Withdrawing MXN

Your Bitso account provides three different SPEI®-based (Sistema de Pagos Electrónicos Interbancarios) methods to withdraw MXN and disburse them using the Mexican local banking network free of fees:

• SPEI Bank Transfer: Send funds to any Mexican bank account.
• SPEI Bank Transfer - Debit Card: Send funds to any Mexican debit card.
• SPEI Bank Transfer - Mobile Number: Send funds to any mobile number. The number must be registered for SPEI Transfers with the corresponding bank.

Transactions are usually immediate during banking hours for most banks. However, some might take up to 24 hours. Nvio Pagos México operates the transactions.

Making a Withdrawal

In each of the methods explained above, you can withdraw your funds in two different ways depending on whether the receiving account is created in Bitso's system:

• Providing the receiving account's data: You have not created the account, so you must also specify the transaction's taxonomy in the request.
• Providing the receiving account's ID: You have previously set up the account, so the system retrieves the transaction's taxonomy from the stored account.

Recall that every withdrawal is associated with a taxonomy that identifies a currency, a method, and an integration with a payment gateway. When the account is not created, you must specify this metadata in the request body, which includes: currency and protocol.

To determine the specific values of these taxonomy parameters for the currency you want to withdraw, make an HTTP call to the endpoint below, which retrieves the withdrawal methods for the currency at hand, in this case, mxn. It is optional to make this call in every transaction. Taxonomy parameters rarely change, and Bitso will provide an official communication if changes are needed.

GET https://api-stage.bitso.com/v3/withdrawal_methods/{currency}

If you send your withdrawn funds to a Debit Card or Phone Number, then another piece of information you must specify in your request for an uncreated account is the bank's code that holds the receiving account. To determine the code you need, make an HTTP call to the following endpoint, which retrieves the codes assigned to banks of a particular country, in this case, mx:

GET https://stage.bitso.com/api/v3/banks/{country}

📘

Country Codes

The path parameter country follows the code standard ISO 3166-1 alpha-2.

🚀 You're now ready to make your transaction. To execute a withdrawal for either a created or uncreated account, complete the following HTTP request using the appropriate body parameters:

POST https://api-stage.bitso.com/v3/withdrawals

Body Parameters

• amount: The amount to be withdrawn in MXN. This value should be a positive number representing the monetary amount to be deducted from the Bitso account.
• beneficiary: The recipient of the withdrawn funds.
• clabe: The unique, 18-number identifier of the receiving bank account that follows the Mexican standard for account numbering (Clave Bancaria Estandarizada). In the case of the Debit Card method, it stores the card number, and in the case of the Phone Number, it holds the mobile phone number. Be aware that Bitso only validates that the given CLABE has a valid format and has no means to validate whether it exists. If the provided CLABE clears the format validation, then the money is sent to the recipient bank, and it is this bank's responsibility to reject the payment in case the CLABE does not exist.
• contact_id: The Bitso-generated, unique identifier of your receiving account. You get this identifier back when you create the contact account.
• currency: The currency to withdraw using the available balance. Valid value: mxn.
• institution_code: The identifier of the bank that holds the receiving account.
• max_fee: The maximum fee that the user is willing to pay for the transaction. This parameter is more helpful in crypto transactions where the volatility of blockchain fees can cause fees to be larger than the withdrawn amount. Setting a limit prevents high transaction fees.
• notes_ref: An alpha-numeric description of the withdrawal, maximum length 40 characters.
• numeric_ref: The withdrawal's numeric reference is an identification number the sender provides that is useful to filter transactions—for example, a date. It has a maximum length of seven digits.
• origin_id: A client-generated unique value that the server uses to recognize subsequent retries of the same request. This idempotency key helps prevent duplicated 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. Formerly, this field was called client_withdrawal_id, a name now deprecated and must not be used.
• protocol: A specific mechanism, protocol, or standard used in a network. Valid values: clabe, debitcard, and phonenum.
• rfc: The beneficiary's taxpayer identification number (Registro Federal de Causantes).

📘

Required and Optional Parameters of the Request Body

The examples in the following sections show optional and required fields in the request bodies. However, if you want to use only the required fields in your call, then revise the information returned by the endpoint /withdrawal_methods/mxn to identify each method's required and optional fields. The following JSON snippets show examples of the three SPEI methods. Anyhow, you must always send in your request the taxonomy-related parameters:currency and protocol.

{
            "method": "praxis",
            "name": "CLABE",
            "integration": "praxis",
            "sub_method": null,
            "method_name": "CLABE",
            "network_name": "Bank",
            "channel_name": "Bank",
            "network_description": "CLABE or Debit Card No fees",
            "network": "spei",
            "protocol": "clabe",
            "required_fields": [
                "beneficiary",
                "clabe"
            ],
            "optional_fields": [
                "sender_rfc",
                "rfc",
                "bank_code",
                "origin_id",
                "client_withdrawal_id",
                "max_fee",
                "notes_ref",
                "numeric_ref"
            ]
}

{
            "method": "praxis",
            "name": "Debit card",
            "integration": "praxis",
            "sub_method": null,
            "method_name": "Debit card",
            "network_name": "Bank",
            "channel_name": "Bank",
            "network_description": "CLABE or Debit Card No fees",
            "network": "spei",
            "protocol": "debitcard",
            "required_fields": [
                "beneficiary",
                "clabe",
                "institution_code"
            ],
            "optional_fields": [
                "sender_rfc",
                "rfc",
                "bank_code",
                "notes_ref",
                "numeric_ref",
                "origin_id",
                "client_withdrawal_id",
                "max_fee"
            ],
}

{ 
            "method": "praxis",
            "name": "Mobile number",
            "integration": "praxis",
            "sub_method": null,
            "method_name": "Mobile number",
            "network_name": "Bank",
            "channel_name": "Bank",
            "network_description": "CLABE or Debit Card <br> No fees",
            "network": "spei",
            "protocol": "phonenum",
            "required_fields": [
                "beneficiary",
                "clabe",
                "institution_code"
            ],
            "optional_fields": [
                "sender_rfc",
                "rfc",
                "bank_code",
                "notes_ref",
                "numeric_ref",
                "origin_id",
                "client_withdrawal_id",
                "max_fee"
            ]
}

Withdrawal Requests Providing the Account's Data

The following objects exemplify the body parameters included in the HTTP request when the receiving account is not stored in the system:

{
  "currency":"mxn",
  "protocol":"clabe",
  "amount":"50",
  "numeric_ref":"1234567",
  "notes_ref":"Pago servicios",
  "rfc":"PESJ590317IG4",
  "clabe":"646180110400000007",
  "beneficiary":"Juan Pérez",
  "origin_id":"bitso_c661dcdbf9e2" 
}

{
   "currency":"mxn",
   "protocol":"debitcard",
   "amount":"50",
   "numeric_ref":"5678123",
   "notes_ref":"Pago de servicios",
   "rfc":"PESJ590317IG4",
   "institution_code":"40002",
   "clabe":"5482347403740547",
   "beneficiary":"Juan Pérez",
   "origin_id":"bitso_0261817e9fc0" 
}

{
   "currency":"mxn",  
   "protocol":"phonenum",
   "amount":"50",
   "numeric_ref":"7890123",
   "notes_ref":"Pago servicios",
   "rfc":"PEST790317IG4",
   "institution_code":"40106",
   "beneficiary":"Tolentino Pérez",
   "clabe":"8180833954",
   "origin_id":"bitso_ae827fd4d571"
}

Withdrawal Requests Providing the Account's ID

The request objects shown below exemplify the body parameters used when you have already created the account. They include the variable contact_id, returned by the create account call. Recall that the system stores the transaction's taxonomy and the account's data when you set up the account.

If you don't have the contact ID, then retrieve your contacts list or do a filtered search. For more details, see the section, Retrieve Your Accounts List.

{
   "amount":"50",
   "contact_id":859,
   "numeric_ref":"1234567",
   "notes_ref":"Pago servicios",
   "rfc":"PESJ590317IG4",
   "origin_id":"bitso_7d37598b9605"
}

{
   "amount":"50",
   "contact_id":839,
   "numeric_ref":"5678123",
   "notes_ref":"Pago servicios",
   "rfc":"PESJ590317IG4",
   "origin_id":"bitso_bca3899a4e34"
}

{
   "amount":"50",
   "contact_id":840,
   "numeric_ref":"7890123",
   "notes_ref":"Pago servicios",
   "rfc":"PEST790317IG4",
   "origin_id":"bitso_4fe8c9a7e265"
}

Withdrawal Request's Response

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, you can download its CEP 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 the create withdrawal call includes the variable wid, which stores the transaction's Bitso-supplied unique identifier. This ID can help you track your transaction by making the following HTTP call, which returns detailed information on a user's funds withdrawal:

GET https://api-stage.bitso.com/v3/withdrawals/{wid}

If you do not specify a withdrawal identifier, then it lists all your withdrawals. You can visit Filter Your MXN Withdrawal Search to learn how to retrieve MXN withdrawals with SPEI®-specific query parameters. Another means to do a filtered search is the general-purpose endpoint Listing Withdrawals, which offers a generic set of query parameters.

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 your wallet, so it has created the transaction and has set this initial status.
• PROCESSING: Bitso sent the withdrawal to the financial institution and received a successful acknowledgement. This economic entity is processing the transaction and has not validated it yet.
• COMPLETE: The financial institution validated the withdrawal; the funds are now in the target wallet or account.
• FAILED: The system could not complete the withdrawal; the funds remain in the original wallet or account. When a withdrawal fails, the response object returned by the /withdrawals endpoint includes the fail_reason parameter in the details object, which explains why it failed. Fail reasons are numerous; refer to Table 1 - Reasons for Failed Withdrawals for further information.

The following response objects exemplify the details retrieval for a specific successful withdrawal and the payload returned for an unsuccessful one:

{
    "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.

Table 1. Reasons for Failed Withdrawals