Create Mock Refund Deposits in MXN

This tutorial guides you through simulating refund deposits over the SPEI® network within the stage testing environment, enabling you to test and refine your MXN reconciliation flows.

A refund deposit is a payment returned to your account after a withdrawal is reversed. Withdrawals can be reversed for various reasons, such as reaching a non-existent, blocked, or canceled account, exceeding the account's monthly limit of allowed deposits, exceeding the account's authorized balance limit, or missing mandatory information to complete the payment.

The webhook sends notifications of refund deposits to your callback URL, if configured, typically using the same tracking key (clave_rastreo) as the original withdrawal that was later reversed. The payload also includes a deposit_type parameter identifying the refund type as either FAIL_WITHDRAWAL_COMPENSATION or REFUND_CREDITED_WITHDRAWAL.

The GET /spei/v1/withdrawals method enables you to customize your search for refund deposits in MXN. For further details, visit the article Filter your MXN Withdrawal Search.

Creation Flow

To create a refund deposit, you must first make a pairing withdrawal. Complete the subsequent flow to create both transactions:

Create a regular withdrawal, POST https://api-stage.bitso.com/v3/withdrawals.

Withdrawal Request Body:

{
  "currency":"mxn",
  "protocol":"clabe",
  "amount":"50",
  "numeric_ref":"1234567",
  "clabe":"646180110400000007",
  "beneficiary":"John Doe",
  "origin_id":"testRefundStageDemo" 
}

A successful transaction returns the following JSON object representing the withdrawal:

Withdrawal Response Body:

{
    "success": true,
    "payload": {
        "wid": "a8b9d30c0efae2d97d5e5dc0bc90cd9e",
        "status": "pending",
        "created_at": "2024-10-28T22:09:03+00:00",
        "currency": "mxn",
        "method": "praxis",
        "method_name": "SPEI Transfer",
        "amount": "50.00",
        "asset": "mxn",
        "network": "spei",
        "protocol": "clabe",
        "integration": "praxis",
        "details": {
            "origin_id": "testRefundStageDemo",
            "fecha_operacion": "",
            "beneficiary_bank_code": "",
            "huella_digital": "",
            "concepto": "nd",
            "beneficiary_name": "John Doe",
            "beneficiary_clabe": "646180110400000007",
            "numeric_ref": "1234567",
            "cep_link": null
        }
    }
}

Wait until your withdrawal reaches a COMPLETE status and locate its assigned clave_de_rastreo. If you initiate a refund deposit before the withdrawal is complete, the service halts the withdrawal, marks it as failed, and skips creating a refund deposit, because reallocating the funds is unnecessary.

You have several options for finding the clave_de_rastreo:

The general-purpose endpoint
GET https://api-stage.bitso.com/v3/withdrawals/{wid}
The SPEI®-dedicated endpoint
GET https://stage.bitso.com/spei/v1/withdrawals?wid=
The webhook notification sent when the withdrawal reaches the COMPLETE status.

The following JSON object shows the response returned by the general-purpose endpoint. The details object contains the clave_de_rastreo parameter:

Search for Withdrawal Response Body:

{
    "success": true,
    "payload": [
        {
            "wid": "a8b9d30c0efae2d97d5e5dc0bc90cd9e",
            "status": "complete",
            "created_at": "2024-10-28T22:09:03+00:00",
            "currency": "mxn",
            "method": "praxis",
            "method_name": "SPEI Transfer",
            "amount": "50.00",
            "asset": "mxn",
            "network": "spei",
            "protocol": "clabe",
            "integration": "praxis",
            "details": {
                "origin_id": "testRefundStageDemo",
                "fecha_operacion": "20230613",
                "beneficiary_bank_code": "90646",
                "clave_de_rastreo": "202410289071005060000004732953",
                "huella_digital": "90f242d102c84208c919e4240ac59b6ccaaa3deb941785fcbe939a1ca3a479a4",
                "concepto": "nd",
                "beneficiary_name": "John Doe",
                "beneficiary_clabe": "646180110400000007",
                "numeric_ref": "1234567",
                "cep_link": "http://www.banxico.org.mx/cep/"
            },
            "legal_operation_entity": {
                "name": "Nvio Pagos Mexico",
                "country_code_iso_2": "MX",
                "image_id": "nvio"
            }
        }
    ]
}

Create a refund deposit taking into account the following considerations for the values of its request body parameters, POST https://stage.bitso.com/spei/test/deposits:
1. amount: Must be the same as the one of the withdrawal you created in Step 1.
2. tracking_key: Must match the value of the clave_de_rastreo parameter from the withdrawal created in Step 1.
3. payment_type: Must equal any of the following integers: 0, 16, 17, 18, 23, or 24, which identify the type of refund the service can create. See Table 1 at the end of the article for further details.
4. receiver_clabe: Must match your MAIN or INTERNATIONAL CLABE.
Create Refund Deposit Request Body:
```
{
   "amount": "50",
   "receiver_clabe": "710969000000196581",
   "receiver_name": "Test",
   "tracking_key": "202410289071005060000004732953",
   "payment_type": "17"
}
```
A successful transaction returns the following JSON object representing the refund deposit:

Create Refund Deposit Response Body:
```
{
    "success": true,
    "payload": {
        "amount": "50",
        "tracking_code": "202410289071005060000004732953",
        "tracking_key": "202410289071005060000004732953",
        "sender_clabe": "",
        "sender_name": "",
        "sender_curp": "",
        "receiver_clabe": "710969000000196581",
        "receiver_name": "Test",
        "receiver_curp": "",
        "created_at": "2024-10-28T22:11:29"
    }
}
```

Verify that the service properly linked the refund deposit to the reversed withdrawal, GET https://stage.bitso.com/spei/v1/withdrawals?only_refunds=true.

The payload's refund_deposit object represents the funding made into your account. The value of the parameter clave_rastreo coincides with that of the parameter clave_de_rastreo contained in the details object that describes the reversed withdrawal.

Search for Refund Deposit Response Body:

{
    "success": true,
    "payload": {
        "total_items": "1",
        "total_pages": "1",
        "current_page": "1",
        "page_size": "25",
        "response": [
            {
                "wid": "a8b9d30c0efae2d97d5e5dc0bc90cd9e",
                "status": "complete",
                "created_at": "2024-10-28T22:09:03",
                "currency": "mxn",
                "amount": "50.00",
                "refund_deposit": {
                    "fid": "c417dc456704435931ed76bbf7ad9c3b",
                    "deposit_id": "4542568",
                    "sender_clabe": "",
                    "receiver_clabe": "710969000000196581",
                    "status": "complete",
                    "amount": "50",
                    "currency": "mxn",
                    "details": {
                        "sender_name": "",
                        "sender_bank": "810",
                        "clave": "1730153489",
                        "clave_rastreo": "202410289071005060000004732953",
                        "numeric_reference": "1",
                        "concepto": "Payment Reason",
                        "cep_link": null
                    },
                    "created_at": "2024-10-28T22:11:29",
                    "updated_at": "2024-10-28T22:11:29"
                },
                "details": {
                    "origin_id": "testRefundStageDemo",
                    "fecha_operacion": "20230613",
                    "beneficiary_bank_code": "90646",
                    "clave_de_rastreo": "202410289071005060000004732953",
                    "huella_digital": "90f242d102c84208c919e4240ac59b6ccaaa3deb941785fcbe939a1ca3a479a4",
                    "concepto": "nd",
                    "beneficiary_name": "John Doe",
                    "beneficiary_clabe": "646180110400000007",
                    "numeric_ref": "1234567",
                    "cep_link": "http://www.banxico.org.mx/cep/"
                }
            }
        ]
    }
}

You can also contact our Customer Service team at [email protected] to ask for a verification of the transaction on the admin dashboard of the stage environment.

If you configure a callback URL in your testing environment, you can verify the webhook notification for the refund deposit.

Webhook Notification:

{
  "event": "funding",
  "payload": {
    "fid": "c417dc456704435931ed76bbf7ad9c3b",
    "status": "complete",
    "created_at": "2024-10-28T22:11:29+00:00",
    "currency": "mxn",
    "method": "praxis",
    "method_name": "Transferencia SPEI",
    "amount": "50",
    "asset": "mxn",
    "network": "spei",
    "protocol": "clabe",
    "integration": "praxis",
    "details": {
      "sender_name": "",
      "sender_clabe": "",
      "receive_clabe": "710969000000196581",
      "sender_bank": 810,
      "clave": 1730153489,
      "clave_rastreo": "202410289071005060000004732953",
      "numeric_reference": "1",
      "concepto": "Payment Reason",
      "cep_link": "",
      "sender_rfc_curp": "",
      "deposit_type": "REFUND_CREDITED_WITHDRAWAL"
    }
  }
}

Refund Types

When a reversed withdrawal occurs, the service tries to reconcile using the reversed withdrawal tracking code, if available, and creates a refund deposit of one of the following types.

Integer	Payment Type
0	Devolución No Acreditada (Not Credited Refund)
16	Devolución Extemporánea No Acreditada (Not Credited Extemporaneous Refund)
17	Devolución Acreditada (Credited Refund)
18	Devolución Extemporánea Acreditada (Credited Extemporaneous Refund)
23	Devolución Especial Acreditada (Credited Special Refund)
24	Devolución Especial Extemporánea Acreditada (Credited Extemporaneous Special Refund)

Table 1. Refund Types