🇲🇽Mexico

（Multiple payment method integration）

Currently supported payment products

1. Cash

2. SPEI

3. Card

Payment process (please refer to the document in the collection list for the process of specific payment methods)

1. The user places an order and pays on the merchant's website.

2. The merchant initiates an API payment request to Supefina.

3. Supefina returns aggregate cashier address and associated tracking number data.

4. The user selects the relevant payment method and makes the payment operation at the cashier.

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

The address of the request

The name of the environment	URL
SandBox	POST http://8.130.9.219:8899/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
merOrderNo	String	Yes	Merchant order number
countryId	String	Yes	Country number Reference: Dictionary table - country number Mexico: MEX
customerName	String	Yes	Customer's name
orderAmount	BigDecimal	Yes	The amount of the order (only fixed payment is supported). 1. If the amount paid by the user is inconsistent with the amount of the order, we will carry out the relevant refund operation, and if the refund cannot be made, we will contact the relevant operation. 2. If the user makes a payment outside the validity period of the cashier, we will also make a refund, and if the refund is not possible, we will contact the relevant operation. 3. Please note that the refund operation will charge a fee for different payment methods. 4. The amount of the fee can be reached by contacting the operator.
merId	String	Yes	Merchant ID Merchant ID acquisition path: Supefina Merchant Background - Merchant Management - Basic Information - Merchant I
currency	String	Yes	Currency Reference: Dictionary Table - Currency Mexican Peso：MXN
checkOut	Boolean	Yes	Pull aggregate checkout conditions In this mode, only true is supported
description	String	Yes	Payment-related descriptions
nonceStr	String	Yes	Random strings The length cannot exceed 32 bits
sign	String	Yes	signature For details, please refer to: Signature algorithm
payProduct	String	No	Payment type If not, pull the cashier of all payment methods under the merchant configuration. If a payment method is in, only the corresponding payment method will be displayed at the cashier. Note: If there is no configured payment method in the incoming payment at this time, an exception message will be returned.
callbackUrl	String	No	Callback address For details, see Notification Callbacks
expireTimeL	Long	No	Cashier expiration time (in seconds) 1. If you don't pass in the default 12H 2. If the incoming time is less than 3 minutes or more than 7 days, we will also default to 12H
requestData	Object	No	Additional parameters Note: If the merchant has configured a Cash payment method, this parameter must be passed.
businessUnit	Object	Yes	Business Units
name	String	Yes	The name of the business unit
key	String	Yes	A unique identifier for a business unit
showHtmlFlag	String	Yes	Display the HTML payment page Receipts page URL：1
repeat	Boolean	No	Whether Clabe is reused Note: If payProduct is specified as 15 (SPEI), this parameter must be passed true：has been used multiple times
productName	String	Yes	The title of the product The maximum number of characters is 50 If the merchant has configured a card payment method, this parameter must be transmitted
email	String	No	Customer's email address 3-256 characters If the merchant has configured a card payment method, this parameter must be transmitted
receiverAddressMain	String	No	Address, street 0-50 characters If the merchant has configured a card payment method, this parameter must be transmitted
receiverAddressExtra	String	No	Address, community, house number 0-50 characters If the merchant has configured a card payment method, this parameter must be transmitted
receiverCity	String	No	Recipient city 0-50 characters, can include spaces, hyphens, apostrophes, commas, and dots If the merchant has configured a card payment method, this parameter must be transmitted
receiverProvince	String	No	收The recipient's province 0-40 characters Parameter：https://en.wikipedia.org/wiki/ISO_3166-2 Example: NY If the merchant has configured a card payment method, this parameter must be transmitted
receiverCountry	String	No	Recipient country Reference：Dictionary Table - Country Number Example: BRA If the merchant has configured a card payment method, this parameter must be transmitted
receiverZipCode	String	No	Zip code 0-12 letters or numbers If the merchant has configured a card payment method, this parameter must be transmitted
receiverPhone	String	No	Recipient's phone 5-20 characters, add area code. For example: [phone] If the merchant has configured a card payment method, this parameter must be transmitted

Sample request

1. Activate all payment methods - do not pass in payProduct

{
    "merOrderNo": "20240920195501",
    "sign": "xxxx",
    "requestData": {
        "businessUnit": {
            "key": "11",
            "name": "123456"
        },
        "showHtmlFlag": "1"
    },
    "countryId": "MEX",
    "nonceStr": "20240920195501",
    "customerName": "xx",
    "orderAmount": 100,
    "merId": "xxxxx",
    "checkOut": "true",
    "currency": "MXN",
    "callbackUrl": "xxxx",
    "productName": "test1",
    "email": "xxxx",
    "receiverAddressMain": "xxxx",
    "receiverAddressExtra": "xx",
    "receiverCity": "xxxx",
    "receiverCountry": "MEX",
    "receiverPhone": "+86123456789012345",
    "receiverProvince": "Example city",
    "receiverZipCode": "xxx",
    "description": "supefina",
    "expireTimeL": 3600
}

1. Partial payment methods (Cash and SPEI) are activated - no payProduct is passed

{
    "merOrderNo": "20240920195501",
    "sign": "xxxx",
    "requestData": {
        "businessUnit": {
            "key": "1098345673212",
            "name": "epay"
        },
        "showHtmlFlag": "1"
    },
    "countryId": "MEX",
    "nonceStr": "20240920195501",
    "customerName": "xxx",
    "orderAmount": 100,
    "merId": "xxxxx",
    "checkOut": "true",
    "currency": "MXN",
    "callbackUrl": "xxxx",
    "description": "supefina",
    "expireTimeL": 3600
}

1. Activate some payment methods (Cash and Card) - do not pass in payProduct

{
    "merOrderNo": "20240920195501",
    "sign": "xxxx",
    "requestData": {
        "businessUnit": {
            "key": "11",
            "name": "123456"
        },
        "showHtmlFlag": "1"
    },
    "countryId": "MEX",
    "nonceStr": "20240920195501",
    "customerName": "xx",
    "orderAmount": 100,
    "merId": "xxxxx",
    "checkOut": "true",
    "currency": "MXN",
    "callbackUrl": "xxxx",
    "productName": "test1",
    "email": "xxxx",
    "receiverAddressMain": "xxxx",
    "receiverAddressExtra": "xx",
    "receiverCity": "xxxx",
    "receiverCountry": "MEX",
    "receiverPhone": "+86123456789012345",
    "receiverProvince": "Example city",
    "receiverZipCode": "xxx",
    "description": "supefina",
    "expireTimeL": 3600
}

1. Pass in the specified payment method

• payProduct：03

{
    "merOrderNo": "20240920195501",
    "sign": "xxxxxx",
    "requestData": {
        "businessUnit": {
            "key": "111",
            "name": "123456"
        },
        "showHtmlFlag": "1"
    },
    "payProduct":"03",
    "countryId": "MEX",
    "nonceStr": "20240920195501",
    "customerName": "xxx",
    "orderAmount": 100,
    "merId": "xxxxx",
    "checkOut": "true",
    "currency": "MXN",
    "callbackUrl": "xxxxxx",
    "description": "supefina",
    "expireTimeL": 3600
}

• payProduct：15

{
    "merOrderNo": "20240920195501",
    "sign": "xxxxx",
    "payProduct":"15",
    "repeat":true,
    "countryId": "MEX",
    "nonceStr": "20240920195501",
    "customerName": "xxxx",
    "orderAmount": 100,
    "merId": "xxxxx",
    "checkOut": "true",
    "currency": "MXN",
    "callbackUrl": "xxxxxx",
    "description": "supefina",
    "expireTimeL": 3600
}

• payProduct：18

{
    "merOrderNo": "20240920195501",
    "sign": "xxxxxxx",
    "payProduct":"18",
    "countryId": "MEX",
    "nonceStr": "20240920195501",
    "customerName": "xxxx",
    "orderAmount": 100,
    "merId": "xxxxx",
    "checkOut": "true",
    "currency": "MXN",
    "callbackUrl": "xxxxx",
    "productName": "test1",
    "email": "xxxxxx",
    "receiverAddressMain": "xxxxxx",
    "receiverAddressExtra": "xxxxx",
    "receiverCity": "Example city",
    "receiverCountry": "MEX",
    "receiverPhone": "+86123456789012345",
    "receiverProvince": "Example city",
    "receiverZipCode": "xxxxx",
    "description": "supefina",
    "expireTimeL": 3600
}

Response parameters

Variable name	type	description
code	String	Response coding For details, see Response Status Code
msg	String	Response description
data	Object	Response data
merCode	String	Merchant ID
merOrderNo	String	Merchant order number
supefinaOrderNo	String	Supefina order number
amount	BigDecimal	The amount of the order
url	String	Transaction links
currency	String	Currency

Example of Response - Success

{
    "code": "200",
    "msg": "success ",
    "data": {
        "merCode": "xxxxx",
        "merOrderNo": "20240920195501",
        "supefinaOrderNo": "2025011877286055912513536",
        "amount": 100,
        "url": "http://h5.supefina.tech/combineCashier?token=3eeec61dc9544b41b9086e953b52571c",
        "currency": "MXN"
    }
}

Example response - Failed

{
    "code": "400",
    "msg": "param error : requestData is null"
}

Callback Notification - Submission Method：POST

Variable name	type	description
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

An example of a callback notification

{
    "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";
}