Basic rules
Basic information
All ordinary API calls use HTTPS. Endpoint URLs in the API Reference are shown as {apiBaseUrl} plus the versioned interface Path, such as {apiBaseUrl}/intl/v1/payment/order/create. {apiBaseUrl} is the platform-issued HTTPS API domain and must not be sent literally. The test and production environments use different {apiBaseUrl} values. Complete integration with the test environment first, then switch to the production {apiBaseUrl}, production merchant number, API Key and API Secret at go-live. Do not disable TLS certificate verification in production clients.
The public v1 API is a server-to-server API. Requests must be sent from the merchant backend. Never place API credentials, signing code or raw recipient data in browsers, mobile apps, mini-programs or frontend source code.
Data format
POST requests use JSON request bodies. GET requests use Query parameters and have an empty request body. The request signing payload always signs the exact request body that is sent on the wire.
Ordinary API POST requests must send Content-Type: application/json. Ordinary API GET and POST requests must send Accept: application/json. Ordinary API responses with JSON bodies must return Content-Type: application/json. Webhook requests must also send Content-Type: application/json.
The body size limit for POST requests is 64 KiB. The public API does not accept XML, form-data or multipart payloads in v1.
JSON field order is not stable and has no business meaning. Read responses by field name, not by position. Numeric amount fields use decimal strings so that merchants can avoid floating-point precision loss.
For create requests, amount.value is the only amount field sent by the merchant. The selected productCode determines the transaction currency and allowed amount precision. For example, currencies with amountScale 0 only accept integer major-unit amounts, while currencies with amountScale 2 accept up to two decimal places. Responses, query results and Webhook events still return amount.currency so merchant systems can reconcile without parsing productCode. Invalid amount format returns AMOUNT_FORMAT_INVALID; too many decimal places for the selected product and currency returns HTTP 422 with AMOUNT_PRECISION_INVALID. This error usually corresponds to request Body amount.value.
Parameter compatibility
The platform may add optional response fields in later versions. Merchant systems must ignore unknown response fields. Request schemas are intentionally strict; unknown request fields may be rejected.
Do not send null, empty strings or empty arrays unless a field description explicitly allows them. Required fields must be present with a valid value.
For create requests, one business order is identified by merchant number plus merchantOrderNo. Query requests only support querying by merchantOrderNo.
Character set
Ordinary API request bodies, response bodies and Webhook bodies all use UTF-8 encoding. Avoid control characters and characters that cannot be stored safely in downstream clearing, reconciliation or support systems. Field length limits are byte-safe API limits; a field can be rejected even when it looks visually short but exceeds the configured maximum.
Time format
Public timestamps use Unix seconds counted from 1970-01-01T00:00:00Z. They are timezone-independent and do not carry a merchant or server timezone. Convert them to the required local timezone only for display. Header Timestamp values are Unix timestamp text in seconds because HTTP Header values are strings. The request Timestamp Header is normally accepted within ±300 seconds of the API service time.
Body fields such as createTime, updateTime and expireTime use Unix timestamps in seconds and are returned as JSON numbers. For Payment and Payout orders, updateTime is the time when the current business status became effective. For example, when status is SUCCEEDED, updateTime is the success time; when status is FAILED, it is the failure time. For balances, updateTime is when the balance data was updated. The public interface version is 1.0. It is part of the published contract and is not sent as a request Header value.
Common request Header
Ordinary API requests use separate signing Headers:
| Header | Required | Description |
|---|---|---|
Accept | Yes | Fixed as application/json, indicating that the merchant client expects a JSON response. It is not included in the signing payload. |
Content-Type | Yes for POST; not sent for GET | POST request body media type, fixed as application/json. It is not included in the signing payload. |
Api-Key | Yes | Merchant API Key obtained from the merchant portal. |
Timestamp | Yes | Unix request signing timestamp text in seconds. |
Nonce | Yes | Request random string unique under the same API Key. |
Signature | Yes | v1= plus lowercase HMAC-SHA256 request signature. Never send the API Secret. |
The complete signing rule is documented in signing and verification. Header names are case-insensitive. The documentation shows canonical unprefixed Header names; do not add product, company or brand prefixes.
Common response Headers
| Header | Returned when | Description |
|---|---|---|
Content-Type | All ordinary API responses with a JSON body | Fixed as application/json. |
Request-Id | All ordinary API responses | Request tracking ID used for support and log correlation. |
Timestamp | Ordinary API responses where the API Key can be identified | Response signing time as Unix timestamp text in seconds. |
Nonce | Ordinary API responses where the API Key can be identified | Response random string, unique for this response. |
Signature | Ordinary API responses where the API Key can be identified | v1= plus lowercase HMAC-SHA256 response signature. |
Request identifier
All ordinary API responses include Request-Id in the response Header. Error responses include error.code in the response body. Ordinary API responses where the API Key can be identified also include Timestamp, Nonce and Signature for verifying the exact raw response body. Authentication-failure responses where the API service cannot identify the API Key might not include signature headers. For support, provide the merchant order number first, then include the Request-Id response Header and response Body error.code when available.
For support tickets, provide only the environment, request time, merchant order number, HTTP status code, Request-Id response Header, error.code and referenceNo when the issue involves a payer receipt or recipient institution investigation. Do not provide API Secrets, Webhook Secrets, signatures or full sensitive request bodies.
Error information
Use the HTTP status code to decide the category of the failure. Use error.code for program branching. Do not parse error.message for business logic because message text can be adjusted for readability.
The ordinary error response body has a stable shape:
| Field | Description | Example value |
|---|---|---|
error.code | Stable machine-readable error code. Use this field for program branching, alert aggregation and troubleshooting. | PARAMETER_INVALID |
error.message | Merchant-safe error description for technical users. Treat it as a human-readable explanation, not as a stable program key. | amount.value must be a positive decimal string. |
Error code identifies what happened in a stable way. Error description explains the failure in readable language and can be adjusted without changing API semantics.
Error codes use uppercase snake case, such as PARAMETER_INVALID and INSUFFICIENT_BALANCE.
Example:
{
"error": {
"code": "PARAMETER_INVALID",
"message": "amount.value must be a positive decimal string."
}
}Typical error codes include parameter errors such as PARAMETER_INVALID, authentication errors such as INVALID_SIGNATURE, permission errors such as PERMISSION_DENIED, order lookup errors such as ORDER_NOT_FOUND, business rejections such as INSUFFICIENT_BALANCE, frequency limits such as FREQUENCY_LIMITED, platform errors such as INTERNAL_ERROR, explicit unknown create results such as ORDER_RESULT_UNKNOWN, and upstream gateway errors such as GATEWAY_ERROR or GATEWAY_TIMEOUT.
Each API page lists the concrete error codes, HTTP status, description and handling guidance that apply to that API.
Response handling model
Handle ordinary API responses in three layers:
| Layer | Fields | When present | Meaning and handling |
|---|---|---|---|
| HTTP status | HTTP status | Every ordinary API response | 200 means the API call succeeded. 4xx means the request or business condition was rejected; handle it according to error.code. 5xx, timeout, network loss or an unverifiable response means the create result may be unknown. Query by the original merchantOrderNo; if repeated queries still find no order, resend only the unchanged request with that same number. |
| Request error | error.code, error.message | Non-2xx error response body | Explains why this API request failed. Use error.code for stable branching and error.message only for technical reading. |
| Order status | status | Order resources, query responses and Webhook order data | Current Payment or Payout business lifecycle status. Merchant-side order state should primarily follow status. |
| Failure reason | failReason | Only when the order reaches a non-success final state, such as Payment CANCELED or Payout FAILED. | Merchant-safe explanation for operations display or troubleshooting. It is not a second status field; merchant systems should still use status as the only order-state decision field. |
error and failReason are separate concepts: error explains why the current request failed, while failReason explains why an order reached a non-success final status. For example, HTTP 200 can return a Payout order with status=FAILED; the API call succeeded, but the Payout failed and merchants can show or review failReason. HTTP 422 means the creation request itself was rejected by business validation, so merchants should read error.code, error.message and the interface field description.
Merchant custom data and upstream reference
Payment and Payout create requests can include customData when needed. referenceNo is not a merchant request field; the platform returns it on order resources and final-status Webhooks when an upstream reference is available:
| Field | Purpose | Handling rules |
|---|---|---|
customData | Merchant-defined key-value pairs for linking the order to merchant-side objects such as carts, customers, batches or internal journals. | Optional in create requests, up to 20 keys. Keys use lowerCamelCase and values are strings. Echoed on the order resource and final-status Webhook for correlation and troubleshooting only; not used for idempotency, lookup, routing, risk or settlement. An idempotent duplicate returns the customData saved from the first accepted request and never merges or overwrites it. |
referenceNo | Upstream payment-network, payment-institution or recipient-institution reference number. | Returned only when available in responses and Webhooks. Use it to match payer receipts or recipient institution investigation results to the order. It is not the merchant order number, platform order number or channel order number, and is not used for idempotency or ordinary lookup. |
Do not put API keys or Secrets, Webhook Secrets, signatures, authentication Tokens, bank card numbers, full recipient bank or wallet account numbers, identity numbers, phone numbers, email addresses or other sensitive data in customData.
Platform order numbers
platOrderNo remains an opaque string of 1–32 characters. Preserve the exact value in API queries, Webhooks, databases and reconciliation files. New deployments may issue 24-character values such as PHI112606010000000001001; the last 13 characters are decimal digits. Historical values such as 3002260601000001001 remain valid. Do not enforce a 24-character public input regex, infer authorization or routing from the prefix, or convert the value to a number. The current API environment is selected by its configured endpoint, never by characters in an order number.
Write spreadsheet identifiers as text cells. When importing CSV into Excel, select Text for the identifier column. Do not add ="..." formulas or an extra leading character to machine reconciliation files. If Excel has already rounded a historical numeric identifier, obtain its original value instead of guessing.