TradingJuno
Guides

Webhooks

Get started listening to webhook events from your Bitso account

🚧

Deprecated

This subscription API is deprecated. Create and manage subscriptions with the Webhooks API. Payload shapes on this page remain valid.

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

To consume the webhook, set up and register with Bitso a callback URL where the webhook will deliver automatic updates on pending transactions. When a supported event changes its status, the webhook sends a notification via an HTTP POST method with the corresponding payload, documented below.

📘

Not Possible to Select Events

You cannot choose a specific event type to subscribe to. If you set up a callback URL, then the service sends a notification for each supported event.

📘

Event Delivery Guidelines

  • The system does not guarantee the order of event delivery, so events may arrive out of sequence.
  • The system may deliver the same event multiple times.

After the URL receives the update, you must store it and process it later. Callback URLs that take more than five seconds to respond time out.

URL Registration

🚧

Deprecated

This registration endpoint is deprecated. Use the Webhooks API to create and manage subscriptions. See Create webhook subscriptions.

To register your callback URL, make the following HTTP call with the corresponding body parameter:

POST https://bitso.com/api/v3/webhooks

Body Parameters

  • callback_url: Specifies the URL that receives the status data the service sends when the state of a withdrawal or deposit changes in your account.

A successful registration sends back the following response body:

{
    "success": true,
    "payload": "Successfully registered URL: <callback_url>"
}

The registered URL must be accessible from the public web so that the webhooks can post the updates. Then, consider ways to secure the connection.

Funding Payload

If you register a callback URL, then when a deposit occurs, the webhook posts a JSON object that includes the following fields:

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.

String

created_at

The date and time when the service created the funding.

String

ISO 8601 timestamp

currency

The currency of the received amount.

String

details

The funding's specific details, the fields included vary depending on the funding method.

JSON object

event

The type of event reported.
Possible values: funding, withdrawal, and dynamic_qr_code.

String

fid

The funding's unique identifier.

String

integration

The specific integration that enables Bitso to connect to the given network.

String

method

The method used for this funding, such as praxis, pixstark, btc, eth, and the like.

String

method_name

The method's long name

String

network

The payment network through which the deposit is processed.

String

protocol

The specific mechanism, protocol, or standard used in the network.

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

The following shows samples of the payload the service sends to the callback URL when a deposit is made into your account directly or via a dynamic QR code:

{
  "event": "funding",
  "payload": {
    "fid": "7e4d8ade7af52735768b46961fe132",
    "status": "complete",
    "created_at": "2025-04-07T19:40:48+00:00",
    "currency": "usd",
    "method": "sol_spl",
    "method_name": "Solana SPL",
    "amount": "1.00000000",
    "asset": "usdc",
    "network": "solana",
    "protocol": "spl",
    "integration": "fblocks-v1",
    "details": {
      "receiving_address": "hx3FWiGvT6syeNvQvvh83S6rD***",
      "sending_address": "0x4ee44Fa73C4534C4Bb61a06DD28Bd0aA49d***",
      "tx_hash": "3oN7HwKbsP4ckwHK8RKmdcy88YNhBuLyLJuvaSHLBnzc3***",
      "confirmations": "0",
      "tx_url": "https://solscan.io/tx/3oN7HwKbsP4ckwHK8RKmdcy88YNhBuLyLJuvaSHLBnzc3***"
    }
  }
}
{
   "event":"funding",
   "payload":{
      "fid":"037c4c00e17c592fc7b6d9bad2261be8",
      "status":"complete",
      "created_at":"2023-05-17T23:12:00+00:00",
      "currency":"mxn",
      "method":"praxis",
      "method_name":"SPEI Transfer",
      "amount":"100.00",
      "asset":"mxn",
      "network":"spei",
      "protocol":"clabe",
      "integration":"praxis",
      "details":{
         "sender_name":"DARTH VADER",
         "sender_clabe":"*****0606032******",
         "sender_bank":"40329",
         "clave":"885364",
         "clave_rastreo":"2023051740014BMOV0000495448940",
         "numeric_reference":"2043562",
         "concepto":"PRUEBA DEPOSITO",
         "cep_link":""
      }
   }
}
{
  "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": "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"
  }
}
{
  "fid": "1439b301c0a1f473ddb1253e345a3879",
  "status": "complete",
  "created_at": "2025-02-05T17:30:27+00:00",
  "currency": "ars",
  "method": "bind",
  "method_name": "Transferencia Bancaria",
  "amount": "5200000.00",
  "asset": "ars",
  "network": "coelsa",
  "protocol": "cvu",
  "integration": "bind",
  "fee": "0.000",
  "details": {
    "sender_name": "SENDER NAME",
    "sender_cuitcuil": "99000999000",
    "sender_address": "0000009999999999999999",
    "sender_scheme": "CBU",
    "sender_bank": "322",
    "transfer_summary": "VAR"
  }
}
📘

Nvio CLABE Bitso Transfer®

For the deposit payload, see Webhook Notifications.

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.

String

created_at

The date and time when the service created the withdrawal.

String

ISO 8601 timestamp

currency

The currency of the amount sent.

String

details

The withdrawal's specific details, the fields included vary depending on the withdrawal method.

JSON object

event

The type of event reported. Possible values: funding, withdrawal, and dynamic_qr_code.

String

fail_reason

The details object includes this parameter only when an MXN or COP withdrawal fails. It stores the reason for failing. Failure causes are numerous, including invalid ID, non-existent or invalid bank codes, insufficient balance, non-existent, cancelled, or blocked accounts, accounts that do not belong to the sender, surpassed transaction or balance limits, missing mandatory information, and incorrect accounts, operations, or payment types.

String

integration

The specific integration that enables Bitso to connect to the payment gateway used.

String

method

The method used for this withdrawal, such as praxis, pixstark, btc, eth, and the like.

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 the network.

String

status

The withdrawal's status.
Possible values: Pending, Processing, Complete, and Failed.

String

wid

The withdrawal's unique identifier.

String

The following shows samples of the payload the service sends to the callback URL when a withdrawal is made from your account:

{
   "event":"withdrawal",
   "payload":{
      "wid":"p4u8d7f0768ee91d3b33bee6483132i8",
      "status":"complete",
      "created_at":"2017-07-09T19:22:38+00:00",
      "currency":"xrp",
      "method":"rp",
      "method_name":"Ripple",
      "amount":"57",
      "asset":"xrp",
      "network":"rp",
      "protocol":"ripple",
      "integration":"rippled",
      "details":{
         "address":"*******LK5R5Am25ArfXFmqg**********",
         "destination_tag":"64136557",
         "ripple_transaction_hash":"33EA42FC7A06F062A7B843AF4DC7C0AB00D6644DFDF4C5D354A87C035813D321"
      }
   }
}
{
  "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
    }
  }
}
{
  "wid": "0e10e397d6ee27fc6105fa62b86f6e6e",
  "status": "complete",
  "created_at": "2025-02-05T18:15:01+00:00",
  "currency": "ars",
  "method": "bind",
  "method_name": "Transferencia Bancaria",
  "amount": "31492.90",
  "asset": "ars",
  "network": "coelsa",
  "protocol": "cvu",
  "integration": "bind",
  "details": {
    "origin_id": "bitso_1738779301397",
    "cvu": "0000009999999999999999",
    "description": "BITSO_COMPLETE_TRANS"
  }
}
📘

Nvio CLABE Bitso Transfer®

For the withdrawal payload, see Webhook Notifications.

Best Practices for Using Webhooks

Follow these best practices to keep your webhook endpoint secure and reliable:

  • Handle Duplicate Events – Avoid Double Processing: Webhooks may send the same event multiple times, so managing potential duplicates is crucial. To prevent issues like double spending or duplicate credits, always verify both the transaction's final status and its unique transaction identifier. This verification ensures that each event is processed only once.
  • Process Events Asynchronously: Use an asynchronous queue instead of handling events synchronously. This approach prevents scalability issues, especially during traffic spikes, ensuring your endpoint's hosting infrastructure remains stable.
  • Acknowledge Events Quickly: Respond with a 2xx status code immediately upon receiving an event. Perform complex operations after acknowledging the event to avoid timeouts and lost events.
  • Validate Events Using IPs: Allow only webhook requests from trusted sources by adding the provided IP addresses to an allowlist:
EnvironmentIP Addresses
Stage3.129.233.228
3.22.247.241
3.134.133.168
Production52.15.91.227
18.216.72.107
18.219.140.132

Updated about 2 months ago

Did this page help you?