Skip to main content

Pay-In · Indonesia

TOPPAY TeamAbout 8 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 choose the async notification payload version. The value is case-insensitive and stored in lowercase on the order. Later automatic notifications and resends use the version saved on the order.

FieldRequiredTypeDescription
notifyVersionOString(8)Callback version
Optional v1, v2, or v3 (case-insensitive)
Omitted or v1: callback contains base fields only
v2: when status is SUCCESS and the upstream provides a valid value, the success callback may include actual payer information
v3: includes every v2 field, and adds retrieval reference number rrn when payment succeeds and the upstream provides a valid value. Further top-level fields at the same level as rrn may be added later
Default: v1. Invalid values are rejected

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 payload version is the notifyVersion saved at order placement (defaults to v1 if omitted). Identify the callback by the top-level version field ("version":"v3" for V3). Do not use the order-request field name notifyVersion to decide which callback you received.

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 the notifyVersion saved on the order
Examples: v1, v2, v3
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 or v3 and status is SUCCESS, the callback may include the following fields if the upstream provides a valid payer value. A field with no valid value is omitted:

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

Non-success callbacks use the same structure as v1 and do not include these fields. Availability depends on the payment channel. Treat a missing field as normal.

Notification Body (v3 extended fields)

v3 includes the base fields and the payer fields above. When payment succeeds and the upstream provides a valid retrieval reference number, it also includes:

FieldRequiredTypeDescription
rrnOStringRetrieval Reference Number
Channel retrieval reference for a successful QRIS (and similar) payment
Receive it as a string and keep leading zeros. Do not parse it as a number
Omitted when no valid value is available

A v3 payload is always a flat JSON object. The platform may later add more top-level fields at the same level as rrn. The field set is not fixed. Ignore unknown fields you do not use yet. Do not check a fixed field count, and do not reject unknown top-level fields.

Payer fields and rrn are independent. If one value is empty, only that field is omitted. Empty strings and null are not sent and do not take part in the signature.

v1 and v2 callbacks do not include rrn or later V3 fields. After a successful payment, Pay-In order query may return string rrn only when that order is v3. v1 and v2 orders do not return it.

Callback Verification

v1, v2, and v3 use the same RSA rules. There is no new signature type. The platform signs with the platform private key. Verify with the platform public key from API settings in the merchant console. Concatenation and decryption are described in Signature.

Verification setup:

  1. Read the raw JSON into a Map or JSONObject and keep every top-level field.
  2. Read top-level version. "version":"v3" means V3.
  3. Exclude sign. Sort the other actually received non-empty top-level field names in ASCII order, then concatenate values only, with no separator.
  4. Decrypt sign with the platform public key. Verification passes when the plaintext matches step 3.
  5. Read business fields and update the order only after verification succeeds. Then return HTTP 200 with the body SUCCESS only.

Do not verify v3 against a fixed field allowlist. Later sibling fields must be included. Do not deserialize into a fixed-field object before verification — dropped unknown fields will make verification fail. Concatenate amounts and rrn from the raw payload text. Do not convert them to numbers and reformat them first.

For the v3 success callback below, the signed field names in ASCII order are amount, customerEmail, customerName, customerPhone, fee, orderNum, payerAccountBank, payerAccountNo, payerName, platOrderNum, rrn, status, version. The plaintext is:

100000budi@email.comBudi0812345678902000ID12345621BNI081234567890BUDI SANTOSOPRE2009165141186183168021116498933SUCCESSv3

Do not invent empty values for optional fields that are absent. Walk the keys you actually received. Do not hard-code the field list from this example.

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="
}