Skip to main content

Quick Start

TOPPAY TeamAbout 6 min

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.

Regional payment guides


  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

    TypeDomainScopeNotes
    Unified domain (recommended)openapi.toppayment.comAll fiat countries and cryptoFiat paths include {countryCode}; crypto uses /crypto/...; legacy hosts remain available
    Country domain (compatible)global-{countryCode}-openapi.toppayment.comAll fiat countriese.g. global-ng-openapi.toppayment.com
    Legacy crypto domain (compatible)global-digit-openapi.toppayment.comCryptoPath 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).

  5. 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 / regionDocs & paramsSandboxProduction
Philippines (ph)Pay-In · Philippines, method, see guidehttps://openapi.toppayment.com/sandbox/ph/pay/prePayhttps://openapi.toppayment.com/ph/pay/prePay
Indonesia (id)Pay-In · Indonesia, method, see guidehttps://openapi.toppayment.com/sandbox/id/pay/prePayhttps://openapi.toppayment.com/id/pay/prePay
Nigeria (ng)Pay-In · Nigeria, method, see guidehttps://openapi.toppayment.com/sandbox/ng/pay/prePayhttps://openapi.toppayment.com/ng/pay/prePay
India (in)Pay-In · India, method, see guidehttps://openapi.toppayment.com/sandbox/in/pay/prePayhttps://openapi.toppayment.com/in/pay/prePay
Thailand (th)Pay-In · Thailand, method, see guidehttps://openapi.toppayment.com/sandbox/th/pay/prePayhttps://openapi.toppayment.com/th/pay/prePay
Vietnam (vn)Pay-In · Vietnam, method, see guidehttps://openapi.toppayment.com/sandbox/vn/pay/prePayhttps://openapi.toppayment.com/vn/pay/prePay
Peru (pe)Pay-In · Peru, method, see guidehttps://openapi.toppayment.com/sandbox/pe/pay/prePayhttps://openapi.toppayment.com/pe/pay/prePay
Brazil (br)Pay-In · Brazil, method, see guidehttps://openapi.toppayment.com/sandbox/br/pay/prePayhttps://openapi.toppayment.com/br/pay/prePay
Mexico (mx)Pay-In · Mexico, method, see guidehttps://openapi.toppayment.com/sandbox/mx/pay/prePayhttps://openapi.toppayment.com/mx/pay/prePay
Colombia (co)Pay-In · Colombia, method, see guidehttps://openapi.toppayment.com/sandbox/co/pay/prePayhttps://openapi.toppayment.com/co/pay/prePay
Bolivia (bo)Pay-In · Bolivia, method, see guidehttps://openapi.toppayment.com/sandbox/bo/pay/prePayhttps://openapi.toppayment.com/bo/pay/prePay
Pakistan (pk)Pay-In · Pakistan, method, see guidehttps://openapi.toppayment.com/sandbox/pk/pay/prePayhttps://openapi.toppayment.com/pk/pay/prePay
Bangladesh (bd)Pay-In · Bangladesh, method, see guidehttps://openapi.toppayment.com/sandbox/bd/pay/prePayhttps://openapi.toppayment.com/bd/pay/prePay
Turkey (tr)Pay-In · Turkey, method, see guidehttps://openapi.toppayment.com/sandbox/tr/pay/prePayhttps://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 / regionSandboxProduction
Philippines (ph)https://openapi.toppayment.com/sandbox/ph/pay/queryhttps://openapi.toppayment.com/ph/pay/query
Indonesia (id)https://openapi.toppayment.com/sandbox/id/pay/queryhttps://openapi.toppayment.com/id/pay/query
Nigeria (ng)https://openapi.toppayment.com/sandbox/ng/pay/queryhttps://openapi.toppayment.com/ng/pay/query
India (in)https://openapi.toppayment.com/sandbox/in/pay/queryhttps://openapi.toppayment.com/in/pay/query
Thailand (th)https://openapi.toppayment.com/sandbox/th/pay/queryhttps://openapi.toppayment.com/th/pay/query
Vietnam (vn)https://openapi.toppayment.com/sandbox/vn/pay/queryhttps://openapi.toppayment.com/vn/pay/query
Peru (pe)https://openapi.toppayment.com/sandbox/pe/pay/queryhttps://openapi.toppayment.com/pe/pay/query
Brazil (br)https://openapi.toppayment.com/sandbox/br/pay/queryhttps://openapi.toppayment.com/br/pay/query
Mexico (mx)https://openapi.toppayment.com/sandbox/mx/pay/queryhttps://openapi.toppayment.com/mx/pay/query
Colombia (co)https://openapi.toppayment.com/sandbox/co/pay/queryhttps://openapi.toppayment.com/co/pay/query
Bolivia (bo)https://openapi.toppayment.com/sandbox/bo/pay/queryhttps://openapi.toppayment.com/bo/pay/query
Pakistan (pk)https://openapi.toppayment.com/sandbox/pk/pay/queryhttps://openapi.toppayment.com/pk/pay/query
Bangladesh (bd)https://openapi.toppayment.com/sandbox/bd/pay/queryhttps://openapi.toppayment.com/bd/pay/query
Turkey (tr)https://openapi.toppayment.com/sandbox/tr/pay/queryhttps://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 / regionURL
Mexico (mx)https://openapi.toppayment.com/mx/pay/querySubOrders
Colombia (co)https://openapi.toppayment.com/co/pay/querySubOrders

Pay-Out orders

Country / regionDocs & paramsSandboxProduction
Philippines (ph)Pay-Out · Philippines, bankCode, see guidehttps://openapi.toppayment.com/sandbox/ph/disbursement/cashhttps://openapi.toppayment.com/ph/disbursement/cash
Indonesia (id)Pay-Out · Indonesia, bankCode, see guidehttps://openapi.toppayment.com/sandbox/id/disbursement/cashhttps://openapi.toppayment.com/id/disbursement/cash
Nigeria (ng)Pay-Out · Nigeria, bankCode, see guidehttps://openapi.toppayment.com/sandbox/ng/disbursement/cashhttps://openapi.toppayment.com/ng/disbursement/cash
India (in)Pay-Out · India, bankCode, see guidehttps://openapi.toppayment.com/sandbox/in/disbursement/cashhttps://openapi.toppayment.com/in/disbursement/cash
Thailand (th)Pay-Out · Thailand, bankCode, see guidehttps://openapi.toppayment.com/sandbox/th/disbursement/cashhttps://openapi.toppayment.com/th/disbursement/cash
Vietnam (vn)Pay-Out · Vietnam, bankCode, see guidehttps://openapi.toppayment.com/sandbox/vn/disbursement/cashhttps://openapi.toppayment.com/vn/disbursement/cash
Peru (pe)Pay-Out · Peru, bankCode, see guidehttps://openapi.toppayment.com/sandbox/pe/disbursement/cashhttps://openapi.toppayment.com/pe/disbursement/cash
Brazil (br)Pay-Out · Brazil, bankCode, see guidehttps://openapi.toppayment.com/sandbox/br/disbursement/cashhttps://openapi.toppayment.com/br/disbursement/cash
Mexico (mx)Pay-Out · Mexico, bankCode, see guidehttps://openapi.toppayment.com/sandbox/mx/disbursement/cashhttps://openapi.toppayment.com/mx/disbursement/cash
Colombia (co)Pay-Out · Colombia, bankCode, see guidehttps://openapi.toppayment.com/sandbox/co/disbursement/cashhttps://openapi.toppayment.com/co/disbursement/cash
Bolivia (bo)Pay-Out · Bolivia, bankCode, see guidehttps://openapi.toppayment.com/sandbox/bo/disbursement/cashhttps://openapi.toppayment.com/bo/disbursement/cash
Pakistan (pk)Pay-Out · Pakistan, bankCode, see guidehttps://openapi.toppayment.com/sandbox/pk/disbursement/cashhttps://openapi.toppayment.com/pk/disbursement/cash
Bangladesh (bd)Pay-Out · Bangladesh, bankCode, see guidehttps://openapi.toppayment.com/sandbox/bd/disbursement/cashhttps://openapi.toppayment.com/bd/disbursement/cash
Turkey (tr)Pay-Out · Turkey, bankCode, see guidehttps://openapi.toppayment.com/sandbox/tr/disbursement/cashhttps://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 / regionSandboxProduction
Philippines (ph)https://openapi.toppayment.com/sandbox/ph/disbursement/queryhttps://openapi.toppayment.com/ph/disbursement/query
Indonesia (id)https://openapi.toppayment.com/sandbox/id/disbursement/queryhttps://openapi.toppayment.com/id/disbursement/query
Nigeria (ng)https://openapi.toppayment.com/sandbox/ng/disbursement/queryhttps://openapi.toppayment.com/ng/disbursement/query
India (in)https://openapi.toppayment.com/sandbox/in/disbursement/queryhttps://openapi.toppayment.com/in/disbursement/query
Thailand (th)https://openapi.toppayment.com/sandbox/th/disbursement/queryhttps://openapi.toppayment.com/th/disbursement/query
Vietnam (vn)https://openapi.toppayment.com/sandbox/vn/disbursement/queryhttps://openapi.toppayment.com/vn/disbursement/query
Peru (pe)https://openapi.toppayment.com/sandbox/pe/disbursement/queryhttps://openapi.toppayment.com/pe/disbursement/query
Brazil (br)https://openapi.toppayment.com/sandbox/br/disbursement/queryhttps://openapi.toppayment.com/br/disbursement/query
Mexico (mx)https://openapi.toppayment.com/sandbox/mx/disbursement/queryhttps://openapi.toppayment.com/mx/disbursement/query
Colombia (co)https://openapi.toppayment.com/sandbox/co/disbursement/queryhttps://openapi.toppayment.com/co/disbursement/query
Bolivia (bo)https://openapi.toppayment.com/sandbox/bo/disbursement/queryhttps://openapi.toppayment.com/bo/disbursement/query
Pakistan (pk)https://openapi.toppayment.com/sandbox/pk/disbursement/queryhttps://openapi.toppayment.com/pk/disbursement/query
Bangladesh (bd)https://openapi.toppayment.com/sandbox/bd/disbursement/queryhttps://openapi.toppayment.com/bd/disbursement/query
Turkey (tr)https://openapi.toppayment.com/sandbox/tr/disbursement/queryhttps://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 / regionURL
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 / regionCurrencySandboxProduction
Philippines (ph)PHP, guidehttps://openapi.toppayment.com/sandbox/ph/balance/v1https://openapi.toppayment.com/ph/balance/v1
Indonesia (id)IDR, guidehttps://openapi.toppayment.com/sandbox/id/balance/v1https://openapi.toppayment.com/id/balance/v1
Nigeria (ng)NGN, guidehttps://openapi.toppayment.com/sandbox/ng/balance/v1https://openapi.toppayment.com/ng/balance/v1
India (in)INR, guidehttps://openapi.toppayment.com/sandbox/in/balance/v1https://openapi.toppayment.com/in/balance/v1
Thailand (th)THB, guidehttps://openapi.toppayment.com/sandbox/th/balance/v1https://openapi.toppayment.com/th/balance/v1
Vietnam (vn)VND, guidehttps://openapi.toppayment.com/sandbox/vn/balance/v1https://openapi.toppayment.com/vn/balance/v1
Peru (pe)PEN, guidehttps://openapi.toppayment.com/sandbox/pe/balance/v1https://openapi.toppayment.com/pe/balance/v1
Brazil (br)BRL, guidehttps://openapi.toppayment.com/sandbox/br/balance/v1https://openapi.toppayment.com/br/balance/v1
Mexico (mx)MXN, guidehttps://openapi.toppayment.com/sandbox/mx/balance/v1https://openapi.toppayment.com/mx/balance/v1
Colombia (co)COP, guidehttps://openapi.toppayment.com/sandbox/co/balance/v1https://openapi.toppayment.com/co/balance/v1
Bolivia (bo)BOB, guidehttps://openapi.toppayment.com/sandbox/bo/balance/v1https://openapi.toppayment.com/bo/balance/v1
Pakistan (pk)PKR, guidehttps://openapi.toppayment.com/sandbox/pk/balance/v1https://openapi.toppayment.com/pk/balance/v1
Bangladesh (bd)BDT, guidehttps://openapi.toppayment.com/sandbox/bd/balance/v1https://openapi.toppayment.com/bd/balance/v1
Turkey (tr)TRY, guidehttps://openapi.toppayment.com/sandbox/tr/balance/v1https://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.

ScenarioSandbox URLProduction URLDoc
Pay-inhttps://openapi.toppayment.com/crypto/sandbox/pay/directlyPayhttps://openapi.toppayment.com/crypto/pay/orderDirectlyCrypto Pay-In
Pay-in queryhttps://openapi.toppayment.com/crypto/sandbox/pay/queryhttps://openapi.toppayment.com/crypto/pay/queryOrder Inquiry
Pay-outhttps://openapi.toppayment.com/crypto/sandbox/disbursement/cashhttps://openapi.toppayment.com/crypto/disbursement/cashCrypto Pay-Out
Pay-out queryhttps://openapi.toppayment.com/crypto/sandbox/disbursement/queryhttps://openapi.toppayment.com/crypto/disbursement/queryOrder Inquiry
Balance inquiryhttps://openapi.toppayment.com/crypto/sandbox/balance/v1https://openapi.toppayment.com/crypto/balance/v1Balance Inquiry
  1. 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.
  2. 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


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