Receive a One-Time Payment
The POST /spei/v1/payments method enables you to request a CLABE for a one-time SPEI® payment. This Multi-CLABE API feature allows your client application to provide a smooth payment experience by generating a single CLABE (with expiration date) and admitting a unique, client-supplied payment ID for each transaction, streamlining your reconciliation of incoming payments. The service sends real-time notifications for completed payments.
The following sub-sections detail relevant aspects of how the endpoint works.
Possible Users
To access this endpoint, new users must complete the onboarding process for the Multi-CLABE API. Existing users can seamlessly integrate it into their existing applications and APIs.
CLABE Type
The Multi-CLABE API links a pool of one-time payment CLABEs to every account. However, the service manages them exclusively. You cannot assign or use these CLABEs for other purposes, turn them off or on, or set a minimum deposit limit to them (via the endpoint PUT /spei/v1/clabes/{clabe}/limits). These CLABEs are of type MANAGED, and the service does not support using CLABEs of any other kind for one-time payments.
Exclusive Linkage
When the system assigns a CLABE to a payment, it remains exclusively linked to that payment until the end user transfers the funds or until its expiration date. This prevents any other deposits from being made to this CLABE.
Amount Validation
The One-Time Payment feature provides an amount validation layer that ensures the received amount matches the expected payment amount, preventing crediting incorrect amounts. This means your end user must deposit the exact amount you specify when requesting the CLABE. Otherwise, the service rejects the payment and triggers a notification via the rejected transaction webhook.
Requesting a CLABE
To request a CLABE for a one-time payment, send the following HTTP request with the indicated body parameters (Note that the URL given is for the stage environment):
POST https://stage.bitso.com/spei/v1/payments
Body Parameters
amount: The amount in MXN to be paid. This value should be a positive number representing the monetary amount to be deposited into your Bitso account. Recall that your end user must deposit the exact same amount.payer_name: A string value to identify your expected payer. Bitso's funding service reports the actual payer's name when the payment reaches the Completed state.payment_id: A client-supplied value that uniquely identifies the payment. The server uses it to recognize subsequent retries of the same request, which prevents duplicate payments from being processed.
Valid character set:atoz(lower and uppercase),0to9, dash (-), and underscore (_).
Maximum length = 40 characters.
The request object shown below exemplifies the body parameters used:
{
"amount": "200",
"payer_name": "Jane Doe",
"payment_id": "63a36ae5-5344-44d2-a7d0-ed2212ae38c9"
}A successful request returns the following JSON object representing the to-be payment:
{
"success": true,
"payload": {
"payment_id": "63a36ae5-5344-44d2-a7d0-ed2212ae38c9",
"amount": "200",
"payer_name": "Jane Doe",
"expiration_date": "2024-11-09",
"clabe": "710969000000303837",
"beneficiary": "Merchant Services",
"status": "PENDING"
}
}Only the beneficiary returned can receive the payment in the assigned CLABE. One-time payment CLABEs remain available to receive the identified payment for a period of three natural days until 23:59 CST.
Tracking Your Payment
The GET /spei/v1/payments/{payment_id} method enables you to track your expected and received payments and learn their status.
Payments can be in one of three possible states:
- PENDING: The service has assigned a CLABE to the payment, but the end user still needs to complete the deposit. The CLABE is still active. The service rejects any deposit attempt that does not match the expected amount; however, as long as the CLABE remains active, end users can retry as necessary without any consequence. The payment can transition to either of the following two states.
- EXPIRED: The expiration date for the assigned CLABE has passed without a deposit from the end user. As a result, the CLABE no longer accepts any payment attempt. If the end user tries to use an expired CLABE, the system rejects the transaction and triggers a notification via the rejected transaction webhook. To complete the payment, you need to request a new one and assign a new payment ID. The service will provide you with another CLABE. The state is final.
- COMPLETED: The end user made a deposit that matches the specified amount and CLABE. As a result, the system credited the funds to your account balance, identified the deposit with the assigned CLABE and payment ID, and sent a confirmation notification through the webhook. This state is final.
Note that the service delivers webhook notifications only for deposits that reach the COMPLETED state. It does not notify status changes for PENDING or EXPIRED transactions.
To retrieve a payment, send the following HTTP request using the specified path parameter (Note that the URL given is for the stage environment):
GET https://stage.bitso.com/spei/v1/payments/{payment_id}
Path Parameter
payment_id: The client-supplied value that uniquely identified the payment when requesting the CLABE.
The following object exemplifies the response sent back for a not-received-yet but still active payment:
{
"success": true,
"payload": {
"payment_id": "63a36ae5-5344-44d2-a7d0-ed2212ae38c9",
"amount": "200",
"expiration_date": "2024-11-09",
"clabe": "710969000000303837",
"beneficiary": "Merchant Services",
"status": "PENDING",
"details": {
"fid": null,
"tracking_key": null,
"expected_payer_name": null,
"actual_payer_name": null,
"payer_clabe": null,
"payer_bank": null,
"payer_id": null
},
"rejection": null,
"created_at": "2024-11-06T17:25:10",
"updated_at": null
}
}When your end user transfers the funds, the payment status updates, and the payment information is now available in the details object:
{
"success": true,
"payload": {
"payment_id": "63a36ae5-5344-44d2-a7d0-ed2212ae38c9",
"amount": "200",
"expiration_date": "2024-11-09",
"clabe": "710969000000303837",
"beneficiary": "Merchant Services",
"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"
}
}Rejected Payment Attempts
If configured, rejected transactions are reported in real time to the corresponding webhook, providing you with immediate feedback. However, the rejection object plays a crucial role in providing a high-level view of rejected payment attempts. It stores the total number of rejected attempts and the reason for the rejection for only the last one
The service returns the rejection object for all three status values (Pending, Expired, and Completed). It's important to note that the service continues to log rejected attempts until the CLABE is again reassigned to a new payment, even if end users try to transfer funds past the CLABE's expiration date.
The following payload serves as an example of a payment that has had one failed attempt because of an amount mismatch:
{
"success": true,
"payload": {
"payment_id": "63a366e5-534d-44d2-a7d0-ed2212ae38c9",
"amount": "200",
"expiration_date": "2024-11-18",
"clabe": "710969000000303086",
"beneficiary": "TestQA",
"status": "PENDING",
"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-15T15:01:25"
}
}Updated about 1 year ago