Pay-In · Peru

Request

The Pay-In API initiates collection transactions from customers. This page covers Peru (country code pe). Request/response fields are the same across markets; use your market’s method codes only.

Request URL

Domain: Prefer unified host openapi.toppayment.com (path unchanged); legacy country domain (e.g. global-pe-openapi.toppayment.com) remains available.

Environment	URL
Sandbox	https://openapi.toppayment.com/sandbox/pe/pay/prePay
Production	https://openapi.toppayment.com/pe/pay/prePay

method (Pay-In payment codes for Peru) is listed in Regional Payment Guide — Peru.

Request Header

Field	Required	Type	Description
Content-Type	M	String	Fixed value: application/json

Request Body

Field	Required	Type	Description
mchNo	M	String(32)	Merchant number
orderNum	M	String(64)	Merchant order number
amount	M	Number(32,8)	Transaction amount Peru: positive, integer or at most 2 decimal places, not all zeros.
productDetail	M	String(100)	Product detail
method	O	String(16)	Payment method (Peru) Currently DOCUMENTS — see Regional Payment Guide — Peru
timestamp	M	String(13)	Timestamp in milliseconds
customerName	M	String(64)	Customer name Peru route: max 50 characters; Unicode letters, digits, spaces only.
customerEmail	M	String(64)	Customer email Peru route: if present, must be a valid email.
customerPhone	M	String(32)	Customer phone
documentType	C	String(16)	ID type; required when documentNo is sent. Values: Regional Payment Guide — Peru (DNI / CE / PAS / RUC, case-insensitive)
documentNo	C	String(100)	ID number; optional; if set, documentType must be sent. No length vs type cross-check
expiryPeriod	O	Number(1–9999)	Validity in minutes
downNotifyUrl	M	String(255)	Async callback URL
redirectUrl	O	String(512)	Redirect after payment
sign	M	String	Signature — see Signature

Request Body Example

Content-type: application/json

{
    "mchNo": "{{mchNo}}",
    "orderNum": "PE1234561",
    "amount": 100.50,
    "productDetail": "Product",
    "method": "DOCUMENTS",
    "timestamp": "1749451858772",
    "customerName": "Maria Garcia",
    "customerEmail": "[email protected]",
    "customerPhone": "51987654321",
    "documentType": "DNI",
    "documentNo": "12345678",
    "expiryPeriod": 1440,
    "downNotifyUrl": "https://example.com/notify",
    "redirectUrl": "https://example.com/return",
    "sign": "Generate per signature rules and replace"
}

Response

HTTP Response

Field	Required	Type	Description
Content-Type	M	String	application/json

Response Body Parameters

Field	Required	Type	Description
success	M	Boolean	Success flag
code	M	String	9999 = success
msg	O	String	Message
timeStamp	M	Number	Server time (ms)
data	M	Object	Payload
method	M	String	Payment method (Peru) — Regional Payment Guide — Peru
…			(Same field list as the Philippines version)

{
    "success": true,
    "code": "9999",
    "msg": null,
    "timeStamp": 1767840272829,
    "data": {
        "orderNum": "PE1234561",
        "platOrderNum": "PRE2009093829059153920",
        "amount": 100.50,
        "fee": 2.0,
        "method": "DOCUMENTS",
        "productDetail": "Product",
        "customerName": "Maria Garcia",
        "customerEmail": "[email protected]",
        "customerPhone": "51987654321",
        "validTime": 1767926672819,
        "cashierUrl": "https://example.cashier/pay",
        "payData": "https://example.cashier/pay",
        "payDataType": "CASHIER_URL"
    }
}

Notification

Same callback contract as the Philippines Pay-In: body fields, status string values, and SUCCESS acknowledgment — see Transaction Status Codes.

Example callback (illustrative)

{
    "platOrderNum": "PRE2009165141186183168",
    "version": "v1",
    "orderNum": "PE12345621",
    "amount": 100.50,
    "fee": 2,
    "customerName": "Maria Garcia",
    "customerEmail": "[email protected]",
    "customerPhone": "51987654321",
    "status": "SUCCESS",
    "sign": "…"
}

Respond with:

SUCCESS