This page explains how deposits, withdrawals and exchanges are processed in the Partner API. Understanding this model is essential for building a reliable integration.Validation and Processing#
Every withdrawal and exchange goes through two stages:1.
Validation (immediate) - the request is validated as soon as it is received: balance, amount, precision, recipient and lock. If the request is invalid, you receive an error and no transaction is created.
2.
Processing (asynchronous) - an accepted transaction is created and processed in the background: verification, compliance review, sending to the network or to the bank. Its status changes over time until it reaches a final status.
The most important rule
A 201 response means that the transaction was accepted and created, not that it was completed. The result is known only when the transaction reaches a final status.Transaction Lifecycle#
| Transaction | Created by | Initial status | Final statuses |
|---|
| Crypto withdrawal | Create Crypto Withdrawal | STARTED | SUCCESSFUL, CANCELED, REJECTED-BY-REVIEWER, BANNED |
| SEPA withdrawal | Create SEPA Withdrawal | PENDING | SUCCESSFUL, CANCELED, REJECTED-BY-REVIEWER, BANNED |
| Exchange | Create Exchange | PENDING | SUCCESSFUL, REJECTED-BY-REVIEWER, BANNED |
| Crypto deposit | Incoming blockchain transaction | STARTED | SUCCESSFUL, UNSUCCESSFUL, REJECTED-BY-REVIEWER, BANNED |
| SEPA deposit | Incoming bank transfer | STARTED | SUCCESSFUL, UNSUCCESSFUL, REJECTED-BY-REVIEWER, BANNED |
The meaning of each status is described in the status field of each transaction. For withdrawals, funds are returned to the balance when the withdrawal is CANCELED or REJECTED-BY-REVIEWER. Withdrawals that are not processed within 24 hours are canceled automatically and the funds are returned to the balance.Deposits are not created by your requests - they appear when incoming funds are detected. You learn about them from webhooks or from Get Balance History.A webhook is sent with every status change, so a single transaction can produce several webhook notifications. Use the status field of the latest notification to determine the current state.How to Build a Resilient Integration#
1. Use webhooks
The most efficient method. Webhooks notify you about every status change.2. Poll as a fallback
Call the details endpoint of the transaction and check status until it reaches a final status. Use it also for reconciliation.3. Show the pending state
In your UI, show the transaction as pending until it reaches a final status. Do not mark it as completed after the 201 response.Implementation Pattern#
1.
Send the request and handle validation errors immediately - no transaction is created in this case.
2.
Store the transactionId and externalId from the response.
3.
Mark the transaction as pending in your system.
4.
Wait for the webhook or poll the details endpoint.
5.
Update the final state when the transaction reaches a final status.
If a request times out and you receive no response, the transaction may have been created. Check Get Balance History or wait for the webhook before retrying. Exchanges are protected against duplicates - each lock can be used only once.
