Withdrawing BRL via Pix

Your Bitso account provides a real-time payment method to withdraw BRL funds and disburse them using the Brazilian local banking network:

• Pix Transfer: Pix is Brazil's leading instant payments rail created and managed by the Central Bank of Brazil (BACEN). It provides you with a quick, real-time, and direct way to transfer funds to another individual, company, or the government. It works 24 - 7, including weekends and holidays. To complete a Pix payment, you need the payee's Pix key; a self-generated "nickname" used to identify the payee's transactional account.

Making a Withdrawal

This section explains and exemplifies how to complete a withdrawal and the body parameters included in the HTTP requests. Currently, Pix-based withdrawals to a previously saved account are not supported.

A Pix-based withdrawal is a two-step process:

1. Preview: In Bitso, every withdrawal is associated with a taxonomy that identifies a currency and an integration with a payment gateway. For BRL withdrawals, you must always send the taxonomy parameters currency and protocol in the Preview call. You also configure the specific details of the beneficiary receiving the payout (payee). The service returns the beneficiary data, the beneficiary's account data, and some transaction details for you to verify, POST /v3/withdrawal/preview.
2. Confirm: If you agree with the information returned, you confirm it by posting a withdrawal call whose request body includes the verified information and the amount to withdraw. At this stage, the service creates the transaction, POST /v3/withdrawals.

Outbound Reversals

Outbound reversals are a feature that enables you to refund previously completed pay-ins (deposits). Reversals follow the withdrawal flow, using the same endpoints and procedures.

However, minor differences at the parameter level exist between the flows. These parameter differences enable the service to distinguish between a regular withdrawal and a reversal transaction and appropriately manage the backend operations.

The following sections detail the two steps of the withdrawal flow explaining also the parameter differences that exist between the withdrawal and reversal flows.

1. Preview

To generate the preview of a withdrawal, make an HTTP call to the following endpoint using the indicated body parameters:

POST https://api-stage.bitso.com/v3/withdrawal/preview

Preview - Request Body Parameters

The request body includes the following key-value pairs:

The identifier object includes the following parameters:

The taxonomy object includes the following parameters:

Outbound Reversal Differences in the Request Body Parameters

The identifier object is completely redefined and includes only the following parameter:

The following JSON objects exemplify the request body of a withdrawal preview request and of an outbound reversal call

{
  "taxonomy":{
    "currency":"brl",
    "protocol":"pix_ind"
  },
  "identifier": {
    "pix_key":"1a717532-2ae7-4b11-b1bd-2ff5559f4d52",
    "pix_key_type": "EVP"
  }
  
}

{
  "taxonomy":{
    "currency":"brl",
    "protocol":"pix_ind"
  },
  "identifier": {
    "refund_id":"59efc1328ab3d2f2cdc9e66e82a8dbb8"
  }
  
}

For regular withdrawals, a successful call returns a JSON object representing a withdrawal preview. An outbound reversal call delivers a response body almost identical to that of a withdrawal call. However, a subtle difference exists in the value of the end_to_end_id key: In reversals, the first character of the string starts with the letter D, whereas in withdrawals, it begins with the letter E.

{
    "success": true,
    "payload": {
        "identifier": {
            "pix_key_type": "EVP",
            "pix_key": "1a717532-2ae7-4b11-b1bd-2ff5559f4d52"
        },
        "account_information": [
            {
                "name": "Pix key",
                "value": "788.266.137-61"
            },
            {
                "name": "Recipient",
                "value": "Melinda Spears"
            },
            {
                "name": "Recipient CPF",
                "value": "***.266.137-**"
            },
            {
                "name": "Bank",
                "value": "CC CREDIMATA"
            }
        ],
        "payment_information": {
            "end_to_end_id": "E5111871820240527175900000001517",
            "amount": {
                "properties": [
                    "editable"
                ]
            },
            "first_schedulable_time": "2024-05-28T03:00:00Z"
        }
    }
}

{
    "success": true,
    "payload": {
        "identifier": {
            "refund_id": "59efc1328ab3d2f2cdc9e66e82a8dbb8"
        },
        "account_information": [
            {
                "name": "CNPJ de quien recibe",
                "value": "37.923.210/0001-61"
            },
            {
                "name": "Banco",
                "value": "NVIO BRASIL IP LTDA"
            },
            {
                "name": "Monto original recibido",
                "value": "100 BRL"
            },
            {
                "name": "Nombre del remitente",
                "value": "Joaquin Galindez "
            },
            {
                "name": "Fecha original del depósito",
                "value": "19 jun 2024 4:02:11 p. m."
            }
        ],
        "payment_information": {
            "end_to_end_id": "D3513612020240625191800000004961",
            "amount": {
                "value": "80",
                "properties": [
                    "editable",
                    "refund"
                ]
            },
            "collectable_question": {     <!--- Used in the app's logic, constant value --->
                "question": "Description",
                "hint": "Complete the description"
            }
        }
    }
}

Preview - Response Body Parameters

The response body includes the following key-value pairs:

The error object contains the following parameters:

The payload object includes the following parameters, which are sent back to be verified by the user:

The account_information array includes key-value pairs that specify the account details:

The payment_information object includes the following parameters:

2. Confirm

To confirm the creation of a previewed withdrawal, make an HTTP call to the following endpoint using the indicated body parameters

POST https://api-stage.bitso.com/v3/withdrawals

Confirm - Request Body Parameters

The request body includes the following key-value pairs:

Outbound Reversal Differences in the Request Body Parameters

No differences exist. The request body of reversals includes the same parameters as a withdrawal.

Sample Request Body

The following JSON object exemplifies the request body for confirming a withdrawal:

{
  "protocol": "pix_ind",
  "currency": "brl",
  "amount": "300",
  "end_to_end_id": "E5111871820240527175900000001517",
  "payer_message": "mensagem de teste",
  "payee_tax_id": "12345678901",
  "origin_id": "bitso_a8a508b43b3f"
}

Withdrawal Request Response

A successful confirmation call returns a JSON object that, depending on the use-case, represents a Pix-based withdrawal or an outbound reversal:

{
    "success": true,
    "payload": {
        "wid": "8c97371db260b128d44113ead670069d",
        "status": "pending",
        "created_at": "2024-05-27T17:59:46+00:00",
        "currency": "brl",
        "method": "pixstark",
        "method_name": "Pix",
        "amount": "300",
        "asset": "brl",
        "network": "pix",
        "protocol": "pix_ind",
        "integration": "stark",
        "details": {
            "end_to_end_id": "E3513612020240820164900000006743",
            "payee": {
              "account_number": "131905953",
              "bank_code": "35136120",
              "tax_id": "07898362705",
              "name": "Andres Fagua",
              "bank_name": "NVIO BRASIL IP LTDA"
            },
            "payer": {
              "bank_branch": "0001",
              "account_number": "595169740",
              "tax_id": "39197185000101",
              "name": "test",
              "bank_name": "NVIO BRASIL IP LTDA"
            },
            "is_reversal": false
        }
    }
}

{
    "success": true,
    "payload": {
        "wid": "992fd4b1b6dbf9c464980e61908bc373",
        "status": "pending",
        "created_at": "2024-06-25T19:20:20+00:00",
        "currency": "brl",
        "method": "pixstark",
        "method_name": "Pix",
        "amount": "10",
        "asset": "brl",
        "network": "pix",
        "protocol": "pix_ind",
        "integration": "stark",
        "details": {
            "end_to_end_id": "D3513612020240820162800000006740",
            "payee": {
                "account_number": null,
                "bank_code": "35136120",
                "tax_id": "07898362705",
                "name": "Andres Fagua ",
                "bank_name": "NVIO BRASIL IP LTDA"
            },
            "payer": {
                "bank_branch": "0001",
                "account_number": "595169740",
                "tax_id": "39197185000101",
                "name": "test",
                "bank_name": "NVIO BRASIL IP LTDA"
            },
            "is_reversal": true,
            "original_end_to_end_id": "E3513612020240816162700000006615"
        }
    }
}

Confirm - Response Body Parameters

The response body includes the following key-value pairs:

The payload object includes the following parameters:

The details object contains the following parameters:

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 processing and validating the withdrawal request and has not sent the transaction to the 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 the financial institution and received a successful acknowledgment. This economic entity is processing the transaction and has not validated it yet.
• 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:

{
  "event": "withdrawal",
  "payload": {
    "wid": "91a72aed1b289f9314275c06c40ec317",
    "status": "complete",
    "created_at": "2024-07-09T21:19:23+00:00",
    "currency": "brl",
    "method": "pixstark",
    "method_name": "Pix",
    "amount": "3000",
    "asset": "brl",
    "network": "pix",
    "protocol": "pix_ind",
    "integration": "stark",
    "details": {
      "end_to_end_id": "D3513612020240709211800000005249",
      "payee": {
        "account_number": "Payee's account ID",
        "bank_code": "Code of the institution that holds the payee's account",
        "tax_id": "Payee's taxpayer ID number",
        "name": "Payee's name",
        "bank_name": "Payee's bank name"
      },
      "payer": {
        "account_number": "Payer's account ID",
        "tax_id": "Payer's taxpayer ID number",
        "name": "Payer's name",
        "bank_name": "Payer's bank name"
      },
      "is_reversal": false,
    }
  }
}

📘

The end_to_end_id parameter changes its value in reversals.

In outbound reversals, the value assigned to the end_to_end_id parameter at the moment of transaction creation (pending state) changes when the transaction finishes (complete state). Therefore, to match reversals, rely on the wid identifier until the service settles the transaction.

The details object contains the following parameters: