SPEI

（payProduct=15）

Payment Process

1. The user places an order on the merchant's website and selects SPEI for payment;

2. The merchant initiates an SPEI payment request to Supefina;

3. Supefina returns the payment reference (CLABE account) information; When "checkOut" is "true", it will return the cashier page with the CRABE account number, and when "checkOut" is "false", it will only return the CRABE account number;

4. The merchant will show the payment reference (CRABE account) to the user;

5. The user copies the payment reference (CLABE account number);

6. The user opens the bank APP and selects the transfer, and enters the copied payment reference (CRABE account number) and amount to complete the transfer;

7. Supefina notifies the merchant that the order is successful.

The address of the request

The name of the environment	URL
SandBox	POST https://api.supefina.tech/api/supefina/transactions/payin
Formal environment	POST https://api.supefina.net/api/supefina/transactions/payin

Request parameters

Request header

Key	Value
Content-Type	application/json

Request body

Variable name	type	Required	description
countryId	String	Yes	Country number Reference: Dictionary table - country number Mexico: MEX
currency	String	Yes	Currency Reference: Dictionary Table - Currency Mexican Peso: MXN
payProduct	String	Yes	Payment type SPEI：15
maxOrderAmount	String	No	Maximum order value The order amount must be greater than or equal to
minOrderAmount	String	No	Minimum order value It must be less than or equal to the order amount It is recommended to pass 00.00
orderAmount	String	Yes	The amount of the order 1. When the order amount (maximum and minimum) is not incoming, the user payment will verify the orderAmount, and if the user's payment amount is not equal to the orderAmount, the payment will be rejected. 2. If the order amount (maximum and minimum) is incoming, the amount of the interval will be verified. 3. The unit peso, which needs to be divided into decimal places, supports two decimal places. 4. If the order amount orderAmount, repeat, maxOrderAmount, and minOrderAmount parameters are used, and the payment amount does not meet the parameter requirements and the transaction is rejected, the channel will charge a fixed handling fee of 6 pesos, and the merchant shall bear the handling fee caused by the transaction rejection, please consider carefully.
repeat	Boolean	Yes	Whether Clabe is reused true: has been used multiple times false: a single use
merId	String	Yes	Merchant ID Merchant ID acquisition path: Supefina Merchant Background - Merchant Management - Basic Information - Merchant ID
merOrderNo	String	Yes	Merchant order number
nonceStr	String	Yes	Random strings The length cannot exceed 32 bits
callbackUrl	String	No	Callback address For details, see Notification Callbacks
sign	String	Yes	signature For details, please refer to: Signature algorithm

Sample request

{
    "callbackUrl": "https://test.com",
    "countryId": "MEX",
    "currency": "MXN",
    "maxOrderAmount": "15000.00",
    "merId": "8302636872670229",
    "merOrderNo": "P1790641845848850466",
    "minOrderAmount": "10.00",
    "nonceStr": "1q5e7zgnbi4fvo9wqhtkpdbuk7fjson1",
    "orderAmount": "30",
    "payProduct": "15",
    "repeat": true,
    "sign": "5764FA39A22135F41F27FCB88EE28DEB"
}

Response parameters

变量名	类型	描述
code	String	Response coding For details, see Response Status Code
data	Object	Response data
amount	BigDecimal	The amount of the order
channelName	String	Clabe's bank
identifier	String	Payment reference identifier Clabe
merCode	String	Merchant ID
merOrderNo	String	Merchant order number
transactionStatus	String	Order status Whether the initiation status of the order is successful or not has nothing to do with the real transaction status of the order. 00: The order is successful 04: Failed to place an order
url	String	Transaction links
msg	String	Response description

Sample response

{
    "code": "200",
    "data": {
        "amount": 30,
        "channelName": "ARCUS",
        "identifier": "706180968985601627",
        "merCode": "8302636872670229",
        "merOrderNo": "P1790641845848850466",
        "transactionStatus": "00",
        "url": "https://h5.supefina.net/clabe?token=45i1YayxSq4f3zQ="
    },
    "msg": "success "
}

Callback notifications

Submission method：POST

Variable name	type	description
payerName	String	Payer's Name
payerAccount	String	Payer's Account Number
amount	String	The amount of the order
countryId	String	Country number Reference: Dictionary table - country number Mexico: MEX
fee	String	Advance handling fee will be charged
identifier	String	Payment Reference Clabe
merId	String	Merchant ID
merOrderId	String	Merchant order number
msg	String	Response description
nonceStr	String	Random strings The length cannot exceed 32 bits
realityAmount	String	Paid-in amount
realityFee	String	Actual handling fee
reference	String	identifier
sign	String	signature
status	String	Transaction status For details, please refer to: Dictionary Table - Trading Order Status
successTime	Date	The time at which the transaction was successful UTC time
supefinaOrderId	String	Supefina order number
transactionType	String	The type of transaction 01: Payin 02: Payout

An example of a callback notification

{
    "payerName": "TEST",
    "payerAccount": "646150996402711110",
    "amount": "30.00",
    "countryId": "MEX",
    "fee": "3.30",
    "identifier": "706180968985601627",
    "merId": "8302636872670229",
    "merOrderId": "P1790641845848850466",
    "msg": "SUCCESS",
    "nonceStr": "03aeeb11-0ad8-42dd-9f00-be1aae",
    "realityAmount": "30.00",
    "realityFee": "3.30",
    "reference": "3843CP03202405190062858560",
    "sign": "27C5933E426DD7A9EABD5C9D50F6BEBE",
    "status": "01",
    "successTime": 1715757366244,
    "supefinaOrderId": "202405150301469d1e0b38e7fdc46",
    "transactionType": "01"
}

Callback notification response

After the merchant successfully receives the callback, it needs to return the specified string synchronously: SUCCESS does not return or returns other content by default, and the notification fails As:

public String test(){
	return "SUCCESS";
}

note

After the user pays the payment, the payment system will send the relevant payment result to the merchant in the form of a data stream, and the merchant needs to receive and process it and return a reply according to the document specification.

1. The same notification may be sent to the merchant system multiple times. The merchant system must be able to handle duplicate notifications correctly.

2. When the background notification is interacted, if the payment system receives the merchant's reply that does not meet the specifications or times out, the payment system will judge that the notification fails and resend the notification (in the case that the notification has been unsuccessful, the payment system will launch multiple notifications in total, and the notification frequency is 0min/3min/6min/9min/12min), but the payment system does not guarantee that the notification will be successful in the end.

3. If the order status is unclear or the payment result is not notified, it is recommended that the merchant call the [Query API] to confirm the order status.

4. Duplicate payments, there are multiple payments in SPEI, please be aware of the situation where multiple payment notifications are received. For multiple payments, Supefina will create multiple orders and notify the merchant multiple times, and the merchant can determine whether it is the same order through the supefinaOrderId in the notification. The identifier remains unchanged when making multiple payments, and the supefinaOrderId and reference are different each time (HSBC banks have multiple payments with the same reference)