Deposit Notifications

The Multi-CLABE API provides a webhook to send your application real-time status data about funding events.

Subscribe to funding with Create webhook subscriptions. See Managing Subscriptions, Webhook Signatures, and Best Practices. For any deposit status changes that occur, 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 a deposit event occurs into any of the CLABEs linked to your account, the webhook posts a JSON object that represents a deposit and includes the following fields in the payload object:

Field Name	Description	Type	Units
`amount`	The number of funds deposited.	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 funded amount.	String
`details`	The specific funding details. See its description in the table below.	JSON Object
`fid`	The funding's unique identifier provided by Bitso.	String
`integration`	The specific integration that enables Bitso to connect to the given network.	String
`method`	The method used for this funding.	String
`method_name`	The method's long name.	String
`network`	The payment network through which the deposit is processed.	String
`protocol`	A specific mechanism, protocol, or standard used in a network.	String
`status`	The funding's standing. Possible values: Pending, Complete, and Failed.	String

The details JSON object contains specific information about the sender and recipient of the transferred funds. It includes the following fields:

Field Name	Description	Type
`cep_link`	The link to download the transaction's electronic receipt issued by BANXICO. A document for informative purposes to back up the realization of the payment.	String
`clave`	The deposit's ID provided by the PRAXIS provider.	String
`clave_rastreo`	The deposit's ID assigned by BANXICO.	String
`concepto`	An alpha-numeric description of the deposit.	String
`deposit_type`	Indicates whether it is a third-party deposit.	String
`numeric_reference`	An identification number the sender provides that can be used to filter transactions—for example, a date.	String
`receive_clabe`	The CLABE that received the deposit. NOTE:This field is named `receiver_clabe` in the API's endpoints.	String
`sender_bank`	The code of the financial institution that sent the deposit.	String
`sender_clabe`	The CLABE that sent the deposit.	String
`sender_name`	Name of the person or institution that sent the deposit.	String
`sender_rfc_curp`	The Registro Federal de Contribuyentes (taxpayer ID number) or Clave Única de Registro de Población (population registration code) of the person or institution sending the deposit.	String

📘
Important Guidelines

We don't guarantee the order of event delivery. Your application should be able to process events that may arrive out of sequence.

The same event might be delivered multiple times. Your application must be idempotent to handle this possibility.

Your endpoint must respond in under five seconds to avoid a timeout. For best performance, we recommend storing the notification and processing it asynchronously.

Introducing new data fields into the JSON response payloads is considered backward-compatible. Ensure your integration gracefully handles new, unexpected fields without errors.

The following shows a sample of the payload the service sends to the callback URL when a funding is made into your account:

[
   {
      "createdAt":"2023-07-11T04:40:12.719Z",
      "name":"Clyde Gulgowski",
      "avatar":"https://cloudflare-ipfs.com/ipfs/Qmd3W5DuhgHirLHGVixi6V76LhCkZUz6pnFt5AJBiyvHye/avatar/702.jpg",
      "id":"1",
      "event":"funding",
      "payload":{
         "fid":"b55e46e2049f694ae53745f4274fdcac",
         "status":"complete",
         "created_at":"2023-07-11T18:52:57+00:00",
         "currency":"mxn",
         "method":"praxis",
         "method_name":"Transferencia SPEI",
         "amount":"9.00",
         "asset":"mxn",
         "network":"spei",
         "protocol":"clabe",
         "integration":"praxis",
         "details":{
            "sender_name":"DARTH VADER              ",
            "sender_clabe":"012180015040777777",
            "receive_clabe":"710969000022222222",
            "sender_bank":41072,
            "clave":1295751,
            "clave_rastreo":"MBAN01002307110098799999",
            "numeric_reference":"1107230",
            "concepto":"prueba webhook",
            "cep_link": "https://www.banxico.org.mx/cep/go?i=90710&s=20220211&d=t6xfisX3hGxosiKQsTiB8dunM2FJK0lX6PV6oV6bLKezKXxZT1GeLjcZ1w8y7iQcttc8URyNIbEahSE59hqYYQQtTkaIkV2DQxZjgAHbKFY%3D",
            "sender_rfc_curp": "TEST841212AB1",
            "deposit_type": "",
            "payment_id": "clientPaymentIdStage3"
         }
      }
   }
]

{
    "createdAt": "2025-03-05T02:13:09.507Z",
    "name": "Travis Tillman",
    "avatar": "https://cloudflare-ipfs.com/ipfs/Qmd3W5DuhgHirLHGVixi6V76LhCkZUz6pnFt5AJBiyvHye/avatar/1021.jpg",
    "id": "92",
    "event": "funding",
    "payload": {
        "fid": "34455ea39d8b4f619433a14d1e2c4272",
        "status": "failed",
        "created_at": "2025-03-05T13:15:02+00:00",
        "currency": "mxn",
        "method": "praxis",
        "method_name": "SPEI Transfer",
        "amount": "1002",
        "asset": "mxn",
        "network": "spei",
        "protocol": "clabe",
        "integration": "praxis",
        "details": {
            "sender_name": "Sender Name",
            "sender_clabe": "810969000000065751",
            "receive_clabe": "710969000000182951",
            "sender_bank": "97810",
            "clave": "1741180502",
            "clave_rastreo": "TESTSPEI492021741180502338",
            "numeric_reference": "1",
            "concepto": "Payment Reason",
            "cep_link": "",
            "sender_rfc_curp": "ND",
            "deposit_type": "",
            "multiclabe_validation_error": "DEPOSIT_MAXIMUM_OPERATION_AMOUNT_EXCEEDED"
        }
    }
}

Refund Deposit Payload Details

When a withdrawal you made is rejected by the other bank the money is returned to your account and a refund deposit is created. The following details are added when the deposit is a refund to facilitate its reconciliation:

origin_wid: It is the wid of the withdrawal that has been refunded.
origin_client_id: It is the origin_id used for the withdrawal that has been refunded.
clave_rastreo_origen: It is the tracking key (SPEI clave de rastreo) of the withdrawal that has been refunded.