Pay-Out · Peru

Request

The Pay-Out API initiates disbursement transactions. This page is for Peru (country code pe). Payee bank bankCode, account type, CCI, and related rules follow this page and Regional Payment Guide — Peru.

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/disbursement/cash
Production	https://openapi.toppayment.com/pe/disbursement/cash

bankCode / bankName (payee bank) are in Regional Payment Guide — Peru.

Request Header

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

Request Body

Field	Required	Type	Description
mchNo	M	String(32)	Merchant number
orderNum	M	String(50)	Merchant order number
amount	M	Number(32,8)	Amount Peru: positive, integer or at most 2 decimal places, not all zeros.
bankCode	M	String(32)	Payee bank/wallet code (Peru) — Regional Payment Guide — Peru
bankCard	C	String(50)	Card/account field if the gateway still uses it; for Peru prefer accountNumber for CCI
accountType	M	String(32)	CORRIENTE / AHORROS / WALLET (case-insensitive) — Regional Payment Guide — Peru
accountNumber	C	String(100)	CCI (interbank): required when not WALLET; after stripping non-digits must be 20 digits; optional for WALLET
documentType	M	String(16)	DNI / CE / PAS / RUC (case-insensitive)
documentNo	M	String(100)	Document number (documento) No cross-check of length vs documentType.
accountEmail	M	String(255)	Payee email — valid format
accountName	M	String(50)	Payee name — max 50, letters/digits/spaces only
description	O	String(255)	Description
feeType	M	Number	Fee type 0: Deducted from order amount (net = amount − fee) 1: Fee separate (net = amount)
downNotifyUrl	M	String(164)	Callback URL
timestamp	M	String	Timestamp (13 digits)
sign	M	String	See Signature

Request Body Example (checking account + CCI; align with your live gateway)

Content-type: application/json

{
    "mchNo": "{{mchNo}}",
    "orderNum": "PEPAYOUT1234561",
    "amount": 100.50,
    "bankCode": "BCP",
    "accountType": "CORRIENTE",
    "accountNumber": "00219200212345678901",
    "documentType": "DNI",
    "documentNo": "12345678",
    "accountEmail": "[email protected]",
    "accountName": "Juan Perez",
    "description": "test",
    "feeType": 1,
    "downNotifyUrl": "https://example.com/notify",
    "timestamp": "1749451858772",
    "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	Request success
code	M	String	9999 = success; otherwise use status codes before treating as final failure
msg	O	String	Message
timeStamp	M	Number	Server time (ms)
data	M	Object	Payload
orderNum	M	String	Merchant order number
platOrderNum	M	String	Platform order number
amount	M	Number	Amount
fee	M	Number	Fee
feeType	M	Number	Fee type
status	M	Number	Status — Transaction Status Codes
statusMsg	M	String	Status message
bankCode	M	String	Bank code (Peru) — Regional Payment Guide — Peru
bankCard	M	String	Masked or echoed account
accountName	M	String	Account name
description	O	String	Description

Content-type: application/json

{
    "success": true,
    "code": "9999",
    "msg": "SUCCESS",
    "timeStamp": 1767772957433,
    "data": {
        "orderNum": "PEPAYOUT12345617",
        "platOrderNum": "TRANS2008811496544403456",
        "amount": 100.50,
        "fee": 2,
        "feeType": 1,
        "status": 1,
        "statusMsg": "ORDER_RECEIVED_PROCESSING",
        "bankCode": "BCP",
        "bankCard": "00219200212345678901",
        "accountName": "Juan Perez",
        "description": "test"
    }
}

Notification

HTTP Request

Field	Required	Type	Description
Content-Type	M	String	HTTP request content type Fixed value: application/json Indicates JSON request format

Notification Body

Field	Required	Type	Description
platOrderNum	M	String	Platform order number System-generated internal transaction reference Used for internal transaction management and support
version	M	String	Version API version identifier Example: v1
orderNum	M	String	Merchant order number Same as orderNum in the original request Used for transaction identification and verification
amount	M	Number	Transaction amount Confirmed transaction amount
fee	M	Number	Fee Fee charged for the transaction
feeType	M	Number	Fee type 1: Merchant bears the fee
status	M	Number	Transaction status See Transaction Status Codes
statusMsg	M	String	Status message Human-readable order status description
bankCode	M	String	Bank code (Peru) See Regional Payment Guide — Peru
bankCard	M	String	Bank card number/account number
accountName	M	String	Account name
description	O	String	Description
sign	M	String	Signature Digital signature of callback data

Response

Important response

Notification response: Return only the string SUCCESS to acknowledge receipt of the notification

{
    "platOrderNum": "TRANS2008812168572567552",
    "version": "v1",
    "orderNum": "PEPAYOUT12345648",
    "amount": 111.00,
    "fee": 3,
    "feeType": 1,
    "status": 2,
    "statusMsg": "supplement success!",
    "bankCode": "BCP",
    "bankCard": "00219200212345678901",
    "accountName": "Juan Perez",
    "description": "test",
    "sign": "KCitZCmhtuoGtVOl/EC4Mn1vwf3QRkoL9Ged0psKiCzATvP0AePNc8P1PEcWrbJYAPctewCRO9jW+vHjtXrh6ozk2OUvVDUlLTiM3PS7ydpeogy+W6w3b4OZDg5vUtaTVwz5mpEKBZv/XEhOes1C16+ec36PLp3Mi0Y0g4ivgwk="
}

SUCCESS