Quick Start
Overview
Request timeout
The maximum timeout for merchant requests to our APIs is 30 seconds. Results are typically returned in about 200 milliseconds. We recommend setting the client timeout to around 10 seconds.
The system callback to the merchant times out after 5 seconds. If it exceeds 5 seconds, the notification is treated as failed.
This page summarizes global open API onboarding: choose environment, prepare keys and params, build paths, sign/verify, and follow the linked guides.
Quick links
- Sandbox
- Production
- Signature rules
- Pay-In query · Pay-Out query · Account verification · Indonesia · Account verification · Vietnam · Balance inquiry
- Crypto integration overview
Regional payment guides
- Philippines · Indonesia · Nigeria · India · Thailand · Vietnam
- Peru · Brazil · Mexico · Colombia · Bolivia · Pakistan · Bangladesh · Turkey
Integration steps (recommended order)
Pick environment and merchant number
- Sandbox: merchant number prefix
SD; paths include/sandbox/. - Production: use the live merchant number; paths do not include
/sandbox/.
- Sandbox: merchant number prefix
Keys preparation
- RSA PKCS#8 (recommended 2048-bit). Keep the merchant private key for signing; upload the merchant public key to the dashboard.
- Obtain the platform public key from the dashboard for callback verification.
Required params
mchNofor the chosen environmentsigngenerated per signature rulesdownNotifyUrlfor Pay-In and Pay-Out callbackstimestamp(13-digit millisecond Unix timestamp)
Domain and path template
Domain guide
Type Domain Scope Notes Unified domain (recommended) openapi.toppayment.comAll fiat countries and crypto Fiat paths include {countryCode}; crypto uses/crypto/...; legacy hosts remain availableCountry domain (compatible) global-{countryCode}-openapi.toppayment.comAll fiat countries e.g. global-ng-openapi.toppayment.comLegacy crypto domain (compatible) global-digit-openapi.toppayment.comCrypto Path remains /crypto/...Path templates (
{host}per the table above):- Fiat sandbox:
https://{host}/sandbox/{countryCode}/... - Fiat production:
https://{host}/{countryCode}/... - Crypto sandbox:
https://{host}/crypto/sandbox/... - Crypto production:
https://{host}/crypto/...
Examples:
- Nigeria (recommended):
https://openapi.toppayment.com/ng/pay/prePay - Nigeria (legacy):
https://global-ng-openapi.toppayment.com/ng/pay/prePay - Philippines (recommended):
https://openapi.toppayment.com/ph/pay/prePay - Indonesia (recommended):
https://openapi.toppayment.com/id/pay/prePay
{countryCode}reference:ph(Philippines),id(Indonesia),in(India),th(Thailand),vn(Vietnam),pe(Peru),br(Brazil),mx(Mexico),co(Colombia),bo(Bolivia),pk(Pakistan),bd(Bangladesh),tr(Turkey),ng(Nigeria).- Fiat sandbox:
Choose API
Fiat is separated by country. See Fiat. Crypto is not. See Crypto.
Fiat
URLs below use the recommended unified host
openapi.toppayment.com; legacy country domains (e.g.global-ng-openapi.toppayment.com) remain available.
Pay-In orders
| Country / region | Docs & params | Sandbox | Production |
|---|---|---|---|
Philippines (ph) | Pay-In · Philippines, method, see guide | https://openapi.toppayment.com/sandbox/ph/pay/prePay | https://openapi.toppayment.com/ph/pay/prePay |
Indonesia (id) | Pay-In · Indonesia, method, see guide | https://openapi.toppayment.com/sandbox/id/pay/prePay | https://openapi.toppayment.com/id/pay/prePay |
Nigeria (ng) | Pay-In · Nigeria, method, see guide | https://openapi.toppayment.com/sandbox/ng/pay/prePay | https://openapi.toppayment.com/ng/pay/prePay |
India (in) | Pay-In · India, method, see guide | https://openapi.toppayment.com/sandbox/in/pay/prePay | https://openapi.toppayment.com/in/pay/prePay |
Thailand (th) | Pay-In · Thailand, method, see guide | https://openapi.toppayment.com/sandbox/th/pay/prePay | https://openapi.toppayment.com/th/pay/prePay |
Vietnam (vn) | Pay-In · Vietnam, method, see guide | https://openapi.toppayment.com/sandbox/vn/pay/prePay | https://openapi.toppayment.com/vn/pay/prePay |
Peru (pe) | Pay-In · Peru, method, see guide | https://openapi.toppayment.com/sandbox/pe/pay/prePay | https://openapi.toppayment.com/pe/pay/prePay |
Brazil (br) | Pay-In · Brazil, method, see guide | https://openapi.toppayment.com/sandbox/br/pay/prePay | https://openapi.toppayment.com/br/pay/prePay |
Mexico (mx) | Pay-In · Mexico, method, see guide | https://openapi.toppayment.com/sandbox/mx/pay/prePay | https://openapi.toppayment.com/mx/pay/prePay |
Colombia (co) | Pay-In · Colombia, method, see guide | https://openapi.toppayment.com/sandbox/co/pay/prePay | https://openapi.toppayment.com/co/pay/prePay |
Bolivia (bo) | Pay-In · Bolivia, method, see guide | https://openapi.toppayment.com/sandbox/bo/pay/prePay | https://openapi.toppayment.com/bo/pay/prePay |
Pakistan (pk) | Pay-In · Pakistan, method, see guide | https://openapi.toppayment.com/sandbox/pk/pay/prePay | https://openapi.toppayment.com/pk/pay/prePay |
Bangladesh (bd) | Pay-In · Bangladesh, method, see guide | https://openapi.toppayment.com/sandbox/bd/pay/prePay | https://openapi.toppayment.com/bd/pay/prePay |
Turkey (tr) | Pay-In · Turkey, method, see guide | https://openapi.toppayment.com/sandbox/tr/pay/prePay | https://openapi.toppayment.com/tr/pay/prePay |
Pay-In query
See Pay-In order inquiry. Request body requires at least one of orderNum or platOrderNum.
| Country / region | Sandbox | Production |
|---|---|---|
Philippines (ph) | https://openapi.toppayment.com/sandbox/ph/pay/query | https://openapi.toppayment.com/ph/pay/query |
Indonesia (id) | https://openapi.toppayment.com/sandbox/id/pay/query | https://openapi.toppayment.com/id/pay/query |
Nigeria (ng) | https://openapi.toppayment.com/sandbox/ng/pay/query | https://openapi.toppayment.com/ng/pay/query |
India (in) | https://openapi.toppayment.com/sandbox/in/pay/query | https://openapi.toppayment.com/in/pay/query |
Thailand (th) | https://openapi.toppayment.com/sandbox/th/pay/query | https://openapi.toppayment.com/th/pay/query |
Vietnam (vn) | https://openapi.toppayment.com/sandbox/vn/pay/query | https://openapi.toppayment.com/vn/pay/query |
Peru (pe) | https://openapi.toppayment.com/sandbox/pe/pay/query | https://openapi.toppayment.com/pe/pay/query |
Brazil (br) | https://openapi.toppayment.com/sandbox/br/pay/query | https://openapi.toppayment.com/br/pay/query |
Mexico (mx) | https://openapi.toppayment.com/sandbox/mx/pay/query | https://openapi.toppayment.com/mx/pay/query |
Colombia (co) | https://openapi.toppayment.com/sandbox/co/pay/query | https://openapi.toppayment.com/co/pay/query |
Bolivia (bo) | https://openapi.toppayment.com/sandbox/bo/pay/query | https://openapi.toppayment.com/bo/pay/query |
Pakistan (pk) | https://openapi.toppayment.com/sandbox/pk/pay/query | https://openapi.toppayment.com/pk/pay/query |
Bangladesh (bd) | https://openapi.toppayment.com/sandbox/bd/pay/query | https://openapi.toppayment.com/bd/pay/query |
Turkey (tr) | https://openapi.toppayment.com/sandbox/tr/pay/query | https://openapi.toppayment.com/tr/pay/query |
Sub-order inquiry
See Sub-order inquiry. Request body requires at least one of orderNum or platOrderNum.
Production only; no sandbox URL.
| Country / region | URL |
|---|---|
Mexico (mx) | https://openapi.toppayment.com/mx/pay/querySubOrders |
Colombia (co) | https://openapi.toppayment.com/co/pay/querySubOrders |
Pay-Out orders
| Country / region | Docs & params | Sandbox | Production |
|---|---|---|---|
Philippines (ph) | Pay-Out · Philippines, bankCode, see guide | https://openapi.toppayment.com/sandbox/ph/disbursement/cash | https://openapi.toppayment.com/ph/disbursement/cash |
Indonesia (id) | Pay-Out · Indonesia, bankCode, see guide | https://openapi.toppayment.com/sandbox/id/disbursement/cash | https://openapi.toppayment.com/id/disbursement/cash |
Nigeria (ng) | Pay-Out · Nigeria, bankCode, see guide | https://openapi.toppayment.com/sandbox/ng/disbursement/cash | https://openapi.toppayment.com/ng/disbursement/cash |
India (in) | Pay-Out · India, bankCode, see guide | https://openapi.toppayment.com/sandbox/in/disbursement/cash | https://openapi.toppayment.com/in/disbursement/cash |
Thailand (th) | Pay-Out · Thailand, bankCode, see guide | https://openapi.toppayment.com/sandbox/th/disbursement/cash | https://openapi.toppayment.com/th/disbursement/cash |
Vietnam (vn) | Pay-Out · Vietnam, bankCode, see guide | https://openapi.toppayment.com/sandbox/vn/disbursement/cash | https://openapi.toppayment.com/vn/disbursement/cash |
Peru (pe) | Pay-Out · Peru, bankCode, see guide | https://openapi.toppayment.com/sandbox/pe/disbursement/cash | https://openapi.toppayment.com/pe/disbursement/cash |
Brazil (br) | Pay-Out · Brazil, bankCode, see guide | https://openapi.toppayment.com/sandbox/br/disbursement/cash | https://openapi.toppayment.com/br/disbursement/cash |
Mexico (mx) | Pay-Out · Mexico, bankCode, see guide | https://openapi.toppayment.com/sandbox/mx/disbursement/cash | https://openapi.toppayment.com/mx/disbursement/cash |
Colombia (co) | Pay-Out · Colombia, bankCode, see guide | https://openapi.toppayment.com/sandbox/co/disbursement/cash | https://openapi.toppayment.com/co/disbursement/cash |
Bolivia (bo) | Pay-Out · Bolivia, bankCode, see guide | https://openapi.toppayment.com/sandbox/bo/disbursement/cash | https://openapi.toppayment.com/bo/disbursement/cash |
Pakistan (pk) | Pay-Out · Pakistan, bankCode, see guide | https://openapi.toppayment.com/sandbox/pk/disbursement/cash | https://openapi.toppayment.com/pk/disbursement/cash |
Bangladesh (bd) | Pay-Out · Bangladesh, bankCode, see guide | https://openapi.toppayment.com/sandbox/bd/disbursement/cash | https://openapi.toppayment.com/bd/disbursement/cash |
Turkey (tr) | Pay-Out · Turkey, bankCode, see guide | https://openapi.toppayment.com/sandbox/tr/disbursement/cash | https://openapi.toppayment.com/tr/disbursement/cash |
Pay-Out query
See Pay-Out order inquiry. Request body requires at least one of orderNum or platOrderNum.
| Country / region | Sandbox | Production |
|---|---|---|
Philippines (ph) | https://openapi.toppayment.com/sandbox/ph/disbursement/query | https://openapi.toppayment.com/ph/disbursement/query |
Indonesia (id) | https://openapi.toppayment.com/sandbox/id/disbursement/query | https://openapi.toppayment.com/id/disbursement/query |
Nigeria (ng) | https://openapi.toppayment.com/sandbox/ng/disbursement/query | https://openapi.toppayment.com/ng/disbursement/query |
India (in) | https://openapi.toppayment.com/sandbox/in/disbursement/query | https://openapi.toppayment.com/in/disbursement/query |
Thailand (th) | https://openapi.toppayment.com/sandbox/th/disbursement/query | https://openapi.toppayment.com/th/disbursement/query |
Vietnam (vn) | https://openapi.toppayment.com/sandbox/vn/disbursement/query | https://openapi.toppayment.com/vn/disbursement/query |
Peru (pe) | https://openapi.toppayment.com/sandbox/pe/disbursement/query | https://openapi.toppayment.com/pe/disbursement/query |
Brazil (br) | https://openapi.toppayment.com/sandbox/br/disbursement/query | https://openapi.toppayment.com/br/disbursement/query |
Mexico (mx) | https://openapi.toppayment.com/sandbox/mx/disbursement/query | https://openapi.toppayment.com/mx/disbursement/query |
Colombia (co) | https://openapi.toppayment.com/sandbox/co/disbursement/query | https://openapi.toppayment.com/co/disbursement/query |
Bolivia (bo) | https://openapi.toppayment.com/sandbox/bo/disbursement/query | https://openapi.toppayment.com/bo/disbursement/query |
Pakistan (pk) | https://openapi.toppayment.com/sandbox/pk/disbursement/query | https://openapi.toppayment.com/pk/disbursement/query |
Bangladesh (bd) | https://openapi.toppayment.com/sandbox/bd/disbursement/query | https://openapi.toppayment.com/bd/disbursement/query |
Turkey (tr) | https://openapi.toppayment.com/sandbox/tr/disbursement/query | https://openapi.toppayment.com/tr/disbursement/query |
Account verification (Indonesia, Vietnam)
See Account verification · Indonesia and Account verification · Vietnam for fields and examples. Synchronous API; no callback; production only. Vietnam requires an extra accountName field in the request body.
| Country / region | URL |
|---|---|
Indonesia (id) | https://openapi.toppayment.com/id/disbursement/bankVerify |
Vietnam (vn) | https://openapi.toppayment.com/vn/disbursement/bankVerify |
Balance inquiry
See Balance inquiry for currency and field details; regional guides are linked below.
| Country / region | Currency | Sandbox | Production |
|---|---|---|---|
Philippines (ph) | PHP, guide | https://openapi.toppayment.com/sandbox/ph/balance/v1 | https://openapi.toppayment.com/ph/balance/v1 |
Indonesia (id) | IDR, guide | https://openapi.toppayment.com/sandbox/id/balance/v1 | https://openapi.toppayment.com/id/balance/v1 |
Nigeria (ng) | NGN, guide | https://openapi.toppayment.com/sandbox/ng/balance/v1 | https://openapi.toppayment.com/ng/balance/v1 |
India (in) | INR, guide | https://openapi.toppayment.com/sandbox/in/balance/v1 | https://openapi.toppayment.com/in/balance/v1 |
Thailand (th) | THB, guide | https://openapi.toppayment.com/sandbox/th/balance/v1 | https://openapi.toppayment.com/th/balance/v1 |
Vietnam (vn) | VND, guide | https://openapi.toppayment.com/sandbox/vn/balance/v1 | https://openapi.toppayment.com/vn/balance/v1 |
Peru (pe) | PEN, guide | https://openapi.toppayment.com/sandbox/pe/balance/v1 | https://openapi.toppayment.com/pe/balance/v1 |
Brazil (br) | BRL, guide | https://openapi.toppayment.com/sandbox/br/balance/v1 | https://openapi.toppayment.com/br/balance/v1 |
Mexico (mx) | MXN, guide | https://openapi.toppayment.com/sandbox/mx/balance/v1 | https://openapi.toppayment.com/mx/balance/v1 |
Colombia (co) | COP, guide | https://openapi.toppayment.com/sandbox/co/balance/v1 | https://openapi.toppayment.com/co/balance/v1 |
Bolivia (bo) | BOB, guide | https://openapi.toppayment.com/sandbox/bo/balance/v1 | https://openapi.toppayment.com/bo/balance/v1 |
Pakistan (pk) | PKR, guide | https://openapi.toppayment.com/sandbox/pk/balance/v1 | https://openapi.toppayment.com/pk/balance/v1 |
Bangladesh (bd) | BDT, guide | https://openapi.toppayment.com/sandbox/bd/balance/v1 | https://openapi.toppayment.com/bd/balance/v1 |
Turkey (tr) | TRY, guide | https://openapi.toppayment.com/sandbox/tr/balance/v1 | https://openapi.toppayment.com/tr/balance/v1 |
Crypto
Crypto is not separated by country: prefer unified host openapi.toppayment.com with the fixed path prefix /crypto; legacy host global-digit-openapi.toppayment.com remains available. Every request must carry the Nonce header. See Crypto integration overview for full field definitions and examples.
Direct API path naming (sandbox vs production)
Sandbox direct pay-in uses /crypto/sandbox/pay/directlyPay (also accepts /crypto/sandbox/pay/transOrder); production uses /crypto/pay/orderDirectly. Path names differ by environment —request and response bodies are identical.
| Scenario | Sandbox URL | Production URL | Doc |
|---|---|---|---|
| Pay-in | https://openapi.toppayment.com/crypto/sandbox/pay/directlyPay | https://openapi.toppayment.com/crypto/pay/orderDirectly | Crypto Pay-In |
| Pay-in query | https://openapi.toppayment.com/crypto/sandbox/pay/query | https://openapi.toppayment.com/crypto/pay/query | Order Inquiry |
| Pay-out | https://openapi.toppayment.com/crypto/sandbox/disbursement/cash | https://openapi.toppayment.com/crypto/disbursement/cash | Crypto Pay-Out |
| Pay-out query | https://openapi.toppayment.com/crypto/sandbox/disbursement/query | https://openapi.toppayment.com/crypto/disbursement/query | Order Inquiry |
| Balance inquiry | https://openapi.toppayment.com/crypto/sandbox/balance/v1 | https://openapi.toppayment.com/crypto/balance/v1 | Balance Inquiry |
Sign and verify
- Signing: sort non-empty param keys by ASCII, concatenate values only (no separators), sign with merchant private key (RSA) and Base64 the result.
- Callback verification: remove
sign, sort and concatenate remaining values the same way, decrypt with platform public key and compare. - Refer to the Signature page for step-by-step guidance and code samples.
Callbacks and testing
- The callback is sent to the
downNotifyUrlprovided in the order request. (Pay-In / Pay-Out separately). - In sandbox you can simulate callbacks from the dashboard (see sandbox guide).
- The callback is sent to the
Checklist
Terminology
- Pay-In: collection from customers to merchants.
- Pay-Out: disbursement from merchants to beneficiaries.
- Country code: lowercase ISO codes in URL paths (e.g.
id,ph,ng).
