Withdrawals

Bitso's Withdrawal Service enables you to wire funds from the USD stablecoin balance of your account and receive the funds in a US-based bank account in fiat dollars. You receive USD at a 1:1 ratio from the USD Stablecoin Crypto Exchange.

Only registered bank accounts of onboarded business clients can receive wires from your Bitso account. For a high-level view of the wiring flow, read the section, Wiring Flows, and 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 wire withdrawal flow:

• Step 3: Make the withdrawal.
• Step 4: Track your withdrawal.

🚧

Fees

Regardless of the drawn-out amount, any wire transfer of USD 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 the section, Transferring U.S. Dollars Via Wire.

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.
• currency: The currency to withdraw using the available balance.
• external_account_id: The ID of the internal wire account created. The register account call returns this ID in the variable id.
• 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: a to z (lower and uppercase), 0 to 9, underscore, _, and dash, -. Maximum length = 40 characters, so a UUID is a valid value. Formerly, this field was called client_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. Possible values: wire.
• wire_message: Any instructions you want to give to the bank receiving the transfer. This message has strict rules around its format. You can have at most three lines (separated by the Newline ASCII character, \n), and each line can have a maximum length of 35 characters, considering the two Newline characters. The system rejects the transfer if your request does not meet this standard.

The following object exemplifies the body parameters included in the HTTP request to wire funds to a US-based account. The variable external_account_id specifies the account ID returned when you registered your bank account:

{
  "asset":"usd",
  "currency":"usd",
  "protocol":"wire",
  "amount":"200",
  "external_account_id":"9b86976d-03d5-40b5-a867-d76b83d75de1",
  "origin_id":"bitso_b864bb09faff",
  "wire_message": "Hello bank, this is my message.\nThese are my instructions."
}

Withdrawal Request's Response

A successful withdrawal of funds returns the object shown below:

{
    "success": true,
    "payload": {
        "wid": "ff94f7d7d034321896d3935ba88fa466",
        "status": "pending",
        "created_at": "2023-08-15T18:49:26+00:00",
        "currency": "usd",
        "method": "bridge",
        "method_name": "Bridge",
        "amount": "215.2",
        "asset": "usd",
        "network": "bridge",
        "protocol": "wire",
        "integration": "bridge",
        "details": {
            "origin_id": "bitso_b864bb09faff"
        }
    }
}

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": "f00be43c45e193140e1e7117bf58d363",
            "status": "pending",
            "created_at": "2023-08-05T00:08:58+00:00",
            "currency": "usd",
            "method": "bridge",
            "method_name": "Bridge",
            "amount": "35.02",
            "asset": "usd",
            "network": "bridge",
            "protocol": "wire",
            "integration": "bridge",
            "details": {
                "origin_id": "bitso_e864bb09fa6d",
                "imad": "20230807ABCD12345678",
                "omad": "20230807ABCD12345678",
                "beneficiary_name": "Satoshi Nakamoto",
                "beneficiary_bank": "Chase Bank",
                "beneficiary_account_number": "2334",
                "beneficiary_bank_routing_number": "021000021",
                "wire_message": "Hello bank, this is a test!"
            }
        }
    ]
}