Webhook Notifications

Bitso's Withdrawal and Funding Services provide webhooks to send real-time status data about withdrawal (payout) and funding (pay-in) events in your account.

Subscribe with Create webhook subscriptions. For Pix, pass funding, withdrawal, and dynamic_qr_code in events (any subset). See Managing Subscriptions, Webhook Signatures, and Best Practices.

When a supported event changes its status, the webhook sends a notification via an HTTP POST method with the corresponding payload, documented below.

Funding Payload

If you register a callback URL, then when any of the events listed below occurs, the webhook posts a JSON object representing the event. It includes the fields explained in Table 1:

Direct funding into your account (event type: funding).
Inbound reversal: This transaction refunds a previously completed payout (withdrawal) and follows the deposit flow (event type: funding).
Funding via a dynamic QR code (event type: dynamic_qr_code).

Field Name	Description	Type	Units
`amount`	The amount received in the specified currency. This positive number represents the monetary amount credited to the Bitso account.	String	Currency
`asset`	The digital asset in a network. In most cases, it is the same as `currency`. Supported value: brl	String	Currency
`created_at`	The date and time when the service created the funding.	String	ISO 8601 timestamp
`currency`	The currency of the received amount. Supported value: brl	String
`details`	The funding's specific details, the fields included vary depending on the type of funding: direct deposit, inbound reversal, or deposit via a dynamic QR code. See examples below.	JSON object
`event`	The type of event reported. Supported values: funding and dynamic_qr_code	String
`fid`	The funding's unique identifier.	String
`integration`	The specific integration that enables Bitso to connect to the given payment network. Supported value: stark	String
`method`	The method used for this funding. Supported value: pixstark	String
`method_name`	The method's name. Supported value: Pix	String
`network`	The payment network through which the deposit is processed. Supported value: pix	String
`protocol`	The specific mechanism, protocol, or standard used in the network. Supported value: pix_ind	String
`status`	The funding's status. For the funding event, the supported values are Pending, Complete, and Failed. For the dynamic_qr_code event, the values are CREATED, PAID, and EXPIRED.	String

Table 1. Description of Funding Payload

The response bodies shown below exemplify the payload the service sends to the callback URL when a funding is made into your account directly or via a dynamic QR code.

An inbound reversal payload differs from a direct funding payload in the following ways:

It does not include the payee object.
It includes the original_end_to_end_id field, which is a reference to the end_to_end_id property of the reversed withdrawal. This identifier is useful to correlate or find the original reversed transaction (the withdrawal).

{
  "event": "funding",
  "payload": {
    "fid": "b920261542c54216ab3ad45a9d199f34",
    "status": "complete",
    "created_at": "2024-07-09T18:13:43+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": "E3513612020240709210500000005246",
      "payer": {
           "account_number": "Payer's account ID",
           "bank_code": "Code of the institution that holds the payer's account",
           "bank_name": "Payer's bank name",
           "name": "Payer's name",
           "tax_id": "Payer's taxpayer ID"
      },
      "payee": {
           "account_number": "Payee's account number",
           "bank_code": "Code of the institution that holds the payee's account",
           "name": "Payee's name",
           "tax_id": "Payee's taxpayer ID"
      },
      "is_reversal": false
    }
  }
}

{
  "event": "funding",
  "payload": {
    "fid": "b920261542c54216ab3ad45a9d199f34",
    "status": "complete",
    "created_at": "2024-07-09T18:13:43+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": "D35136120202502031253pn16HHvJdpM",
        "payer": {
            "account_number": "395177626",
            "bank_code": null,
            "bank_name": "BITSO IP LTDA",
            "branch_code": "0001",
            "name": "John Doe",
            "tax_id": "12345678901"
        },
        "is_reversal": true,
        "original_end_to_end_id": "E3513612020250203125000000059372"        
  	}
  }
}

{
  "event": "dynamic_qr_code",
  "payload": {
    "fid": "eb12cc1b2d3141269b8f6fe895ac28fe",
    "payer": {
      "name": "FULL NAME",
      "tax_id": "668XXXX991"
    },
    "status": "EXPIRED",
    "amount": "1000.00",
    "currency": "brl",
    "expires_at": "2024-09-30T18:28:48Z",
    "created_at": "2024-09-30T18:26:18Z",
    "payed_at":"",
    "qr_code_payload": "00020101021226890014br.gov.bcb.pix2567brcode-h.sandbox.starkinfra.com/v2/966a26531a794c54908278cfc63aefcd5204000053039865802BR5910JoseBadano6004CABA62070503***6304C918"
  }
}

Withdrawal Payload

If you register a callback URL, then when a withdrawal occurs, the webhook posts a JSON object representing the transaction and includes the following fields:

Field Name	Description	Type	Units
`amount`	The sent amount in the specified currency. This positive number represents the monetary amount deducted from the Bitso account.	String	Currency
`asset`	The digital asset in a network. In most cases, it is the same as `currency`. Supported value: brl	String
`created_at`	The date and time when the service created the withdrawal.	String	ISO 8601 timestamp
`currency`	The currency of the amount sent. Supported value: brl	String
`details`	The specific data that describes the withdrawal: end-to-end ID, payee's information, payer's data, and Boolean flag to indicate whether it is a reversal. See example below.	JSON object
`event`	The type of event reported. Supported value: withdrawal	String
`integration`	The specific integration that enables Bitso to connect to the payment gateway used. Supported value: stark	String
`method`	The method used for this withdrawal. Supported value: pixstark	String
`method_name`	The method's name. Supported value: Pix	String
`network`	The payment network through which the withdrawal is processed. Supported value: pix	String
`protocol`	The specific mechanism, protocol, or standard used in a network. Supported value: pix_ind	String
`status`	The withdrawal's status. Possible values: Pending, Processing, Complete, and Failed.	String
`wid`	The withdrawal's unique identifier.	String

Table 2. Description of Withdrawal Payload

The following exemplifies the payload sent to the callback URL when a withdrawal is made from your account:

{
  "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": "Bank code for 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,
    }
  }
}