List Rejected Transactions

Recall that deposits and one-time payments are different entities in the context of the Multi-CLABE API, so the word transactions includes these two concepts. The underlying operation of a one-time payment is a deposit. Still, the API manages the transaction as payment and considers the transfers of funds into your created CLABEs as deposits.

The method GET spei/v1/rejected_transactions retrieves a paginated, filtered list of rejected deposits and one-time payments that rapidly lets you know why the service rejected the transaction. Rejections can occur for the following reasons:

• CLABE_DISABLED: The account holder has the control to turn the CLABE off, setting it temporarily inactive to receive deposits.
• CLABE_BLOCKED: For security reasons or non-payment for the service, a Bitso operator has blocked the CLABE, making it temporarily unavailable for deposits.
• MINIMUM_LIMIT_AMOUNT: The end user attempted to deposit an amount that falls below the minimum limit set for the CLABE.
• DEPOSIT_MAXIMUM_XXXXX_AMOUNT_EXCEEDED: The amount the end user tried to deposit exceeds the account limits, which can be of various types: per transaction (operation), daily, weekly, and monthly limits.
• INVALID_PAYMENT_AMOUNT: The amount the end user tried to pay for a one-time payment does not match the expected amount.
• EXPIRED_PAYMENT: The end user tried to complete a one-time payment past the CLABE's expiration date.
• PAYMENT_ALREADY_COMPLETED: The end user attempted to transfer funds for a one-time payment that had already been paid.

Then, every failed deposit to a created CLABE or a failed one-time payment to a system-controlled CLABE stores a rejected transaction record, which includes the transaction data and the reason for rejecting it. A set of query parameters enables you to filter your search through these records.

If you are subscribed to the rejected-transaction webhook, you receive real-time notifications that enable immediate feedback about the transactions the service rejects.

To retrieve a filtered list of rejected transactions, send the following HTTP request with the relevant query parameters. Note that the URL given is for the stage environment:

GET https://stage.bitso.com/spei/v1/rejected_transactions

When you do not specify any query parameters, the endpoint sets the default values for page number and page size, 1 and 25, respectively, and returns up to 25 of the most recent rejected transactions, sorted from most to least recent.

The following table summarizes the query parameters you can use in a filtered search. You can combine them to create your filter.

The following payload depicts the search results obtained on the specified filter, showing only some elements.

GET https://stage.bitso.com/spei/v1/rejected_transactions?end_date=2024-11-25&start_date=2024-09-04

{
    "success": true,
    "payload": {
        "total_items": "35",
        "total_pages": "2",
        "current_page": "1",
        "page_size": "25",
        "response": [
            {
                "sender_clabe": "810969000000065751",
                "receiver_clabe": "710969000000309624",
                "clabe_type": "MANAGED",
                "amount": "222",
                "clave_rastreo": "TESTSPEI492021732574773329",
                "payment_id": "bf3d19a6",
                “currency”: “mxn”,
                "reason": "PAYMENT_ALREADY_COMPLETED",
                "created_at": "2024-11-25T22:46:13"
            },
            {
                "sender_clabe": "810969000000065751",
                "receiver_clabe": "710969000000287199",
                "clabe_type": "ADDITIONAL_INTERNATIONAL",
                "amount": "0.1",
                "clave_rastreo": "TESTSPEI492021732573945866",
                "payment_id": null,
                “currency”: “mxn”,
                "reason": "MINIMUM_LIMIT_AMOUNT",
                "created_at": "2024-11-25T22:32:25"
            },
            {
                "sender_clabe": "810969000000065751",
                "receiver_clabe": "710969000000303086",
                "clabe_type": "MANAGED",
                "amount": "222",
                "clave_rastreo": "TESTSPEI492021732564620393",
                "payment_id": "63a366e5-534d-44d2-a7d0-ed2212ae38c9",
                "reason": "INVALID_PAYMENT_AMOUNT",
                "created_at": "2024-11-25T19:57:00"
            },
            {
                "sender_clabe": "810969000000065751",
                "receiver_clabe": "710969000000303086",
                "clabe_type": "MANAGED",
                "amount": "111",
                "clave_rastreo": "TESTSPEI492021731595672084",
                "payment_id": "bf3d19a1",
                “currency”: “mxn”,
                "reason": "EXPIRED_PAYMENT",
                "created_at": "2024-11-14T14:47:52"
            }
        ]
    }
}