Card

（payProduct=18）

Payment Process

1. The user places an order on the merchant's website/app and selects Card payment;

2. The merchant initiates a card payment request to Supefina;

3. Supefina returns the card payment URL address;

4. The merchant will open the address on the user's side;

5. The user shall verify and pay according to the prompts on the page;

6. The user pays successfully;

7. Supefina will notify the merchant of the payment success information.

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
countryId	String	Yes	Country number Reference: Dictionary table - country number Mexico: MEX
currency	String	Yes	Currency Reference: Dictionary Table - Currency Mexican Peso: MXN
orderAmount	String	Yes	The amount of the order The unit peso, which needs to be divided into decimal places, supports two decimal places
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
payProduct	String	Yes	Payment type Card：18
checkOut	Boolean	Yes	Cash register true: The cashier is required false: The cash register is not required Pass true
returnUrl	Boolean	No	Return address where the payment is complete
callbackUrl	String	No	Callback address For details, see Notification Callbacks
productName	String	Yes	The title of the product The maximum number of characters is 50
productQuantity	Integer	No	The number of units Radius[0,1000]
email	String	No	Customer's email address 3-256 characters The e-commerce industry must be transmitted
receiverAddressMain	String	No	AddAddress, street 0-50 characters The e-commerce industry must be transmitted
receiverAddressExtra	String	No	Address, community, house number 0-50 characters The e-commerce industry must be transmitted
receiverCity	String	No	Recipient city 0-50 characters, can include spaces, hyphens, apostrophes, commas, and dots The e-commerce industry must be transmitted
receiverProvince	String	No	The recipient's province 0-40 characters Parameter：https://en.wikipedia.org/wiki/ISO_3166-2 Example: NY The e-commerce industry must be transmitted
receiverCountry	String	No	Recipient country Reference: Dictionary Table - Country Number Example: BRA The e-commerce industry must be transmitted
receiverZipCode	String	No	Zip code 0-12 letters or numbers The e-commerce industry must be transmitted
receiverPhone	String	No	Recipient's phone 5-20 characters, add area code. For example: [phone] The e-commerce industry must be transmitted
alias	String	No	Username 0-60 characters A must-have for the gaming industry
newUser	Boolean	No	Whether the user is within a month true: a new user false: an existing user A must-have for the gaming industry
hasDispute	Boolean	No	Whether there has been a historical dispute, including any of the following: 1. Taking advantage of cheating tools, game loopholes, etc. to carry out improper behavior; 2. Harassing other players, engaging in malicious behavior, or disrupting the game experience; 3. Players have inappropriate remarks, violate the rules of the game, and are frequently reported; true: There have been false: None A must-have for the gaming industry
hasRefund	Boolean	No	Whether there have been refunds true: There have been false: None A must-have for the gaming industry
hasSingedLong	Boolean	No	Whether the registration period is more than three months true: exceeded false: does not exceed the value of the data A must-have for the gaming industry
sign	String	Yes	signature For details, please refer to: Signature algorithm
customerName	String	Yes	Username
description	String	Yes	description It cannot contain special symbols and should not exceed 200 characters in length

Sample request

{
	"callbackUrl": "https://test.com",
	"checkOut": true,
	"countryId": "MEX",
	"currency": "MXN",
	"merId": "8302858375850055",
	"merOrderNo": "20240509087436S20P0154104514",
	"nonceStr": "555016487033129560298749615154",
	"orderAmount": "200",
	"payProduct": "18",
	"returnUrl": "https://www.bing.com/",
	"productName": "testName",
	"productQuantity": 10,
	"email": "[email protected]",
	"receiverAddressMain": "Sample street 357",
	"receiverAddressExtra": "Apt 2",
	"receiverCity": "Example city",
	"receiverProvince": "Example state",
	"receiverCountry": "MXN",
	"receiverZipCode": "01254",
	"receiverPhone": "1234567890",
	"alias": "test alias",
	"newUser": false,
	"hasDispute": true,
	"hasRefund": false,
	"hasSingedLong": true,
	"sign": "6FD59D9111C58A608147EB05AFC1458E",
	"customerName": "Aaliyah Rogers",
	"description":"Supefina"
}

Response parameters

Variable name	type	description
code	String	Response coding For details, see Response Status Code
data	Object	Response data
amount	BigDecimal	The amount of the order
currency	String	Currency Reference: Dictionary Table - Currency Mexican Peso: MXN
merCode	String	Merchant ID
merOrderNo	String	Merchant order number
url	String	Transaction links
msg	String	Response Information

Sample response

{
    "code": "200",
    "data": {
        "amount": 200,
        "currency": "MXN",
        "merCode": "8302858375850055",
        "merOrderNo": "20240509087436S20P0154104514",
        "url": "https://h5.supefina.net/supefina?token=b3909bfa4683e3443a57"
    },
    "msg": "success "
}

Callback notifications

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
merId	String	Merchant ID
merOrderId	String	Merchant order number
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
supefinaOrderId	String	Supefina order number
transactionType	String	The type of transaction 01: Payin 02: Payout

An example of a callback notification

{
    "amount": "200.00",
    "countryId": "MEX",
    "fee": "11.48",
    "identifier": "078018503",
    "merId": "8302858375850055",
    "merOrderId": "20240509087436S20P0154104514",
    "nonceStr": "f861c17d-64eb-494a-be67-79066b",
    "realityAmount": "200.00",
    "realityFee": "11.48",
    "reference": "0117ed5c-3bce-4d5c-8740-a346ce76e8b4",
    "sign": "8AC0AEB3BF6CC99632C8D7FDF4CED101",
    "status": "01",
    "supefinaOrderId": "202405090301003498176b135384e",
    "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";
}

Test data

The test environment provides full payment functionality, but it is only simulated processing with no actual banking transactions.

You can use the following credit card information to test payments.

Visa

Card PAN	3-D Secure result	Transaction result
4000000000000085	3-D secure version 2, challenge flow, full authentication	Payment has CONFIRMED status
4580000000000059	3-D secure version 2, frictionless flow, attempt	Payment has CONFIRMED status
4000000000000093	3-D secure version 2, frictionless flow, success	Payment has CONFIRMED status

Mastercard

Card PAN	3-D Secure result	Transaction result
5100000000000065	3-D secure version 2, challenge flow, full authentication	Payment has CONFIRMED status
2400000000000069	3-D secure version 2, frictionless flow, attempt	Payment has CONFIRMED status
5100000000000073	3-D secure version 2, frictionless flow, success	Payment has CONFIRMED status

Maestro

Card PAN	3-D Secure result	Transaction result
5000000000000025	3-D secure version 2, challenge flow, full authentication	Payment has CONFIRMED status
5000000000000033	3-D secure version 2, frictionless flow, success	Payment has CONFIRMED status
5666666666666955	3-D secure version 2, challenge flow, full authentication	Payment has DECLINED status

Discover

Card PAN	3-D Secure result	Transaction result
6500000000000895	3-D secure version 2, challenge flow, full authentication	Payment has CONFIRMED status
6500000000000069	3-D secure version 2, frictionless flow, attempt	Payment has CONFIRMED status
6011000000000053	3-D secure version 2, frictionless flow, success	Payment has CONFIRMED status

JCB

Card PAN	3-D Secure result	Transaction result
3528000000000015	3-D secure version 2, challenge flow, full authentication	Payment has CONFIRMED status
3528000000000023	3-D secure version 2, frictionless flow, success	Payment has CONFIRMED status
3528000000000049	3-D secure version 2, frictionless flow, attempt	Payment has CONFIRMED status

UnionPay

Card PAN	3-D Secure result	Transaction result
6222020000000085	3-D secure version 2, challenge flow, full authentication	Payment has CONFIRMED status
8171000000000000079	3-D secure version 2, frictionless flow, attempt	Payment has CONFIRMED status
6200000000000053	3-D secure version 2, frictionless flow, success	Payment has CONFIRMED status

Amex

Card PAN	3-D Secure result	Transaction result
370000000000085	3-D secure version 2, challenge flow, full authentication	Payment has CONFIRMED status
340000000000033	3-D secure version 2, frictionless flow, success	Payment has CONFIRMED status
340000000000009	3-D secure version 2, frictionless flow, attempt	Payment has CONFIRMED status

During the test, merchants used any cardholder name, expiration date, and security code to pay with these card information. To complete the authentication, the 3-DS Secure Authentication is also simulated through a page that displays only two buttons, one for successful authentication and the other for failed authentication. Please note that when the merchant chooses to fail authentication, the payment will always be declined, regardless of which PAN is used.

If you encounter an abnormal status code during the test, please contact Supefina operation personnel directly.