Create a Pix Withdrawal

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:

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.
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:

Parameter Name	Description	Type	Required / Optional
`identifier`	The beneficiary's specific details. See the table below for its description.	object	Required
`taxonomy`	The withdrawal's taxonomy. See the table below for its description.	object	Required

The identifier object includes the following parameters:

Parameter Name	Description	Type	Required / Optional
`pix_key`	The address key of the payee's account or wallet.	string	Required
`pix_key_type`	The specific type of Pix key. Valid values: CPF, CNPJ, PHONE, EMAIL, EVP.	string	Optional

The taxonomy object includes the following parameters:

Parameter Name	Description	Type	Required / Optional
`currency`	The currency to withdraw using the available balance. Valid value: brl.	string	Required
`protocol`	The specific mechanism, protocol, or standard used in the network. Valid value: pix_ind	string	Required

Outbound Reversal Differences in the Request Body Parameters

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

Parameter Name	Description	Type	Required / Optional
`refund_id`	The ID of the pay-in (deposit) you want to revert. The `fid` field stores this value. For further details about the `fid` field, refer to the section, Create a Dynamic QR Code.	string	Required

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:

Parameter Name	Description	Type
`error`	Contains error details when the call fails. See the table below for its description.	object
`payload`	Contains the account and payment information. See the table below for its description.	object
`success`	Flag that indicates whether the call was successful.	Boolean

The error object contains the following parameters:

Parameter Name	Description	Type
`code`	The error code	string
`message`	An explanation of the error	string

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

Parameter Name	Description	Type
`account_information`	An array that lists the account details to be verified. See the table below for its description.	array
`identifier`	The beneficiary's specific details to be verified. See the table in the Preview - Request Body Parameters section for its description.	object
`payment_information`	The payment details to be verified. See the table below for its description.	object

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

Parameter Name	Description	Type
`name`	Identifier of the piece of information stored in `value`.	string
`value`	The value of the information identified by `name`.	string

The payment_information object includes the following parameters:

Parameter Name	Description	Type
`amount`	The amount to be withdrawn. Not yet specified. You specify it in the request body of the confirm call.	string
`end_to_end_id`	An end-to-end identifier, which is unique to each transaction. You must include this ID in the request body of the confirm call.	string
`first_schedulable_time`	Starting date and time when the withdrawal can be scheduled, ISO 8601 format.	string (timestamp)

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:

Parameter Name	Description	Type	Required / Optional
`amount`	The amount to be withdrawn. This value should be a positive number representing the monetary amount to be deducted from the Bitso account.	string	Required
`end_to_end_id`	An end-to-end identifier, which is unique to each transaction. The `preview` call returns it.	string	Required
`currency`	The currency to withdraw using the available balance. Valid value: brl.	string	Required
`origin_id`	A client-generated unique value, which the server uses to recognize subsequent retries of the same request. This idempotency key helps prevent duplicate 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.	string	Optional
`payer_message`	A message the payer can send in the transaction.	string	Optional
`payee_tax_id`	The payee's personal or business taxpayer ID. In Brazil they are named CPF or CNPJ. Note: This parameter is mandatory for API users who are merchants. If omitted, the service rejects the transaction.	string	Optional (see Note)
`protocol`	The specific mechanism, protocol, or standard used in the network. Valid value: pix_ind.	string	Required

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:

Parameter Name	Description	Type
`error`	Contains error details when the call fails. See the table in the Preview - Response Body Parameters section for its description.	object
`payload`	Contains the payment data. See the table below for its description.	object
`success`	Flag that indicates whether the call was successful.	Boolean

The payload object includes the following parameters:

Parameter Name	Description	Type
`amount`	The amount sent in BRL.	string
`asset`	The digital asset in a network. In this case, it is the same as `currency`.	string
`created_at`	The date and time when the service created the withdrawal, ISO 8601 format.	string (timestamp)
`currency`	The currency of the withdrawn amount.	string
`details`	The withdrawal's specific details. See the table below for its description.	object
`integration`	The specific integration that enables Bitso to connect to the payment gateway used.	string
`method`	The method used to process the withdrawal.	string
`method_name`	The method's long name.	string
`network`	The payment network through which the withdrawal is processed.	string
`protocol`	The specific mechanism, protocol, or standard used in a network.	string
`status`	The withdrawal's status. Possible values: Pending, Processing, Complete, and Failed.	string
`wid`	The withdrawal's unique identifier. This ID is useful for correlating the payment with the transaction notifications delivered by the webhook. It is also useful to track your withdrawal.	string

The details object contains the following parameters:

Parameter Name	Description	Type
`end_to_end_id`	The transaction's unique identifier.	string
`is_reversal`	A flag that indicates whether the transaction is an outbound reversal or a withdrawal.	Boolean
`original_end_to_end_id`	The unique end-to-end identifier of the original reversed transaction (deposit). This parameter is only part of the payload in outbound reversals.	string
`payee`	A JSON object that includes the payee's data. The key-value pairs are self explanatory.	object
`payer`	A JSON object that includes the payer's data. The key-value pairs are self explanatory.	object