Skip to main content

Pay-In · Indonesia

TOPPAY TeamAbout 6 min

Overview

The Pay-In API lets merchants initiate collection transactions from customers. This page covers Indonesia (country code id) and supports two order placement modes:

ModePathDescription
Cashier mode/pay/prePayDefault mode. Returns cashierUrl for redirecting the customer to the platform H5 cashier to complete payment
API mode/pay/transOrderSpecify method in the request to receive payData / payDataType directly (VA, QRIS, etc.)

method (Pay-In payment codes for Indonesia) is listed in Regional Payment Guide — Indonesia.

Integration note

Cashier mode is enabled by default. To integrate API mode, contact support to request merchant whitelist access before integration.

Request Header

Shared by both modes:

FieldRequiredTypeDescription
Content-TypeMStringHTTP content type specification
Fixed value: application/json
Required for proper request parsing

Callback Version (shared by both modes)

Both order placement modes accept notifyVersion to specify the async notification payload version:

FieldRequiredTypeDescription
notifyVersionOString(8)Callback version
Optional v1 or v2 (case-insensitive)
Omitted or v1: callback contains base fields only
v2: when status is SUCCESS and the upstream channel supports it, the success callback may include actual payer information (see Notification below)
Default: v1

Cashier Mode (prePay)

After placing a pre-order, the merchant receives cashierUrl and redirects the customer to the platform cashier to select a payment method and complete payment.

Request URL

Domain: Prefer unified host openapi.toppayment.com (path unchanged); legacy country domain (e.g. global-id-openapi.toppayment.com) remains available.

EnvironmentURL
Sandboxhttps://openapi.toppayment.com/sandbox/id/pay/prePay
Productionhttps://openapi.toppayment.com/id/pay/prePay

Request Body

FieldRequiredTypeDescription
mchNoMString(32)Merchant number
Unique merchant identifier assigned by the platform
Used for merchant authentication and transaction routing
orderNumMString(64)Merchant order number
Unique transaction identifier
Format: Alphanumeric string
Used for transaction tracking and reference
amountMNumber(32,8)Transaction amount
Numeric type
Decimals are not allowed for Indonesia — pass an integer
Example: 100000
productDetailMString(100)Product detail
Transaction purpose or description
UTF-8 string
methodOString(16)Payment method (Indonesia)
Optional; if omitted, the customer selects on the cashier. Examples: QRIS, DANA, BNI — full list: Regional Payment Guide — Indonesia
timestampMString(13)Timestamp
Request timestamp in milliseconds
Example: 1749451858772
customerNameMString(64)Customer name
Payer name
UTF-8 string
customerEmailMString(64)Customer email
Payer email address
Valid email format
customerPhoneMString(32)Customer phone
Payer phone number
Valid phone number
expiryPeriodONumber(1–9999)Expiry period
Order validity in minutes
Example: 1440 (24 hours)
downNotifyUrlMString(255)Async notification URL
Webhook URL for transaction status updates
Valid HTTP/HTTPS URL
redirectUrlOString(512)Redirect URL
Browser redirect after successful payment (cashier mode)
Valid absolute http:// or https:// URL
Must share the same origin as a URL on the merchant redirect whitelist; if omitted or invalid, fallback rules apply (see below)
notifyVersionOString(8)Callback version
See Callback Version above
signMStringSignature
Digital signature for request authentication
See Signature

Request Body Example

Content-type: application/json

Response Body Parameters

FieldRequiredTypeDescription
successMBooleanRequest success status
true: success, false: failure
codeMStringResponse status code
9999: success; other values: failure
msgOStringResponse message
Human-readable status description
null on success
timeStampMNumberResponse timestamp
Server response time in milliseconds
dataMObjectResponse data object
Contains transaction details
orderNumMStringMerchant order number
Same as orderNum in the request
platOrderNumMStringPlatform order number
System-generated internal transaction reference
amountMNumberTransaction amount
feeMNumberFee
methodMStringPayment method (Indonesia)
As returned by the platform — see Regional Payment Guide — Indonesia
productDetailMStringProduct detail
customerNameMStringCustomer name
customerEmailMStringCustomer email
customerPhoneMStringCustomer phone
validTimeMNumberExpiry timestamp
Order expiry time in milliseconds
cashierUrlMStringCashier URL
URL to open the payment cashier

Response Example

Content-type: application/json

Cashier success redirect

After a successful payment, the payer’s browser can be redirected to a merchant-configured page. This capability is disabled by default. To enable it, contact support via Telegram; support will turn it on and configure a redirect URL whitelist (multiple URLs allowed).

You may pass optional redirectUrl when placing an order:

  • Must be an absolute http:// or https:// URL (relative paths and other schemes are not supported)
  • Redirect occurs only on payment success; failed or incomplete payments do not redirect
  • If a valid redirectUrl is provided and its origin matches the merchant whitelist: redirect as-is after success (no automatic orderNum append)
  • If omitted, empty, or invalid: redirect to the first whitelist URL with query parameter orderNum appended (same as the order request orderNum)
    Example: https://merchant.example.com/pay/result?orderNum=ID1234561
  • If redirectUrl is provided but its origin is not on the whitelist: no redirect after success (does not fall back to the first whitelist URL)

API Mode (transOrder)

The merchant specifies the payment method in the request and initiates the transaction directly with the payment channel. The response returns payData / payDataType (such as VA account number, QRIS code, or redirect link) without redirecting to the platform H5 cashier.

Request URL

EnvironmentURL
Sandboxhttps://openapi.toppayment.com/sandbox/id/pay/transOrder
Productionhttps://openapi.toppayment.com/id/pay/transOrder

Request Body

Compared with cashier mode, the difference is:

FieldRequiredTypeDescription
methodMString(16)Payment method (Indonesia)
Required in API mode. Examples: QRIS, DANA, BNI — full list: Regional Payment Guide — Indonesia

All other fields (including notifyVersion) are the same as cashier mode.

Request Body Example

Content-type: application/json

Response Body Parameters

Common response fields (success, code, msg, timeStamp, and orderNum, platOrderNum, amount, fee, method, productDetail, customerName, customerEmail, customerPhone, validTime in data) are the same as cashier mode. API mode focuses on:

FieldRequiredTypeDescription
payDataMStringPayment data
VA account number, QRIS string, redirect link, etc. — meaning depends on payDataType
payDataTypeMStringPayment data type
Values: VA, QR_CODE, QR_URL, CASHIER_URL
cashierUrlOStringCashier URL
Some channels may return this as well; in API mode, use payData as the primary field

payDataType Reference

payDataTypeDescriptionTypical method
VAVirtual account — merchant guides the customer to transfer to this accountBNI, BCA, MANDIRI, BRI bank VA
QR_CODEQRIS QR code content string — render as QR code on your sideQRIS
QR_URLQR code image or scan page URLSome QRIS / wallet scenarios
CASHIER_URLUpstream payment page redirect linkDANA, OVO wallets
Content-type: application/json

Notification

Async notifications are identical for both order placement modes. The callback payload version is determined by notifyVersion at order placement (defaults to v1 if omitted). The version field in the callback body matches it.

HTTP Request

FieldRequiredTypeDescription
Content-TypeMStringHTTP request content type specification
Fixed value: application/json

Notification Body (v1 / base fields)

FieldRequiredTypeDescription
platOrderNumMStringPlatform order number
System-generated internal transaction reference
versionMStringCallback version
Matches notifyVersion at order placement
Examples: v1, v2
orderNumMStringMerchant order number
Same as orderNum in the original request
amountMNumberTransaction amount
feeMNumberFee
customerNameMStringCustomer name
Payer name provided at order placement (not the actual payer account name)
customerEmailMStringCustomer email
customerPhoneMStringCustomer phone
statusMStringTransaction status
See Transaction Status Codes
signMStringSignature
Digital signature for callback verification

Notification Body (v2 extended fields)

When notifyVersion is v2 and status is SUCCESS, if the upstream channel returns payer information, the callback may additionally include the following fields (channel-dependent — omitted or empty when unavailable):

FieldRequiredTypeDescription
payerNameOStringPayer name
Actual payer account name (may differ from customerName at order placement)
payerAccountNoOStringPayer account number
Actual payer account
payerAccountBankOStringPayer bank
Actual payer bank or channel name

v2 notes

  • v2 only affects whether successful callbacks attempt to include payer information; non-success callbacks (e.g. failure) have the same structure as v1 without the extended fields.
  • Whether payerName / payerAccountNo / payerAccountBank are returned depends on whether the payment channel provides them in the upstream callback. Merchants should handle both cases.

Response

Important

Return only the string SUCCESS to acknowledge receipt of the notification.

{
    "platOrderNum": "PRE2009165141186183168",
    "version": "v1",
    "orderNum": "ID12345621",
    "amount": 100000,
    "fee": 2000,
    "customerName": "Budi",
    "customerEmail": "[email protected]",
    "customerPhone": "081234567890",
    "status": "SUCCESS",
    "sign": "m5++HHEOfaVL3opFSuihVE4kkdLaCyhpFVSSLJld8WeEhlH93Ido5MQQ6peWrf+8eCkQd127jesL9esQDdFAiGKkem5BwvqTAvZGQm9v7M33Sy+W58OkGkb3/8BxQwCLTIUouhwpj1TwIeqP3JWo3AFMm5qezH3JbVfOd1IZ9Gw="
}
Copyright © 2026 TOPPAY Team