Withdrawals SEPA Transfers
Bitso's Withdrawal Service enables you to transfer funds from your USD stablecoin balance to an external SEPA-enabled bank account, receiving the funds in EUR at the current exchange rate.
Only registered bank accounts of onboarded business clients can receive SEPA transfers from your Bitso account. For details on customer onboarding (Step 1) and bank account registration (Step 2), see the sections, Customer Onboarding and Registering Your Bank Account respectively.
The article presently in view drills into the following steps of the withdrawal flow:
- Step 3: Make the withdrawal.
- Step 4: Track your withdrawal.
FeesRegardless of the drawn-out amount, any off-ramp causes a fixed and a variable fee, which Bitso always deducts from your account's USD stablecoin balance.
Hence, ensure your balance is enough to fund the payout and associated fee. Otherwise, the API throws an insufficient funds error and does not execute the withdrawal.
For further details on fees, transactions' settling time, terms and conditions, and limitations, refer to your Account Manager, [email protected], or Customer Support, [email protected].
Making a Withdrawal
Each withdrawal is associated with a taxonomy that identifies a currency, a method, and an integration with a payment gateway. You must specify this metadata in the request body of the withdrawal call, which includes: asset, currency, and protocol.
🚀 To withdraw USD stablecoin funds from your Bitso account, complete the following HTTP request using the appropriate body parameters:
POST https://api-stage.bitso.com/v3/withdrawals
Body Parameters
amount: The amount to be withdrawn in USD stablecoins. This value should be a positive number representing the monetary amount to be deducted from the Bitso account.asset: The digital asset transferred in a network. In most cases, it is the same as the withdrawal currency. Valid value:usd.currency: The currency to withdraw using the available balance. Valid value:usd.external_account_id: The ID that represents your external bank account in Bitso's systems. The register account call returns this ID in the variableid.max_fee: The maximum fee that the user is willing to pay for the transaction. This parameter is more helpful in crypto transactions where the volatility of blockchain fees can cause fees to be larger than the withdrawn amount. Setting a limit prevents high transaction fees.origin_id: A client-generated unique value that the server uses to recognize subsequent retries of the same request. This idempotency key helps prevent duplicated withdrawals from being processed. Valid character set:atoz(lower and uppercase),0to9, and underscore,_. Dash,-, is not supported. Maximum length = 40 characters. Formerly, this field was calledclient_withdrawal_id, a name now deprecated and must not be used.protocol: A specific mechanism, protocol, or standard used in a network to transfer funds. Valid value:sepa.sepa_message: Any instructions you want to send to the bank receiving the funds. This message has a strict format. If specified, it must be between 6 and 140 characters. The supported characters area-z,A-Z,0-9, spaces, ampersand (&), hyphen (-), period (.), and slash (/). If your request does not meet this standard, the service rejects it.
The following request object exemplifies an HTTP request to transfer funds to a SEPA-enabled account. The property external_account_id specifies the account ID returned when you registered your bank account:
{
"asset":"usd",
"currency":"usd",
"protocol":"sepa",
"amount":"5",
"external_account_id":"9b86976d-03d5-40b5-a867-d76b83d75de1",
"origin_id":"sepa_b864bb091234",
"sepa_message": "Hello bank, this is my sepa message. These are my instructions."
}Withdrawal Request's Response
A successful withdrawal of funds returns the object shown below:
{
"success": true,
"payload": {
"wid": "7f5326c87e1c1a1f29a3f09a6aff6f4b",
"status": "pending",
"created_at": "2025-04-02T18:44:25+00:00",
"currency": "usd",
"method": "bridgesepa",
"method_name": "Bridge SEPA",
"amount": "5.00",
"asset": "usd",
"network": "sepa",
"protocol": "sepa",
"integration": "bridge",
"details": {
"origin_id": "sepa_b864bb091234"
}
}
}Getting a Withdrawal Status
The payload returned by the create withdrawal call includes the variable wid, which stores the transaction's identifier. This ID can help you track your transaction by making the following HTTP call, which returns detailed information on a user's funds withdrawal:
GET https://api-stage.bitso.com/v3/withdrawals/{wid}
If you do not specify a withdrawal identifier, then it lists all your withdrawals. Visit Listing Withdrawals to learn other ways to filter your search using query parameters.
Another variable in the payload is status, which reports the withdrawal's state. Withdrawals can be in one of four possible states:
- PENDING: Bitso is currently validating and processing the withdrawal request and has not sent the transaction to the target financial institution. The system found enough balance to fund the payout from your wallet, so it has created the transaction and has set this initial status.
- PROCESSING: Bitso sent the withdrawal to our partner fintech. This entity is processing the transaction and has yet to validate it.
- COMPLETE: The financial institution validated the withdrawal; the funds are now in the target wallet or account.
- FAILED: The system could not complete the withdrawal; the funds remain in the original wallet or account.
The following response object exemplifies the details retrieval for a specific withdrawal:
{
"success": true,
"payload": [
{
"wid": "7f5326c87e1c1a1f29a3f09a6aff6f4b",
"status": "complete",
"created_at": "2025-04-01T19:12:22+00:00",
"currency": "usd",
"method": "bridgesepa",
"method_name": "Bridge SEPA",
"amount": "5.00",
"asset": "usd",
"network": "sepa",
"protocol": "sepa",
"integration": "bridge",
"details": {
"origin_id": "bitso_891debcea266"
},
"legal_operation_entity": {
"name": "Bitso International",
"country_code_iso_2": "GI",
"image_id": "bitso"
}
}
]
}Updated 8 months ago