Authentication & signature

All merchant REST requests and webhook signature verification share the same HMAC model.
Updated: 2026-08-05

Request headers (Merchant → BPN)

Header	Required	Notes	Example
`API-KEY`	Yes	Merchant apiKey	`ak_live_xxx`
`API-TIMESTAMP`	Yes	Unix epoch milliseconds	`1690000000000`
`API-SIGNATURE`	Yes	Algorithm below	`a1b2c3...`
`Content-Type`	Required for POST	`application/json`

Signature algorithm

POST message = compactJson(body) + "&" + timestampMillis
GET message  = sortedDecodedQueryPairs + "&" + timestampMillis
signature = HEX_LOWER( HMAC_SHA256( key = apiSecret(UTF-8), message ) )

For GET, sign the query string representation, not a JSON body: sort parameter names ascending, take the first decoded value for each name, join key=value pairs with &, then append &timestampMillis. Do not percent-encode values again when signing. Only a GET with no query parameters uses an empty signing body. Avoid duplicate parameter names.

Example: GET /v1/virtual-account/sub/get?virtualAccountId=12345 signs virtualAccountId=12345&<timestampMillis>.

compactJson: JSON serialization without insignificant whitespace; field order must match the body bytes you actually send.

Large clock skew fails verification — keep NTP sync.

Code examples

Python

Java

Webhook verification

When you receive a callback, verify API-SIGNATURE with the same algorithm. See Webhooks Overview.

GET example in Python

Pass query values as strings. Sign the decoded values; let the HTTP client encode the URL once. This helper deliberately rejects repeated keys by accepting a dictionary of scalar values.

Authentication

Authentication & signature#

Request headers (Merchant → BPN)#

Signature algorithm#

Code examples#

Python#

Java#

Webhook verification#

GET example in Python#