Pay-In · Philippines
Overview
The Pay-In API initiates collection transactions from customers. This page covers the Philippines (country code ph) with two ordering modes:
| Mode | Path | Description |
|---|---|---|
| Cashier mode | /pay/prePay | Default. Returns cashierUrl for the platform H5 cashier |
| API mode | /pay/transOrder | Requires method in the request; returns payData / payDataType (payment redirect URL, etc.) |
method (Philippines Pay-In codes) is listed in Regional Payment Guide — Philippines.
Integration note
Cashier mode is enabled by default. Contact support to whitelist your merchant account before integrating API mode.
Request Header
Shared by both modes:
| Field | Required | Type | Description |
|---|---|---|---|
| Content-Type | M | String | Fixed value: application/json |
Cashier Mode (prePay)
Pre-order and redirect the customer to the platform cashier via cashierUrl.
Request URL
Domain: Prefer unified host
openapi.toppayment.com(path unchanged); legacy country domain (e.g.global-ph-openapi.toppayment.com) remains available.
| Environment | URL |
|---|---|
| Sandbox | https://openapi.toppayment.com/sandbox/ph/pay/prePay |
| Production | https://openapi.toppayment.com/ph/pay/prePay |
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 Philippines: at most 2 decimal places Example: 100, 100.50 |
| productDetail | M | String(100) | Product detail |
| method | O | String(16) | Payment method (Philippines) Optional; omit to let the user choose on the cashier. Examples: GCASH, MAYA, QRPH, GCASH_WEB — full list: Regional Payment Guide — Philippines |
| timestamp | M | String(13) | Timestamp in milliseconds |
| customerName | M | String(64) | Customer name |
| customerEmail | M | String(64) | Customer email |
| customerPhone | M | String(32) | Customer phone |
| 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": "PH1232451",
"amount": 100,
"productDetail": "Test",
"method": "GCASH",
"timestamp": "1749451858772",
"customerName": "AMY",
"customerEmail": "[email protected]",
"customerPhone": "0817773255",
"expiryPeriod": 1440,
"downNotifyUrl": "https://123.com",
"redirectUrl": "http://hxxyhyo.mr/gchmnzv",
"sign": "Generate per signature rules and replace"
}
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 |
| orderNum | M | String | Merchant order number |
| platOrderNum | M | String | Platform order number |
| amount | M | Number | Transaction amount |
| fee | M | Number | Fee |
| method | M | String | Payment method — Regional Payment Guide — Philippines |
| productDetail | M | String | Product detail |
| customerName | M | String | Customer name |
| customerEmail | M | String | Customer email |
| customerPhone | M | String | Customer phone |
| validTime | M | Number | Expiry timestamp (ms) |
| cashierUrl | M | String | Cashier URL |
Response note
Cashier mode does not return payData or payDataType. Those fields appear only in API mode responses.
Content-type: application/json
{
"success": true,
"code": "9999",
"msg": null,
"timeStamp": 1767840272829,
"data": {
"orderNum": "2025014123512317681013",
"platOrderNum": "PRE2009093829059153920",
"amount": 200,
"fee": 2.00,
"method": "GCASH",
"productDetail": "desc",
"customerName": "James Bond",
"customerEmail": "[email protected]",
"customerPhone": "+639502704098",
"validTime": 1767926672819,
"cashierUrl": "https://coc.gcashol.top/?20260108104430623221216941"
}
}
API Mode (transOrder)
Specify the payment method in the request, place the order directly with the channel, and receive payData / payDataType without the platform H5 cashier.
Request URL
| Environment | URL |
|---|---|
| Sandbox | https://openapi.toppayment.com/sandbox/ph/pay/transOrder |
| Production | https://openapi.toppayment.com/ph/pay/transOrder |
Request Body
Differences from cashier mode:
| Field | Required | Type | Description |
|---|---|---|---|
| method | M | String(16) | Payment method (Philippines) Required in API mode. Examples: GCASH, MAYA, QRPH, GCASH_WEB, MAYA_WEB, GRABPAY_WEB, GCASH_WAP, MAYA_WAP — full list: Regional Payment Guide — Philippines |
All other fields match cashier mode.
Request Body Example
Content-type: application/json
{
"mchNo": "{{mchNo}}",
"orderNum": "PHAPI1234561",
"amount": 100,
"productDetail": "Test",
"method": "GCASH",
"timestamp": "1749451858772",
"customerName": "AMY",
"customerEmail": "[email protected]",
"customerPhone": "0817773255",
"expiryPeriod": 1440,
"downNotifyUrl": "https://123.com",
"sign": "Generate per signature rules and replace"
}
Response Body Parameters
Common fields (success, code, msg, timeStamp, and data.orderNum, platOrderNum, amount, fee, method, productDetail, customerName, customerEmail, customerPhone, validTime) match cashier mode. API mode focuses on:
| Field | Required | Type | Description |
|---|---|---|---|
| payData | M | String | Payment payload — usually an upstream payment page URL; meaning depends on payDataType |
| payDataType | M | String | Payment data type Philippines e-wallet flows commonly use CASHIER_URL |
payDataType Reference
| payDataType | Description | Typical methods |
|---|---|---|
CASHIER_URL | Upstream payment page URL | GCASH, MAYA, GCASH_WAP, GCASH_WEB, MAYA_WAP, MAYA_WEB, GRABPAY_WEB |
QR_CODE | Raw QRPH QR code payload | QRPH |
Content-type: application/json
{
"success": true,
"code": "9999",
"msg": null,
"timeStamp": 1767840272829,
"data": {
"orderNum": "PHAPI1234561",
"platOrderNum": "PRE2009093829059153920",
"amount": 100,
"fee": 2.00,
"method": "GCASH",
"productDetail": "Test",
"customerName": "AMY",
"customerEmail": "[email protected]",
"customerPhone": "0817773255",
"validTime": 1767926672819,
"payData": "https://coc.gcashol.top/?20260108104430623221216941",
"payDataType": "CASHIER_URL"
}
}
Notification
Both ordering modes use the same async callback. The Philippines market uses v1 only — notifyVersion / v2 payer fields are not supported.
HTTP Request (callback)
| Field | Required | Type | Description |
|---|---|---|---|
| Content-Type | M | String | application/json |
Notification Body
| Field | Required | Type | Description |
|---|---|---|---|
| platOrderNum | M | String | Platform order number |
| version | M | String | Fixed value: v1 |
| orderNum | M | String | Merchant order number |
| amount | M | Number | Amount |
| fee | M | Number | Fee |
| customerName | M | String | Customer name |
| customerEmail | M | String | Customer email |
| customerPhone | M | String | Customer phone |
| status | M | String | Status — see Transaction Status Codes |
| sign | M | String | Callback signature |
Response
Info
Return only the string SUCCESS to acknowledge the notification.
{
"platOrderNum": "PRE2009165141186183168",
"version": "v1",
"orderNum": "PH12324521",
"amount": 100,
"fee": 2,
"customerName": "AMY",
"customerEmail": "[email protected]",
"customerPhone": "0817773255",
"status": "SUCCESS",
"sign": "m5++HHEOfaVL3opFSuihVE4kkdLaCyhpFVSSLJld8WeEhlH93Ido5MQQ6peWrf+8eCkQd127jesL9esQDdFAiGKkem5BwvqTAvZGQm9v7M33Sy+W58OkGkb3/8BxQwCLTIUouhwpj1TwIeqP3JWo3AFMm5qezH3JbVfOd1IZ9Gw="
}
SUCCESS