Filter Your MXN Withdrawal Search

The GET spei/v1/withdrawals method returns a paginated list of withdrawals that match specific SPEI® criteria, such as receiver CLABE or clave de rastreo. The search space includes only withdrawals processed through the SPEI® network, and with a Pending, Complete, or Failed status value.

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 withdrawals from your account, sorted from most to least recent.

To retrieve a filtered list of your SPEI® withdrawals, make the following HTTP request:

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

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

Query Parameter	Description	Required /Optional
`end_date`	The ending date of the searched time window, specified in ISO 8601 date format, YYYY-MM-DD (server timezone). It returns withdrawals whose creation date lies within the defined window. Ensure the value of this parameter comes after the value of `start_date`.	Optional
`only_refunds`	A Boolean flag to retrieve only reversed withdrawals. These transactions pair with a refund deposit.	Optional
`origin_id`	A client-generated unique identifier that, when creating a withdrawal, helps prevent duplicated withdrawals from being processed. It helps retrieve a specific transaction in a search. However, a withdrawal might not have it because it is an optional parameter when creating it. In this case, you can retrieve a specific transaction using the `tracking_key` or the `wid`.	Optional
`page`	The page number.	Optional
`page_size`	The number of entries per page, maximum=1000.	Optional
`receiver_clabe`	It enables you to retrieve all the withdrawals sent to a specific external account (CLABE, debit card, or phone number). Not all withdrawals have a CLABE number in this field because the withdrawal creation endpoint also supports sending funds to a debit card or a phone number. In these cases, it stores an obfuscated card number or the mobile phone number.	Optional
`start_date`	The starting date of the searched time window, specified in ISO 8601 date format, YYYY-MM-DD (server timezone). It returns withdrawals whose creation date lies within the defined window. Ensure the value of this parameter comes before the value of `end_date`.	Optional
`timezone`	Specifies a Coordinated Universal Time (UTC) offset that defines a timezone, enabling reporting transaction creation time according to the given timezone. A UTC offset is the difference in hours and minutes between UTC and the standard time at a particular place. UTC offsets range from the westernmost geographies (-12:00) to the easternmost (+14:00) and are a multiple of 15 minutes—however, the majority of times, they are stated in whole hours. Refer to the following list of UTC offsets to search for the ones of your regions of interest. Specify it using the following format: + table , -marizes, and ptional. Default value: 00:00. Examples: Argentina: -03:00 Colombia: -05:00 Sao Paulo: -03:00 The date and time reported in the response for the `created_at` and `updated_at` keys are those of the specified timezone. Consider this conversion when using query parameters `start_date` and `end_date` together with `timezone`. See the Examples section for usage details.
`tracking_key`	You can use this parameter to track a specific withdrawal using its `clave_de_rastreo` value. However, it is especially helpful when searching for a specific refund deposit. Using the tracking key (`clave_de_rastreo`) returned by the webhook for the completed withdrawal, which eventually becomes a reversed withdrawal, you can search for a specific refund deposit. Usually, refund deposits have the same `clave_rastreo` as the reversed withdrawal, so this key enables you to link them. However, exceptions occur when the service receives the refund deposit on a date different from the withdrawal's completion date. In this case, the `clave_de_rastreo` of both transactions does not match. This rarely occurs, but if it's your case, contact our Support Team at [email protected] .	Optional
`wid`	The transaction’s Bitso-supplied unique ID. The create withdrawal endpoint and the webhook report it back.	Optional

Examples

Example 1

The service stores all transactions in UTC but provides the timezone parameter to display their creation dates in a specific time zone. For instance, to retrieve all transactions created on January 20th in Mexico's local time (UTC offset -06:00), configure the query parameters as follows:

GET https://stage.bitso.com/spei/v1/deposits?start_date=2025-01-20&end_date=2025-01-20&timezone=-06:00

This query adjusts the result set and the displayed timestamps based on the provided time zone. For example, a transaction recorded at 2025-01-20T14:38:34 (UTC) will be displayed as 2025-01-20T08:38:34 in the specified time zone (UTC-6). However, a transaction recorded at 2025-01-20T05:00:00 (UTC) is not included in the resulting set because, in the UTC-6 time zone, its creation date is 2025-01-19T23:00:00.

Example 2

The following JSON object exemplifies the response returned. Only reversed withdrawals include the refund_deposit object. In others, it has a null value.

{
    "success": true,
    "payload": {
        "total_items": "1",
        "total_pages": "1",
        "current_page": "1",
        "page_size": "25",
        "response": [
            {
                "wid": "e76f2c84b32394da37d4b74d90b1c66c",
                "status": "failed",
                "created_at": "2024-10-14T15:41:29",
                "currency": "mxn",
                "amount": "165.50",
                "refund_deposit": {
                    "fid": "53b5ed8fb6e6c4df6d35eaba3b0caa31",
                    "deposit_id": "2088270",
                    "sender_clabe": "ND",
                    "receiver_clabe": "710180000000000472",
                    "status": "complete",
                    "amount": "165.50",
                    "currency": "mxn",
                    "details": {
                        "sender_name": "ND",
                        "sender_bank": "810",
                        "clave": "1728736403",
                        "clave_rastreo": "202410149071030060000001493218",
                        "numeric_reference": "1",
                        "concepto": "Pago servicios",
                        "cep_link": "http://www.banxico.org.mx/cep/"
                    },
                    "created_at": "2024-10-14T17:33:27",
                    "updated_at": "2024-10-14T17:33:27"
                },
                "details": {
                    "origin_id": null,
                    "fecha_operation": "20241014",
                    "beneficiary_bank_code": "0",
                    "clave_de_rastreo": "202410149071030060000001493218",
                    "huella_digital": "fbc08914f7fdd69cf13630dd00ef556d61d2901159d582630830bb19845b9bb8",
                    "concepto": "Pago servicios",
                    "beneficiary_name": "Juan Perez",
                    "beneficiary_clabe": "012680924756111643",
                    "numeric_ref": "1234567",
                    "cep_link": "http://www.banxico.org.mx/cep/"
                }
            }
        ]
    }
}