List One-Time Payments
The GET spei/v1/payments method returns a paginated payment list that matches the given query parameters. The search space includes only one-time payments made via MANAGED CLABEs assigned to your account. CLABEs of type MANAGED are the ones the service makes available when you request one-time payments.
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 payments, sorted from most to least recent. The list includes payments that can be COMPLETED, EXPIRED, or PENDING.
This method also supports searching for a specific payment using the payment ID. However, you need to specify it as a path parameter. For more details, refer to the section, Receive a One-time Payment. The article in view focuses on performing a search using query parameters.
To retrieve a filtered list of one-time SPEI® payments, 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/payments
The following table summarizes the query parameters you can use in a filtered search. You can combine them to create your filter.
| Query Parameter | Description | Type | Required / Optional |
|---|---|---|---|
end_date | The ending date of the searched time window, specified in ISO 8601 date format, YYYY-MM-DD (server timezone). It enables returning payments whose creation date lies within the defined window. Ensure the value of this parameter comes after the value of start_date. | String (timestamp) | Optional |
fid | The funding’s Bitso-supplied, unique ID. This ID is available until the end user deposits the funds and the payment reaches the COMPLETED state. It pairs uniquely with a payment ID. If you don't have the fid, search for it using the GET /spei/v1/payments/{payment_id} method. The webhook also reports it back. | String | Optional |
only_rejections | A Boolean flag that, when true, signals to retrieve only payments that have at least one rejection. | Boolean | Optional |
page | The page number. | Integer | Optional |
page_size | The number of entries per page, maximum=100. | Integer | Optional |
start_date | The starting date of the searched time window, specified in ISO 8601 date format, YYYY-MM-DD (server timezone). It enables returning payments whose creation date lies within the defined window. Ensure the value of this parameter comes before the value of end_date. | String (timestamp) | Optional |
status | The current state of the payment. It indicates to search for the payments that match the given value. Valid values: COMPLETED, EXPIRED, and PENDING. | String | Optional |
tracking_key | The payment’s unique clave_de_rastreo. This ID is available until the end user deposits the funds and the payment reaches the COMPLETED state. It pairs uniquely with a payment ID and a fid. If you don't have this key, search for it using the GET /spei/v1/payments/{payment_id} method. The webhook also reports it back. | String | Optional |
The following payload depicts the search results obtained on the specified filter, showing only some elements. The payment details are null because they represent transactions where the end user did not complete the deposit of the funds.
Rejections can occur for various reasons, such as a mismatch between the transferred amount and the expected amount or the CLABE assigned to the payment expiring without a deposit from the end user. For further details on how one-time payments work in Bitso, refer to the section, Receive One-Time Payments.
{
"success": true,
"payload": {
"total_items": "4",
"total_pages": "1",
"current_page": "1",
"page_size": "25",
"response": [
{
"payment_id": "63a366e5-534d-44d2-a7d0-ed2212ae38c9",
"amount": "200",
"expiration_date": "2024-11-18",
"clabe": "710969000000303086",
"beneficiary": "TestQA",
"status": "EXPIRED",
"details": {
"fid": null,
"tracking_key": null,
"expected_payer_name": null,
"actual_payer_name": null,
"payer_clabe": null,
"payer_bank": null,
"payer_id": null
},
"rejection": {
"total_count": "1",
"last_reason": "INVALID_PAYMENT_AMOUNT"
},
"created_at": "2024-11-15T15:00:37",
"updated_at": "2024-11-19T00:00:00"
},
{
"payment_id": "bf3d19a1",
"amount": "111",
"expiration_date": "2024-11-13",
"clabe": "710969000000303086",
"beneficiary": "TestQA",
"status": "EXPIRED",
"details": {
"fid": null,
"tracking_key": null,
"expected_payer_name": null,
"actual_payer_name": null,
"payer_clabe": null,
"payer_bank": null,
"payer_id": null
},
"rejection": {
"total_count": "3",
"last_reason": "EXPIRED_PAYMENT"
},
"created_at": "2024-11-14T14:34:17",
"updated_at": "2024-11-14T14:47:52"
}
]
}
}Whereas, when the search results include COMPLETED payments, the payment details appear:
curl https://stage.bitso.com/spei/v1/payments?end_date=2024-11-19&start_date=2024-08-01&status=COMPLETED
{
"success": true,
"payload": {
"total_items": "11",
"total_pages": "1",
"current_page": "1",
"page_size": "25",
"response": [
{
"payment_id": "bf3d19a2",
"amount": "222",
"expiration_date": "2024-11-17",
"clabe": "710969000000303086",
"beneficiary": "TestQA",
"status": "COMPLETED",
"details": {
"fid": "efc5e52d14ee0a734c47940edd21f75e",
"tracking_key": "TESTSPEI492021731615735909",
"expected_payer_name": "Alice",
"actual_payer_name": "TestQA",
"payer_clabe": "810969000000065751",
"payer_bank": null,
"payer_id": "TEST840812AB0"
},
"rejection": {
"total_count": "1",
"last_reason": "INVALID_PAYMENT_AMOUNT"
},
"created_at": "2024-11-14T14:55:42",
"updated_at": "2024-11-14T20:22:18"
},
{
"payment_id": "63a36ae5-5344-44d2-a7d0-ed2212ae38c9",
"amount": "200",
"expiration_date": "2024-11-09",
"clabe": "710969000000303837",
"beneficiary": "TestQA",
"status": "COMPLETED",
"details": {
"fid": "b3c33aa5b84ec52427219239ecf9aac7",
"tracking_key": "TESTSPEI492021730915032102",
"expected_payer_name": "Jane Doe",
"actual_payer_name": "Sender Name",
"payer_clabe": "810969000000065751",
"payer_bank": null,
"payer_id": "ND"
},
"rejection": null,
"created_at": "2024-11-06T17:25:10",
"updated_at": "2024-11-06T17:43:53"
}
]
}
}Updated about 1 year ago