Quick Start

Overview

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 · Balance inquiry
• Crypto integration overview

Regional payment guides

• Philippines · Indonesia · India · Thailand · Vietnam
• Peru · Brazil · Mexico · Colombia · Bolivia · Pakistan · Bangladesh

---

Integration steps (recommended order)

1. Pick environment and merchant number

   • Sandbox: merchant number prefix SD; paths include /sandbox/.
   • Production: use the live merchant number; paths do not include /sandbox/.

2. 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.

3. Required params

   • mchNo for the chosen environment
   • sign generated per signature rules
   • downNotifyUrl for Pay-In and Pay-Out callbacks
   • timestamp (13-digit millisecond Unix timestamp)

4. Domain and path template

   Domain guide

   Type	Domain	Scope	Notes
   Unified domain (recommended)	openapi.toppayment.com	All fiat countries and crypto	Fiat paths include {countryCode}; crypto uses /crypto/...; legacy hosts remain available
   Country domain (compatible)	global-{countryCode}-openapi.toppayment.com	All fiat countries	e.g. global-ng-openapi.toppayment.com
   Legacy crypto domain (compatible)	global-digit-openapi.toppayment.com	Crypto	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), ng (Nigeria).

5. Choose API

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

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

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

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

Account verification (Indonesia)

See Account verification · Indonesia for fields and examples. Synchronous API; no callback; production only.

Country / region	URL
Indonesia (id)	https://openapi.toppayment.com/id/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

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 (cashier)	https://openapi.toppayment.com/crypto/sandbox/pay/prePay	https://openapi.toppayment.com/crypto/pay/prePay	Crypto Pay-In
Pay-in (direct API)	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

6. 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.

7. Callbacks and testing

   • The callback is sent to the downNotifyUrl provided in the order request. (Pay-In / Pay-Out separately).
   • In sandbox you can simulate callbacks from the dashboard (see sandbox guide).

---

Checklist

• Environment: correct domain and path (with or without /sandbox/).
• Merchant number: sandbox uses SD...; production uses the live merchant number.
• Keys: merchant private key stored; merchant public key uploaded; platform public key obtained.
• Signature: generated per rules; callback verification implemented.
• Callback: downNotifyUrl reachable; Pay-Out IP allowlist handled if required.
• API paths: {countryCode} correct; params align with examples.

---

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).

---

References

• Sandbox integration guide
• Production integration guide
• Signature rules
• Exception codes
• Transaction status codes