🇵🇪Peru

（Multiple payment method integration）

Currently supported payment products

1. Cash

2. Transfer

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
countryId	String	Yes	Country number Reference: Dictionary table - country number Peru：PER
currency	String	Yes	Currency Reference: Dictionary Table - Currency Peruvian Sol：PEN
orderAmount	String	Yes	The amount of the order
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.
customerIdentification	String	Yes	The ID number of the user 00：ID card (CC), 8 digits 01：Alien Identity Card (CE), more than 9 digits 02：Tax identification number, 11 digits 03：Passport, more than 9 digits 04：Departure Document (PAR) 05：Military Identification（LMI） The same certificate number customerIdentification can be collected no more than 20 times per day
customerIdentificationType	String	Yes	The type of user ID 00：Identification Card（CC） 01：Alien Identity Card（CE） 02: Tax identification number 03：Passport（PAS) 04：Departure Document（PAR） 05：Military Identification（LMI）
customerName	String	Yes	User's name
lastName	String	Yes	The user's last name
customerPhone	String	Yes	Subscriber's phone, 9 digits Example: 975728895
customerEmail	String	Yes	The user's email address
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
merId	String	Yes	Merchant ID Merchant ID acquisition path: Supefina Merchant Background - Merchant Management - Basic Information - Merchant ID
merOrderNo	String	Yes	Merchant order number
description	String	Yes	Payment-related descriptions
callbackUrl	String	No	Callback address For details, see Notification Callbacks
checkOut	Boolean	Yes	Pull aggregate checkout conditions In this mode, only true is supported
nonceStr	String	Yes	Random strings The length cannot exceed 32 bits
sign	String	Yes	signature For details, please refer to: Signature algorithm

Sample request

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

{
    "customerIdentificationType": "00",
    "lastName": "xxxx",
    "merOrderNo": "20240920195501",
    "sign": "xxxxxx",
    "customerIdentification": "22345678",
    "countryId": "PER",
    "nonceStr": "20240920195501",
    "customerName": "xxxx",
    "customerPhone": "1234567890",
    "orderAmount": 100,
    "customerEmail": "[email protected]",
    "merId": "xxxxxxx",
    "checkOut": "true",
    "description":"supefina",
    "currency": "PEN",
    "callbackUrl": "xxxxxxxx"
}

1. Pass in the specified payment method

• payProduct：03

{
    "customerIdentificationType": "00",
    "payProduct":"03",
    "lastName": "xxxx",
    "merOrderNo": "20240920195501",
    "sign": "xxxxxx",
    "customerIdentification": "22345678",
    "countryId": "PER",
    "nonceStr": "20240920195501",
    "customerName": "xxxx",
    "customerPhone": "1234567890",
    "orderAmount": 100,
    "customerEmail": "[email protected]",
    "merId": "xxxxxxx",
    "checkOut": "true",
    "description":"supefina",
    "currency": "PEN",
    "callbackUrl": "xxxxxxxx"
}

• payProduct：12

{
    "customerIdentificationType": "00",
    "payProduct":"12",
    "lastName": "xxxx",
    "merOrderNo": "20240920195501",
    "sign": "xxxxxx",
    "customerIdentification": "22345678",
    "countryId": "PER",
    "nonceStr": "20240920195501",
    "customerName": "xxxx",
    "customerPhone": "1234567890",
    "orderAmount": 100,
    "customerEmail": "[email protected]",
    "merId": "xxxxxxx",
    "checkOut": "true",
    "description":"supefina",
    "currency": "PEN",
    "callbackUrl": "xxxxxxxx"
}

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": "xxxxxx",
        "merOrderNo": "20240920195501",
        "supefinaOrderNo": "2025011877295415489306624",
        "amount": 100,
        "url": "http://h5.supefina.tech/combineCashier?token=349472b99a184e0f9da91a3b290d4ad7",
        "currency": "PEN"
    }
}

Example response - Failed

{
    "code": "400",
    "msg": "param error customerName cannot be empty"
}

Callback Notification - Submission Method：POST

Variable name	type	description
amount	String	The amount of the order
countryId	String	Country number
fee	String	Advance handling fee will be charged
identifier	String	Payment Reference
merId	String	Merchant code
merOrderId	String	Merchant order number
msg	String	message
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": "230.00",
    "countryId": "PER",
    "customerName": "Test Name",
    "fee": "6.90",
    "identifier": "90911988431",
    "merId": "8202980903390150",
    "merOrderId": "17922853818122896811753697281175369728",
    "nonceStr": "935111b9-968e-4b3d-9036-fd1acf",
    "realityAmount": "230",
    "realityFee": "6.90",
    "reference": "90911988431",
    "sign": "69DF96903B85CD1408BD6849C62254C0",
    "status": "01",
    "successTime": 1716149235000,
    "supefinaOrderId": "202405190101010696298b1ca1141",
    "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";
}