Response and status

Read an MXN withdrawal and the reasons a completed transfer can fail.

A successful withdrawal of funds returns the response object shown below. See the Getting a Withdrawal Status section for further details in the failed withdrawal response.

{
   "success":true,
   "payload":{
       "wid":"7c28ccfc714940e5274d9fa9a219d479",
       "status":"complete",
       "created_at":"2024-02-14T15:53:39+00:00",
       "currency":"mxn",
       "method":"praxis",
       "method_name":"SPEI Transfer",
       "amount":"200.50",
       "asset":"mxn",
       "network":"spei",
       "protocol":"clabe",
       "integration":"praxis",
       "details":{
          "origin_id":"bitso_812527",
          "fecha_operacion":"0",
          "beneficiary_bank_code":"90661",
          "clave_de_rastreo":"202402149071040080000323032815",
          "huella_digital":"eacb7610bae8cf0d1b38dcb822f88a5142c1c6a7910dc99fbd0c527de475b12d",
          "concepto":"Retiro de saldo",
          "beneficiary_name":"Harry Potter",
          "beneficiary_clabe":"646180110400000007",
          "numeric_ref":"1234",
          "cep_link":"https://www.banxico.org.mx/cep/go?i=90710&s=20220921&d=POpMol2HpeYbNph8fQ4I%2B1NcKisU%2FIjEsRNY1GCl1jtYIta5sXLFTvXZ7Mxmn%2Pp6vv2os2PlQ%2FvHFZ2%2BlzdXJ%2B76YpZNIQAahW7kGiTjtuw%3D"
        }
    }
}

The details object provides a comprehensive description of the transaction. The Body Parameters section above outlines most of its parameters. The following are the ones not included in this list:

  • cep_link: The URL to retrieve the Comprobante Electrónico de Pago (CEP)—the official transaction receipt generated by Banxico for payments processed via the SPEI® network. For any completed SPEI® transfer, its CEP can be downloaded directly from Banxico's CEP portal.
  • clave_de_rastreo: The withdrawal's ID assigned by Banxico.
  • huella_digital: A unique digital fingerprint that Banxico's regulations mandate for each withdrawal. It encodes specific information about the transaction, including the amount, time and date, and sender and receiver identification. This parameter plays a crucial role in ensuring compliance and internal control.

Getting a Withdrawal Status

The payload returned by create includes wid, the transaction's Bitso-supplied identifier. Call Get a withdrawal with that wid.

Call List withdrawals to retrieve withdrawals without a wid. For SPEI® fields that list does not cover, see Filter Your MXN Withdrawal Search.

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 the wallet, so it has created the transaction and has set this initial status.
  • PROCESSING: Bitso sent the withdrawal to the SPEI network and received a successful acknowledgement from Banxico.
  • COMPLETE: The withdrawal has been liquidated in the SPEI network. The funds are now in the receiver bank.
  • FAILED: The system could not complete the withdrawal; the funds remain in the original wallet or account. When a withdrawal fails, the response includes fail_reason in details. See Failed withdrawals. A create call rejected before the withdrawal exists is a different case. See Failed field validations.

The following response objects exemplify the details retrieval for a specific successful withdrawal and the payload returned for an unsuccessful one. These are SPEI withdrawals. An Nvio CLABE cannot be sent on SPEI. Use Nvio CLABE Bitso Transfer®.

{
    "success": true,
    "payload": [
        {
            "wid": "102a583495f6e9b03d2e3974ba0cb8d5",
            "status": "complete",
            "created_at": "2024-05-06T19:09:16+00:00",
            "currency": "mxn",
            "method": "praxis",
            "method_name": "SPEI Transfer",
            "amount": "10.00",
            "asset": "mxn",
            "network": "spei",
            "protocol": "clabe",
            "integration": "praxis",
            "details": {
                "origin_id": "bitso_c661dcdbf9e2ff",
                "fecha_operacion": "0",
                "beneficiary_bank_code": "90646",
                "clave_de_rastreo": "202405069071016060000004309089",
                "huella_digital": "53e2b2af49453c655c4891ceb2b93a435da304f2ca4b8bf6b343daf020a37701",
                "concepto": "Pago servicios",
                "beneficiary_name": "Juan Perez",
                "beneficiary_clabe": "646180110400000007",
                "numeric_ref": "1234",
                "cep_link": "http://www.banxico.org.mx/cep/"
            },
            "legal_operation_entity": {
                "name": "Nvio Pagos Mexico",
                "country_code_iso_2": "MX",
                "image_id": "nvio"
            }
        }
    ]
}
{
   "wid":"fcb09e435e453e0ee69689fbae4abf67",
   "status":"failed",
   "created_at":"2024-04-30T23:04:09+00:00",
   "currency":"mxn",
   "method":"praxis",
   "method_name":"SPEI Transfer",
   "amount":"8795.00",
   "asset":"mxn",
   "network":"spei",
   "protocol":"debitcard",
   "integration":"praxis",
   "details":{
      "origin_id":"8d01c138ce094fc1a6979b1305a99ad5",
      "fecha_operacion":"0",
      "beneficiary_bank_code":"40012",
      "clave_de_rastreo":"202414309071010080000365656412",
      "huella_digital":"cdec0dfd02b49be01da314f6e9aec5cab9d9bf158ac527752857d5480ba3f4b4",
      "concepto":"nd",
      "beneficiary_name":"Satoshi Nakamoto",
      "beneficiary_clabe":"4152313774135702",
      "numeric_ref":"1",
      "cep_link":null,
      "fail_reason":"Excede el l\u00edmite de saldo autorizado de la cuenta (Exceeds the limit of authorized balance in the account)"
   },
   "legal_operation_entity": {
      "name": "Nvio Pagos Mexico",
      "country_code_iso_2": "MX",
      "image_id": "nvio"
   }
}

Failed withdrawals

Table 1 lists why an MXN withdrawal completed via the SPEI® network might fail and whether the service launches a reprocessing when the transaction fails.

Reason (returned in the fail_reason parameter)Reprocess
Clave de institución ordenante no catalogada (The code of the ordering institution is unknown)No
Cuenta bloqueada (Blocked Account)No
Cuenta cancelada (Cancelled Account)No
Cuenta en otra divisa (Account in another currency)No
Cuenta inexistente (Non Existing Account)No
Cuenta no pertenece al Participante Emisor (Account does not belong to Emitter Participant)No
El participante beneficiario está desconectado (The receiving institution is not connected to SPEI®). An institution's connectivity can be confirmed using Banxico's Connection Monitor.No
Estructura de la información adicional incorrecta (Incorrect structure of additional information)No
Excede el límite de abonos permitidos en el mes en la cuenta (Exceeds the limit of allowed deposits in a month of the account)No
Excede el límite de saldo autorizado de la cuenta (Exceeds the limit of authorized balance in the account)No
Falta información mandatoria para completar el pago (Missing mandatory information to complete payment)No
Not mapped errorYes
Tipo de cuenta no corresponde (Account type does not correspond)No
Tipo de operación errónea (Erroneous operation type)No
Tipo de pago erróneo (Erroneous payment type)No

Table 1. Reasons for Failed Withdrawals


Did this page help you?