Payouts via Bitso Transfer®
How to transfer funds between Bitso accounts.
Bitso Transfer® is an instant and commission-free way to send and receive fiat or crypto through
any email or cell phone number that is part of the Bitso community. You won't have to go through
a blockchain or a third party to send or receive Bitso Transfers, eliminating fees.
In Bitso, 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. The taxonomy parameters include asset, currency, method, network, and
protocol.
To determine the specific values of these parameters for the particular currency you want to
withdraw, make an HTTP call to the following endpoint, which retrieves the withdrawal methods
for the currency at hand:
GET https://api-stage.bitso.com/v3/withdrawal_methods/{currency_ticker}
The following JSON snippet exemplifies the response when currency_ticker=mxn.
"payload": [
{
"method": "bt",
"integration": "bt",
"sub_method": null,
"name": "Bitso Transfer",
"method_name": "Bitso Transfer",
"network_name": "Bitso Transfer",
"network_description": "To other Bitso users, immediately without fees.",
"required_fields": [],
"optional_fields": [
"notes",
"refcode",
"email",
"phone",
"emoji",
"origin_id",
"to_client",
"client_withdrawal_id",
"max_fee"
],
"currency_configurations": [
{
"currency": "mxn",
"legal_operating_entity": {
"legal_operation_entity": "Nvio Pagos Mexico",
"country_code": "MX"
},
"fee": {
"amount": "0.00000000",
"type": "fixed"
},
"limits": {
"system_min": "0.01000000",
"system_max": "2000000.00000000",
"tx_limit": "1999790.00000000",
"status": "upgradeable"
},
"asset": "mxn"
}
],
"consumer_contacts_enabled": false,
"method_description": "To other Bitso accounts.",
"network": "bt",
"protocol": "bt",
},When you have configured the taxonomy parameters, you are ready to make your withdrawal. 🚀
To execute a withdrawal, 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 deducted from the Bitso account in MXN.asset: The digital asset in a network. In most cases, it is the same as the withdrawal currency.currency: The currency to withdraw using the available balance.email: The recipient's email address. You can specify the recipient using either their email address or phone number, not both.max_fee: The maximum fee 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.method: The withdrawal method.network: The payment network through which the withdrawal is processed.notes: A 200-character string that enables sending a message to the recipient.origin_id: A client-generated, unique value the server uses to recognize subsequent retries of the same request. This idempotency key helps prevent duplicate withdrawals from being processed. The valid character set isatoz(lower and uppercase),0to9, and underscore,_. Dash,-, is not supported. This field is also namedclient_withdrawal_id, a name now deprecated and must not be used.protocol: A specific mechanism, protocol, or standard used in a network.phone: The recipient’s phone number. You can specify the recipient using either their phone number or their email address, not both. Specify the number starting with the plus sign, for example, "phone": "+573113220448".
Note: Your request must always include the COMPLETE set of taxonomy-related parameters: asset, currency, method, network, and protocol.
The following object exemplifies the body parameters included in the HTTP request :
{
"asset": "mxn",
"currency": "mxn",
"method": "bt",
"network": "bt",
"protocol": "bt",
"amount": "100",
"notes": "ID-Test1234567890",
"origin_id": "Refund-BT12345-12345",
"email": "[email protected]"
}A successful withdrawal of funds returns the response object shown below:
{
"success": true,
"payload": {
"wid": "629e3f04934d89dda4f6ec781facb70a",
"status": "pending",
"created_at": "2024-04-08T20:23:26+00:00",
"currency": "mxn",
"method": "bt",
"method_name": "Bitso Transfer",
"amount": "100.00",
"asset": "mxn",
"network": "bt",
"protocol": "bt",
"integration": "bt",
"details": {
"origin_id": "Refund-BT12345-12345",
"email": "[email protected]",
"phone": null,
"refcode": null,
"recipient_name": null,
"recipient_ref": "togb",
"notes": "ID-Test1234567890",
"emoji": ""
}
}
}Webhook Notifications
Bitso's withdrawal and funding services provide webhooks that send real-time status data about withdrawal and funding events in a Bitso account.
To consume the webhook, subscribe to funding and withdrawal with Create webhook subscriptions. See Managing Subscriptions.
The webhook delivers the following JSON objects (one per each status change) that represent the withdrawal:
{
"event": "withdrawal",
"payload": {
"wid": "629e3f04934d89dda4f6ec781facb70a",
"status": "processing",
"created_at": "2024-04-08T20:23:26+00:00",
"currency": "mxn",
"method": "bt",
"method_name": "Bitso Transfer",
"amount": "100.00",
"asset": "mxn",
"network": "bt",
"protocol": "bt",
"integration": "bt",
"details": {
"origin_id": "Refund-BT12345-12345",
"email": "[email protected]",
"phone": null,
"refcode": null,
"recipient_name": null,
"recipient_ref": "togb",
"notes": "ID-Test1234567890",
"emoji": ""
}
}
}
{
"event": "withdrawal",
"payload": {
"wid": "629e3f04934d89dda4f6ec781facb70a",
"status": "complete",
"created_at": "2024-04-08T20:23:26+00:00",
"currency": "mxn",
"method": "bt",
"method_name": "Bitso Transfer",
"amount": "100.00",
"asset": "mxn",
"network": "bt",
"protocol": "bt",
"integration": "bt",
"details": {
"origin_id": "Refund-BT12345-12345",
"email": "[email protected]",
"phone": null,
"refcode": null,
"recipient_name": "Mycompany",
"recipient_ref": "togb",
"notes": "ID-Test1234567890",
"emoji": ""
}
}
}For a detailed description of the JSON object the webhook delivers, see funding and withdrawal.
Tracking Your Withdrawal
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 withdrawal.
To retrieve a specific transaction, send 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.
The following response object exemplifies the details retrieval for a specific withdrawal:
{
"success": true,
"payload": [
{
"wid": "89af4965c41234ff3ce6406fa6251db6",
"status": "complete",
"created_at": "2024-04-09T00:59:18+00:00",
"currency": "mxn",
"method": "bt",
"method_name": "Bitso Transfer",
"amount": "10.00",
"asset": "mxn",
"network": "bt",
"protocol": "bt",
"integration": "bt",
"details": {
"origin_id": "BT12347-04-08",
"email": null,
"phone": "+573113220448",
"refcode": null,
"recipient_name": "Technology Inc",
"recipient_ref": "scjb",
"notes": "ID-Test-0987654321",
"emoji": ""
},
"legal_operation_entity": {
"name": "Nvio Pagos Mexico",
"country_code_iso_2": "MX",
"image_id": "nvio"
}
}
]
}Updated about 2 months ago