OmiPay V3 API Reference

Acquiring APIs for merchants: multi-channel order placement, refunds, order/refund queries, hosted checkout, card-token payments, and exchange-rate queries. All endpoints are called over HTTPS with JSON (UTF-8) requests and responses.

Service Endpoints

Sandboxhttps://tapi.omipay.net

Productionhttps://api.omipay.net

Open api Dochttps://api.omipay.net/openapi/v3.json

Updated 2026-09-04 · Version 1.0.0

Product Overview

Omipay is a professional mobile payment platform headquartered in Sydney, Australia, with long-standing expertise in the Australian local and cross-border payment markets. It provides secure, convenient, and customizable aggregated payment solutions for retail, food & beverage, e-commerce, and subscription businesses.

Omipay aggregates major payment channels such as WeChat Pay and Alipay, and also offers its own card payment (Card Pay) capability. Merchants can accept payments across all channels through a single unified API:

In-Store Payments: QR-code payments, merchant-scan (auth-code) payments, and POS terminal payments, covering every in-store checkout scenario;
Online Payments: Online (web/wap), JSAPI, in-app, and mini-program payments, covering websites and mobile apps in all forms;
Card Pay: Hosted checkout + card-binding Token payments. Card data is encrypted end-to-end with RSA-2048 and 3DS verification is supported. Merchants can accept card payments in PCI DSS compliance without ever touching card numbers, and support recurring charges such as subscriptions and renewals;
Full Supporting Capabilities: unified refunds, order queries, real-time exchange-rate queries, and asynchronous result notifications.

Payment Scenarios

2.1 In-Store Payments

For face-to-face, in-store checkout.

Scenario	Endpoint	Description
QR-code Payment	`POST /omipay/api/v3/order/qr`	After the merchant creates an order, a QR code is shown (customer scans merchant). The customer scans it with WeChat/Alipay to enter an H5 cashier page and complete payment. The response returns `qrcode` (the channel payment string to encode into the QR image) and `pay_url` (the H5 cashier page URL).
Merchant-Scan Payment	`POST /omipay/api/v3/order/scan`	The merchant scans the customer's payment code (auth code) with a scanning device. The order is paid immediately upon creation — fast and seamless.
POS Payment	`POST /omipay/api/v3/order/pos`	Payment is initiated through a bound Omipay POS terminal, ideal for integrated checkout counters.

2.2 Online Payments

For remote payments on websites and apps.

Scenario	Endpoint	Description
Online Payment	`POST /omipay/api/v3/order/online`	For PC websites (web) and mobile websites (wap). After ordering, the customer is redirected to `pay_url` to complete payment.
In-App Payment	`POST /omipay/api/v3/order/app`	Launches the WeChat/Alipay client inside an Android/iOS app to complete payment. The response returns the order string needed to invoke the SDK. platform only supports `WECHATPAY` (WeChat) and `ALIPAYONLINE` (Alipay).
JSAPI Payment	`POST /omipay/api/v3/order/jsapi`	The customer pays directly inside the WeChat built-in browser (Official-Account web page). Optionally returns a PC payment URL (`show_pc_pay_url=1`).
Mini-Program Payment	`POST /omipay/api/v3/order/applet`	Launches payment inside a WeChat/Alipay mini-program.

2.3 Card Pay

Scenario A: Hosted Checkout Card Payment

After creating an order, the merchant receives a checkout_url. The customer completes card entry, 3DS verification, and payment on the Omipay hosted checkout page;
The card number and CVV are encrypted in the browser with the order-specific RSA-2048 public key (OAEP-SHA256) before submission. The merchant system never touches card data, meeting PCI DSS compliance requirements;
The payment result is pushed via asynchronous notification, and the merchant can also actively query the order status;
Orders are automatically closed if not completed within 30 minutes.

Scenario B: Card Binding + Token Payment (Recurring Charges)

POST /omipay/api/v3/token/bind initiates card binding and returns a bind_url. The customer completes card entry and 3DS verification on the hosted binding page;
After binding succeeds, the merchant obtains the card_token via asynchronous notification or the token-list endpoint;
For subsequent charges: POST /omipay/api/v3/order/token with the card_token to charge the card without requiring the customer to re-enter card details — ideal for recurring scenarios such as subscriptions and membership renewals;
Unbinding is supported (POST /omipay/api/v3/token/unbind) and takes effect immediately.

Integration Rules

3.1 Protocol Rules

Item	Rule
Transport Protocol	HTTPS, TLS 1.2 or above
Submission Method	POST / GET
Data Format	Both request and response are JSON
Character Encoding	UTF-8
Parameter Passing	Business parameters are passed as QueryString
Timeout	The request timestamp must be within ±60 minutes of the server time

3.2 Parameter Conventions

Item	Rule
Field Naming	All in snake_case (lowercase with underscores)
Amount Unit	Integer, smallest currency unit (cents). E.g. `$10.00` is sent as `1000`
Timestamp	`timestamp` is Unix milliseconds
Time Format	`yyyy-MM-dd HH:mm:ss`
Time Zone	`Australia/Sydney` (IANA time zone ID)
Unified Response Envelope	`return_code` / `success` / `error_code` / `error_msg` + business fields
Idempotency	`out_order_no` (merchant order number) must be unique per merchant. Duplicate submission returns `DUPLICATE_ORDER` (card payments) or `OUT_TRANSACTION_PAID` (other channels); the same applies to `out_refund_no`

3.3 Header Rules

Header	Required	Description
`Content-Type`	Yes (POST)	`application/json; charset=utf-8`
`Accept-Language`	No	Language of error messages: `en` (English, default) / `zh-CN` (Chinese)

3.4 Signature Authentication

All /omipay/api/v3/* endpoints require signature authentication. Merchants receive the following when onboarding with Omipay:

m_number: Merchant number
secret_key: Secret key (kept only on the merchant's server; never distribute to the front-end or embed in client code)

Authentication parameters (passed as query):

Parameter	Description
`m_number`	Merchant number
`timestamp`	Unix millisecond timestamp; must be within ±60 minutes of the server time
`nonce_str`	Random string; must be unique for every request (replay protection)
`sign`	Signature, see below

Signature algorithm:

Code

stringToSign = m_number & timestamp & nonce_str & secret_key
sign         = UpperHex( HMAC-SHA256( key = secret_key, message = stringToSign ) )

The signature is a 64-character uppercase hexadecimal string, generated in uppercase.

Example (pseudo-code):

Signature Example (Python)

import hmac, hashlib, time, uuid

m_number  = "000000"
secret    = "your_secret_key"
ts        = str(int(time.time() * 1000))
nonce     = uuid.uuid4().hex

sign_src  = f"{m_number}&{ts}&{nonce}&{secret}"
sign      = hmac.new(secret.encode(), sign_src.encode(), hashlib.sha256).hexdigest().upper()

Authentication failure error codes: UNAUTHORIZED (missing parameters), MERCHANT_NOT_FOUND (merchant number does not exist or is deleted), TIMESTAMP_EXPIRED (timestamp out of window), SIGNATURE_FAILED (signature mismatch).

3.5 Common Error Codes

error_code	Meaning	Suggestion
`SUCCESS`	Success	——
`FAIL`	Business failure (generic)	Check `error_msg`
`SYSTEM_ERROR`	System error	Retry with the same order or contact support
`PARAMETER_INVALID`	Invalid parameter	Fix the parameter and retry
`UNAUTHORIZED`	Missing authentication parameters	Check m_number / timestamp / nonce_str / sign
`SIGNATURE_FAILED`	Signature mismatch	Verify the signature algorithm and secret key
`TIMESTAMP_EXPIRED`	Timestamp out of the time window	Calibrate the clock and retry
`MERCHANT_NOT_FOUND`	Merchant number does not exist or is deleted	Check the merchant number
`TOO_MANY_REQUESTS`	Too many requests	Back off and retry
`DUPLICATE_REQUEST`	Concurrent duplicate request	Do not submit the same order concurrently
`DUPLICATE_ORDER`	Duplicate merchant order number (card payments)	Use a new order number or query the original order
`OUT_TRANSACTION_PAID`	Payment already exists for this external order number (other channels)	Same as above
`CURRENCY_ERROR`	Currency not supported	Check the currency parameter
`PLATFORM_NOT_SUPPORTED`	Payment platform not supported	Check the allowed platform values for each endpoint
`WEBSTORE_NOT_EXISTS`	Store does not exist	Check `o_number`
`ORDER_NO_ERROR`	Invalid or expired order number	Create a new order
`TRANSACTION_NOT_FOUND` / `ORDER_NOT_FOUND`	Transaction/order does not exist	Check the order number
`TRANSACTION_IN_PROGRESS`	Transaction in progress	Wait for the result; do not resubmit
`ORDER_CLOSED`	Order closed (timed out)	Create a new order
`INVALID_CARD_NUMBER` / `INVALID_CVV` / `INVALID_EXPIRY_MONTH` / `INVALID_EXPIRY_YEAR` / `CARD_EXPIRED`	Card info validation failed	Prompt the customer to check card details
`CARD_DECRYPT_FAILED` / `CARD_PROCESSING_FAILED` / `PAYMENT_PROCESSING_FAILED`	Card processing error	Contact support
`PAYMENT_FAILED` / `BIND_FAILED`	Payment/binding failed	Check `error_msg`; may prompt the customer to retry
`TOKEN_NOT_FOUND` / `CARD_TOKEN_INVALID_STATUS` / `CARD_NOT_READY`	card_token invalid or in an abnormal status	Check the token or guide the customer to re-bind
`REFUND_NOT_ALLOWED` / `REFUND_FAILED` / `AMOUNT_OVER_LIMIT`	Refund not allowed / failed / exceeds refundable amount	Check the refundable amount and retry

3.6 Asynchronous Notification

After a payment, binding, or refund reaches a final state, Omipay sends a JSON notification via POST to the notify_url provided by the merchant when creating the order:

The notification body contains nonce_str, timestamp, sign (HMAC-SHA256, same algorithm as §3.4), and order fields (order_no, out_order_no, total_amount (cents), order_time, pay_time, etc.);
The merchant must verify the signature, process the business logic after successful verification, and respond with HTTP 200;
A non-200 response is treated as a failure. Omipay retries on a 15s / 30s / 1m / 5m / 30m / 1h / 2h backoff schedule, up to 8 attempts;
The same order may produce multiple notifications; the merchant must handle them idempotently;
The notification URL must be a publicly reachable HTTPS URL.

Notification body fields:

Field	Type	Description
`nonce_str`	string	Random string for this notification (replay protection).
`timestamp`	integer(int64)	Unix milliseconds when the notification was sent.
`sign`	string	HMAC-SHA256 signature, 64-char uppercase hex. Same algorithm as §3.4.
`order_no`	string	The Omipay system order number.
`out_order_no`	string	The merchant order number.
`total_amount`	integer	The order amount in cents (smallest currency unit).
`currency`	string	The currency code (e.g. AUD).
`order_time`	string	The order creation time, `yyyy-MM-dd HH:mm:ss`.
`pay_time`	string	The payment completion time, `yyyy-MM-dd HH:mm:ss`.
`status`	string	The final status (e.g. `SUCCESS`, `FAIL`).

Example notification body:

json

{
  "nonce_str": "9d4a1c7e8f2b4c0a8e6d1f3a5b7c9d0e",
  "timestamp": "1756872000000",
  "sign": "5F1A3B…64-char-uppercase-hex",
  "order_no": "TRC260903XXXXXXXXXX",
  "out_order_no": "2026090300001",
  "total_amount": 1000,
  "currency": "AUD",
  "order_time": "2026-09-03 12:00:00",
  "pay_time": "2026-09-03 12:00:05",
  "status": "SUCCESS"
}

POST/omipay/api/v3/order/qr

Create QR-code payment order

Creates a QR-code payment order. On success the response contains the order number, the payment URL, and the QR-code payload to render for the payer.

Parameters

order_name

string

The order name/title.

currencyrequired

string

The currency code (e.g. AUD).

amountrequired

any

The order amount in cents (smallest currency unit).

notify_url

string

The asynchronous payment-notification callback URL. Notifications are sent only for successful payments — failed payments are NOT notified (poll order/query instead), and refunds are never notified. Omit this parameter to receive no asynchronous notification.

out_order_norequired

string

The merchant order number (must be unique per merchant).

platformrequired

string

WECHATPAYWeChat Pay

ALIPAYAlipay

UPIUnionPay International

o_number

string

The branch number.

pos_no

string

The POS machine number.

m_numberrequired

string

Merchant number issued by Omipay. Identifies the merchant account whose secret key is used to sign the request.

timestamprequired

string

Request time in milliseconds since the Unix epoch, sent as a string (e.g. "1756872000000"). The signature is computed over this literal string. Must be within 60 minutes of the server time (up to 5 minutes of future skew allowed).

nonce_strrequired

string

A unique random string for this request, used for replay protection. Generate a fresh value for every request.

signrequired

string

HMAC-SHA256 signature, uppercase hexadecimal. Computed over the string "m_number&timestamp&nonce_str&secret_key" using the merchant's secret key as the HMAC key.

Headers

Accept-Language

string

Optional. Language of the returned error messages: en (English, default) / zh-CN (Chinese).

Content-Type

string

Optional. application/json; charset=utf-8 by default.

Responses

200

OK

order_norequired

string

The transaction order number.

qrcoderequired

string

The QR code content.

pay_urlrequired

string

The payment QR code URL.

platformrequired

string

The payment platform identifier.

return_coderequired

string

"SUCCESS" on success, "FAIL" on any error.

successrequired

boolean

Whether the operation was successful.

error_code

string

Specific error code on failure (e.g. SYSTEM_ERROR). Null on success.

error_msg

string

Localized error message on failure. Null on success.

Try it

Merchant Credentials

m_number timestamp nonce_str sign

Parameters

order_namecurrencyamountnotify_urlout_order_noplatformo_numberpos_no

Click "Send Request"

Response

200 · application/json

{
  "order_no": "TRC260903XXXXXXXXXX",
  "qrcode": "string",
  "pay_url": "string",
  "platform": "string",
  "return_code": "string",
  "success": true,
  "error_code": "string",
  "error_msg": "string"
}

400 · application/json

{
  "return_code": "FAIL",
  "success": false,
  "error_code": "PARAMETER_INVALID",
  "error_msg": "The amount field is required."
}

401 · application/json

{
  "return_code": "FAIL",
  "success": false,
  "error_code": "SIGNATURE_FAILED",
  "error_msg": "Signature verification failed."
}

500 · application/json

{
  "return_code": "FAIL",
  "success": false,
  "error_code": "SYSTEM_ERROR",
  "error_msg": "Internal server error."
}

POST/omipay/api/v3/order/online

Create online payment order

Online payment supports WeChat and Alipay, suitable for PC (web) and mobile (WAP) websites. On success the response contains the order number and the redirect URL the payer should be sent to.

Parameters

order_name

string

The order name/title.

currencyrequired

string

The currency code (e.g. AUD).

amountrequired

any

The order amount in cents (smallest currency unit).

notify_url

string

The asynchronous payment-notification callback URL. Notifications are sent only for successful payments — failed payments are NOT notified (poll order/query instead), and refunds are never notified. Omit this parameter to receive no asynchronous notification.

out_order_norequired

string

The merchant order number (must be unique per merchant).

return_url

string

The synchronous return URL after payment.

typerequired

string

The online payment type: web or wap.

platform

string

ALIPAYONLINEAlipay Online

ALIPAYPLUSAlipay+

WECHATPAYWeChat

Default: ALIPAYONLINE

o_number

string

The branch number.

m_numberrequired

string

Merchant number issued by Omipay. Identifies the merchant account whose secret key is used to sign the request.

timestamprequired

string

Request time in milliseconds since the Unix epoch, sent as a string (e.g. "1756872000000"). The signature is computed over this literal string. Must be within 60 minutes of the server time (up to 5 minutes of future skew allowed).

nonce_strrequired

string

A unique random string for this request, used for replay protection. Generate a fresh value for every request.

signrequired

string

HMAC-SHA256 signature, uppercase hexadecimal. Computed over the string "m_number&timestamp&nonce_str&secret_key" using the merchant's secret key as the HMAC key.

Headers

Accept-Language

string

Optional. Language of the returned error messages: en (English, default) / zh-CN (Chinese).

Content-Type

string

Optional. application/json; charset=utf-8 by default.

Responses

200

OK

order_norequired

string

The transaction order number.

pay_urlrequired

string

The payment URL.

return_coderequired

string

"SUCCESS" on success, "FAIL" on any error.

successrequired

boolean

Whether the operation was successful.

error_code

string

Specific error code on failure (e.g. SYSTEM_ERROR). Null on success.

error_msg

string

Localized error message on failure. Null on success.

Try it

Merchant Credentials

m_number timestamp nonce_str sign

Parameters

order_namecurrencyamountnotify_urlout_order_noreturn_urltypeplatformo_number

Click "Send Request"

Response

200 · application/json

{
  "order_no": "TRC260903XXXXXXXXXX",
  "pay_url": "string",
  "return_code": "string",
  "success": true,
  "error_code": "string",
  "error_msg": "string"
}

400 · application/json

{
  "return_code": "FAIL",
  "success": false,
  "error_code": "PARAMETER_INVALID",
  "error_msg": "The amount field is required."
}

401 · application/json

{
  "return_code": "FAIL",
  "success": false,
  "error_code": "SIGNATURE_FAILED",
  "error_msg": "Signature verification failed."
}

500 · application/json

{
  "return_code": "FAIL",
  "success": false,
  "error_code": "SYSTEM_ERROR",
  "error_msg": "Internal server error."
}

POST/omipay/api/v3/order/app

Create in-app payment order

APP payment supports Alipay and WeChat. Invokes the Alipay or WeChat client within Android/iOS apps to complete payment. On success the response contains the order number and the order string to pass to the SDK.

Parameters

order_name

string

The order name/title.

amountrequired

any

The order amount in cents (smallest currency unit).

currencyrequired

string

The currency code (e.g. AUD).

out_order_norequired

string

The merchant order number (must be unique per merchant).

notify_url

string

The asynchronous payment-notification callback URL. Notifications are sent only for successful payments — failed payments are NOT notified (poll order/query instead), and refunds are never notified. Omit this parameter to receive no asynchronous notification.

platformrequired

string

ALIPAYONLINEAlipay Online

WECHATPAYWeChat Pay

o_number

string

The branch number.

app_id

string

The merchant's AppID (required for WeChat Pay).

m_numberrequired

string

Merchant number issued by Omipay. Identifies the merchant account whose secret key is used to sign the request.

timestamprequired

string

Request time in milliseconds since the Unix epoch, sent as a string (e.g. "1756872000000"). The signature is computed over this literal string. Must be within 60 minutes of the server time (up to 5 minutes of future skew allowed).

nonce_strrequired

string

A unique random string for this request, used for replay protection. Generate a fresh value for every request.

signrequired

string

HMAC-SHA256 signature, uppercase hexadecimal. Computed over the string "m_number&timestamp&nonce_str&secret_key" using the merchant's secret key as the HMAC key.

Headers

Accept-Language

string

Optional. Language of the returned error messages: en (English, default) / zh-CN (Chinese).

Content-Type

string

Optional. application/json; charset=utf-8 by default.

Responses

200

OK

order_norequired

string

The transaction order number.

order_stringrequired

string

The order string for the APP payment SDK.

return_coderequired

string

"SUCCESS" on success, "FAIL" on any error.

successrequired

boolean

Whether the operation was successful.

error_code

string

Specific error code on failure (e.g. SYSTEM_ERROR). Null on success.

error_msg

string

Localized error message on failure. Null on success.

Try it

Merchant Credentials

m_number timestamp nonce_str sign

Parameters

order_nameamountcurrencyout_order_nonotify_urlplatformo_numberapp_id

Click "Send Request"

Response

200 · application/json

{
  "order_no": "TRC260903XXXXXXXXXX",
  "order_string": "string",
  "return_code": "string",
  "success": true,
  "error_code": "string",
  "error_msg": "string"
}

400 · application/json

{
  "return_code": "FAIL",
  "success": false,
  "error_code": "PARAMETER_INVALID",
  "error_msg": "The amount field is required."
}

401 · application/json

{
  "return_code": "FAIL",
  "success": false,
  "error_code": "SIGNATURE_FAILED",
  "error_msg": "Signature verification failed."
}

500 · application/json

{
  "return_code": "FAIL",
  "success": false,
  "error_code": "SYSTEM_ERROR",
  "error_msg": "Internal server error."
}

POST/omipay/api/v3/order/jsapi

Create JSAPI payment order

Creates a JSAPI payment order for in-page payment within a mini-program or webview. On success the response contains the order number and the payment URL to invoke.

Parameters

order_name

string

The order name/title.

currencyrequired

string

The currency code (e.g. AUD).

amountrequired

any

The order amount in cents (smallest currency unit).

notify_url

string

The asynchronous payment-notification callback URL. Notifications are sent only for successful payments — failed payments are NOT notified (poll order/query instead), and refunds are never notified. Omit this parameter to receive no asynchronous notification.

redirect_url

string

The redirect URL after payment.

out_order_norequired

string

The merchant order number (must be unique per merchant).

direct_pay

any

Whether to pay directly without order detail page (1=yes, 0=no).

show_pc_pay_url

any

Whether to show the PC payment URL page (1=yes, 0=no).

o_number

string

The branch number.

pos_no

string

The POS machine number.

m_numberrequired

string

Merchant number issued by Omipay. Identifies the merchant account whose secret key is used to sign the request.

timestamprequired

string

Request time in milliseconds since the Unix epoch, sent as a string (e.g. "1756872000000"). The signature is computed over this literal string. Must be within 60 minutes of the server time (up to 5 minutes of future skew allowed).

nonce_strrequired

string

A unique random string for this request, used for replay protection. Generate a fresh value for every request.

signrequired

string

HMAC-SHA256 signature, uppercase hexadecimal. Computed over the string "m_number&timestamp&nonce_str&secret_key" using the merchant's secret key as the HMAC key.

Headers

Accept-Language

string

Optional. Language of the returned error messages: en (English, default) / zh-CN (Chinese).

Content-Type

string

Optional. application/json; charset=utf-8 by default.

Responses

200

OK

order_norequired

string

The transaction order number.

pay_urlrequired

string

The mobile payment URL.

pc_pay_urlrequired

string

The PC payment URL.

return_coderequired

string

"SUCCESS" on success, "FAIL" on any error.

successrequired

boolean

Whether the operation was successful.

error_code

string

Specific error code on failure (e.g. SYSTEM_ERROR). Null on success.

error_msg

string

Localized error message on failure. Null on success.

Try it

Merchant Credentials

m_number timestamp nonce_str sign

Parameters

order_namecurrencyamountnotify_urlredirect_urlout_order_nodirect_payshow_pc_pay_urlo_numberpos_no

Click "Send Request"

Response

200 · application/json

{
  "order_no": "TRC260903XXXXXXXXXX",
  "pay_url": "string",
  "pc_pay_url": "string",
  "return_code": "string",
  "success": true,
  "error_code": "string",
  "error_msg": "string"
}

400 · application/json

{
  "return_code": "FAIL",
  "success": false,
  "error_code": "PARAMETER_INVALID",
  "error_msg": "The amount field is required."
}

401 · application/json

{
  "return_code": "FAIL",
  "success": false,
  "error_code": "SIGNATURE_FAILED",
  "error_msg": "Signature verification failed."
}

500 · application/json

{
  "return_code": "FAIL",
  "success": false,
  "error_code": "SYSTEM_ERROR",
  "error_msg": "Internal server error."
}

POST/omipay/api/v3/order/scan

Create merchant-scan payment order

Creates a merchant-scan payment order from the payer's QR code / auth code. The payment is captured synchronously; the response returns the order number and the order time.

Parameters

order_name

string

The order name/title.

currencyrequired

string

The currency code (e.g. AUD).

amountrequired

any

The order amount in cents (smallest currency unit).

notify_url

string

The asynchronous payment-notification callback URL. Notifications are sent only for successful payments — failed payments are NOT notified (poll order/query instead), and refunds are never notified. Omit this parameter to receive no asynchronous notification.

out_order_norequired

string

The merchant order number (must be unique per merchant).

qrcoderequired

string

The payment QR code / auth code.

pos_no

string

The POS machine number.

m_numberrequired

string

Merchant number issued by Omipay. Identifies the merchant account whose secret key is used to sign the request.

timestamprequired

string

Request time in milliseconds since the Unix epoch, sent as a string (e.g. "1756872000000"). The signature is computed over this literal string. Must be within 60 minutes of the server time (up to 5 minutes of future skew allowed).

nonce_strrequired

string

A unique random string for this request, used for replay protection. Generate a fresh value for every request.

signrequired

string

HMAC-SHA256 signature, uppercase hexadecimal. Computed over the string "m_number&timestamp&nonce_str&secret_key" using the merchant's secret key as the HMAC key.

Headers

Accept-Language

string

Optional. Language of the returned error messages: en (English, default) / zh-CN (Chinese).

Content-Type

string

Optional. application/json; charset=utf-8 by default.

Responses

200

OK

order_norequired

string

The transaction order number.

out_order_norequired

string

The merchant order number.

order_timerequired

string

The order creation time.

platformrequired

string

The payment platform identifier.

return_coderequired

string

"SUCCESS" on success, "FAIL" on any error.

successrequired

boolean

Whether the operation was successful.

error_code

string

Specific error code on failure (e.g. SYSTEM_ERROR). Null on success.

error_msg

string

Localized error message on failure. Null on success.

Try it

Merchant Credentials

m_number timestamp nonce_str sign

Parameters

order_namecurrencyamountnotify_urlout_order_noqrcodepos_no

Click "Send Request"

Response

200 · application/json

{
  "order_no": "TRC260903XXXXXXXXXX",
  "out_order_no": "string",
  "order_time": "2026-09-03T12:00:00Z",
  "platform": "string",
  "return_code": "string",
  "success": true,
  "error_code": "string",
  "error_msg": "string"
}

400 · application/json

{
  "return_code": "FAIL",
  "success": false,
  "error_code": "PARAMETER_INVALID",
  "error_msg": "The amount field is required."
}

401 · application/json

{
  "return_code": "FAIL",
  "success": false,
  "error_code": "SIGNATURE_FAILED",
  "error_msg": "Signature verification failed."
}

500 · application/json

{
  "return_code": "FAIL",
  "success": false,
  "error_code": "SYSTEM_ERROR",
  "error_msg": "Internal server error."
}

POST/omipay/api/v3/order/applet

Create mini-program payment order

Creates a mini-program (applet) payment order. On success the response returns the order number and the SDK parameters needed to invoke the payment.

Parameters

model

string

The mall model (omipay for B2B2C, other for B2B).

order_name

string

The order name/title.

currencyrequired

string

The currency code (e.g. AUD).

amountrequired

any

The order amount in cents (smallest currency unit).

notify_url

string

The asynchronous payment-notification callback URL. Notifications are sent only for successful payments — failed payments are NOT notified (poll order/query instead), and refunds are never notified. Omit this parameter to receive no asynchronous notification.

out_order_norequired

string

The merchant order number (must be unique per merchant).

o_number

string

The branch number.

app_idrequired

string

The merchant's AppID (required for WeChat Pay).

customer_idrequired

string

The mall customer ID.

m_numberrequired

string

Merchant number issued by Omipay. Identifies the merchant account whose secret key is used to sign the request.

timestamprequired

string

Request time in milliseconds since the Unix epoch, sent as a string (e.g. "1756872000000"). The signature is computed over this literal string. Must be within 60 minutes of the server time (up to 5 minutes of future skew allowed).

nonce_strrequired

string

A unique random string for this request, used for replay protection. Generate a fresh value for every request.

signrequired

string

HMAC-SHA256 signature, uppercase hexadecimal. Computed over the string "m_number&timestamp&nonce_str&secret_key" using the merchant's secret key as the HMAC key.

Headers

Accept-Language

string

Optional. Language of the returned error messages: en (English, default) / zh-CN (Chinese).

Content-Type

string

Optional. application/json; charset=utf-8 by default.

Responses

200

OK

order_norequired

string

The transaction order number.

time_stamprequired

string

The payment timestamp.

nonce_strrequired

string

The payment nonce string.

packagerequired

string

The payment package.

sign_typerequired

string

The payment signature type.

pay_signrequired

string

The payment signature.

return_coderequired

string

"SUCCESS" on success, "FAIL" on any error.

successrequired

boolean

Whether the operation was successful.

error_code

string

Specific error code on failure (e.g. SYSTEM_ERROR). Null on success.

error_msg

string

Localized error message on failure. Null on success.

Try it

Merchant Credentials

m_number timestamp nonce_str sign

Parameters

modelorder_namecurrencyamountnotify_urlout_order_noo_numberapp_idcustomer_id

Click "Send Request"

Response

200 · application/json

{
  "order_no": "TRC260903XXXXXXXXXX",
  "time_stamp": "string",
  "nonce_str": "32-char random string (e.g. uuid4 hex)",
  "package": "string",
  "sign_type": "string",
  "pay_sign": "string",
  "return_code": "string",
  "success": true,
  "error_code": "string",
  "error_msg": "string"
}

400 · application/json

{
  "return_code": "FAIL",
  "success": false,
  "error_code": "PARAMETER_INVALID",
  "error_msg": "The amount field is required."
}

401 · application/json

{
  "return_code": "FAIL",
  "success": false,
  "error_code": "SIGNATURE_FAILED",
  "error_msg": "Signature verification failed."
}

500 · application/json

{
  "return_code": "FAIL",
  "success": false,
  "error_code": "SYSTEM_ERROR",
  "error_msg": "Internal server error."
}

POST/omipay/api/v3/order/pos

Create POS payment order

Creates a POS payment order for a registered POS terminal. The payment is captured synchronously; the response returns the order number and the order time.

Parameters

order_name

string

The order name/title.

currencyrequired

string

The currency code (e.g. AUD).

amountrequired

any

The order amount in cents (smallest currency unit).

notify_url

string

The asynchronous payment-notification callback URL. Notifications are sent only for successful payments — failed payments are NOT notified (poll order/query instead), and refunds are never notified. Omit this parameter to receive no asynchronous notification.

pos_norequired

string

The POS machine number.

out_order_norequired

string

The merchant order number (must be unique per merchant).

m_numberrequired

string

Merchant number issued by Omipay. Identifies the merchant account whose secret key is used to sign the request.

timestamprequired

string

Request time in milliseconds since the Unix epoch, sent as a string (e.g. "1756872000000"). The signature is computed over this literal string. Must be within 60 minutes of the server time (up to 5 minutes of future skew allowed).

nonce_strrequired

string

A unique random string for this request, used for replay protection. Generate a fresh value for every request.

signrequired

string

HMAC-SHA256 signature, uppercase hexadecimal. Computed over the string "m_number&timestamp&nonce_str&secret_key" using the merchant's secret key as the HMAC key.

Headers

Accept-Language

string

Optional. Language of the returned error messages: en (English, default) / zh-CN (Chinese).

Content-Type

string

Optional. application/json; charset=utf-8 by default.

Responses

200

OK

order_norequired

string

The transaction order number.

out_order_norequired

string

The merchant order number.

order_timerequired

string

The order creation time.

platformrequired

string

The payment platform identifier.

return_coderequired

string

"SUCCESS" on success, "FAIL" on any error.

successrequired

boolean

Whether the operation was successful.

error_code

string

Specific error code on failure (e.g. SYSTEM_ERROR). Null on success.

error_msg

string

Localized error message on failure. Null on success.

Try it

Merchant Credentials

m_number timestamp nonce_str sign

Parameters

order_namecurrencyamountnotify_urlpos_noout_order_no

Click "Send Request"

Response

200 · application/json

{
  "order_no": "TRC260903XXXXXXXXXX",
  "out_order_no": "string",
  "order_time": "2026-09-03T12:00:00Z",
  "platform": "string",
  "return_code": "string",
  "success": true,
  "error_code": "string",
  "error_msg": "string"
}

400 · application/json

{
  "return_code": "FAIL",
  "success": false,
  "error_code": "PARAMETER_INVALID",
  "error_msg": "The amount field is required."
}

401 · application/json

{
  "return_code": "FAIL",
  "success": false,
  "error_code": "SIGNATURE_FAILED",
  "error_msg": "Signature verification failed."
}

500 · application/json

{
  "return_code": "FAIL",
  "success": false,
  "error_code": "SYSTEM_ERROR",
  "error_msg": "Internal server error."
}

POST/omipay/api/v3/order/checkout

Create checkout order

Creates a hosted card-payment checkout order. On success the response contains the order number and the hosted checkout URL to redirect the payer to.

Parameters

currencyrequired

string

The three-letter currency code (ISO 4217). Currently only AUD is supported.

amountrequired

any

The order amount in cents (smallest currency unit). For AUD, 100 = $1.00. Minimum amount is 50 (i.e. $0.50).

notify_url

string

The asynchronous payment-notification callback URL. Notifications are sent only for successful payments — failed payments are NOT notified (poll order/query instead), and refunds are never notified. Omit this parameter to receive no asynchronous notification.

redirect_url

string

The URL the payer is redirected to after completing payment.

out_order_norequired

string

The merchant order number (must be unique per merchant).

o_numberrequired

string

The branch (store) number.

order_inforequired

string

Product information (required). JSON-format string array; each item has item_name (non-empty string), item_count (> 0) and item_price (> 0, a decimal in MAJOR units — dollars, NOT cents). The sum of item_price × item_count must equal amount ÷ 100 (amount is in cents). Example: [{"item_name":"Product A","item_count":1,"item_price":1.00}] matches amount=100.

delivery_is_required

any

Whether the order requires a shipping address.

shipping_info

string

Shipping information (required when delivery_is_required is true). JSON-format string. Example:

{
  "recipient_name": "Zhang San",
  "recipient_phone": "13800138000",
  "recipient_address": "Address"
}

m_numberrequired

string

Merchant number issued by Omipay. Identifies the merchant account whose secret key is used to sign the request.

timestamprequired

string

Request time in milliseconds since the Unix epoch, sent as a string (e.g. "1756872000000"). The signature is computed over this literal string. Must be within 60 minutes of the server time (up to 5 minutes of future skew allowed).

nonce_strrequired

string

A unique random string for this request, used for replay protection. Generate a fresh value for every request.

signrequired

string

HMAC-SHA256 signature, uppercase hexadecimal. Computed over the string "m_number&timestamp&nonce_str&secret_key" using the merchant's secret key as the HMAC key.

Headers

Accept-Language

string

Optional. Language of the returned error messages: en (English, default) / zh-CN (Chinese).

Content-Type

string

Optional. application/json; charset=utf-8 by default.

Responses

200

OK

order_norequired

string

The Omipay order number (card orders are prefixed with "TRC").

checkout_urlrequired

string

The checkout page URL.

return_coderequired

string

"SUCCESS" on success, "FAIL" on any error.

successrequired

boolean

Whether the operation was successful.

error_code

string

Specific error code on failure (e.g. SYSTEM_ERROR). Null on success.

error_msg

string

Localized error message on failure. Null on success.

Try it

Merchant Credentials

m_number timestamp nonce_str sign

Parameters

currencyamountnotify_urlredirect_urlout_order_noo_numberorder_infodelivery_is_requiredshipping_info

Click "Send Request"

Response

200 · application/json

{
  "order_no": "TRC260903XXXXXXXXXX",
  "checkout_url": "string",
  "return_code": "string",
  "success": true,
  "error_code": "string",
  "error_msg": "string"
}

400 · application/json

{
  "return_code": "FAIL",
  "success": false,
  "error_code": "PARAMETER_INVALID",
  "error_msg": "The amount field is required."
}

401 · application/json

{
  "return_code": "FAIL",
  "success": false,
  "error_code": "SIGNATURE_FAILED",
  "error_msg": "Signature verification failed."
}

500 · application/json

{
  "return_code": "FAIL",
  "success": false,
  "error_code": "SYSTEM_ERROR",
  "error_msg": "Internal server error."
}

POST/omipay/api/v3/refund

Refund order

Refunds an existing order. Card-payment orders (order numbers starting with "TRC") are refunded through the card channel; all other orders are refunded through their original payment channel.

Parameters

order_norequired

string

The system order number.

out_refund_norequired

string

The merchant refund number (must be unique per merchant).

amountrequired

any

The refund amount in cents (smallest currency unit).

pos_no

string

The POS machine number.

reason

string

The refund reason.

m_numberrequired

string

Merchant number issued by Omipay. Identifies the merchant account whose secret key is used to sign the request.

timestamprequired

string

Request time in milliseconds since the Unix epoch, passed as a string. Must be within 60 minutes of the server time (up to 5 minutes of future skew allowed).

nonce_strrequired

string

A unique random string for this request, used for replay protection. Generate a fresh value for every request.

signrequired

string

HMAC-SHA256 signature, uppercase hexadecimal. Computed over the string "m_number&timestamp&nonce_str&secret_key" using the merchant's secret key as the HMAC key.

Headers

Accept-Language

string

Optional. Language of the returned error messages: en (English, default) / zh-CN (Chinese).

Content-Type

string

Optional. application/json; charset=utf-8 by default.

Responses

200

OK

refund_norequired

string

The system refund number.

out_refund_norequired

string

The merchant refund number.

order_norequired

string

The system order number.

currencyrequired

string

The currency code.

amountrequired

any

The refund amount in cents.

refund_timerequired

string

The refund time.

platformrequired

string

The payment platform identifier.

statusrequired

string

The refund status (card refund only).

return_coderequired

string

"SUCCESS" on success, "FAIL" on any error.

successrequired

boolean

Whether the operation was successful.

error_code

string

Specific error code on failure (e.g. SYSTEM_ERROR). Null on success.

error_msg

string

Localized error message on failure. Null on success.

Try it

Merchant Credentials

m_number timestamp nonce_str sign

Parameters

order_noout_refund_noamountpos_noreason

Click "Send Request"

Response

200 · application/json

{
  "refund_no": "RFD260903XXXXXXXXXX",
  "out_refund_no": "R2026090300001",
  "order_no": "TRC260903XXXXXXXXXX",
  "currency": "AUD",
  "amount": 1000,
  "refund_time": "2026-09-03T12:00:00Z",
  "platform": "string",
  "status": "string",
  "return_code": "string",
  "success": true,
  "error_code": "string",
  "error_msg": "string"
}

400 · application/json

{
  "return_code": "FAIL",
  "success": false,
  "error_code": "PARAMETER_INVALID",
  "error_msg": "The amount field is required."
}

401 · application/json

{
  "return_code": "FAIL",
  "success": false,
  "error_code": "SIGNATURE_FAILED",
  "error_msg": "Signature verification failed."
}

500 · application/json

{
  "return_code": "FAIL",
  "success": false,
  "error_code": "SYSTEM_ERROR",
  "error_msg": "Internal server error."
}

GET/omipay/api/v3/order/query

Query order

Queries the status and details of an order by its Omipay order number or the merchant order number.

Parameters

order_no

string

The system order number.

out_order_no

string

The merchant order number.

m_numberrequired

string

Merchant number issued by Omipay. Identifies the merchant account whose secret key is used to sign the request.

timestamprequired

string

Request time in milliseconds since the Unix epoch, passed as a string. Must be within 60 minutes of the server time (up to 5 minutes of future skew allowed).

nonce_strrequired

string

A unique random string for this request, used for replay protection. Generate a fresh value for every request.

signrequired

string

HMAC-SHA256 signature, uppercase hexadecimal. Computed over the string "m_number&timestamp&nonce_str&secret_key" using the merchant's secret key as the HMAC key.

Headers

Accept-Language

string

Optional. Language of the returned error messages: en (English, default) / zh-CN (Chinese).

Content-Type

string

Optional. application/json; charset=utf-8 by default.

Responses

200

OK

result_coderequired

string

The order result code.

Enum

READYOrder created; not yet submitted to the payment channel

PAYINGSubmitted to the channel and awaiting the result (card payments: under review)

PAIDPayment completed (confirmed by the channel, or reconciled)

CLOSEDOrder closed, e.g. expired without payment

CANCELLEDCancelled by the payment channel (non-card channels only)

FAILEDPayment failed

FailUnknown status — rare fallback value

pay_currency / pay_amount / exchange_rate / order_time / pay_time are only returned when result_code is PAID or CLOSED; otherwise they are null.

out_order_norequired

string

The merchant order number.

currencyrequired

string

The currency code.

amountrequired

any

The order amount in cents.

platformrequired

string

The payment platform identifier.

pay_currencyrequired

string

The actual pay currency code.

pay_amountrequired

any

The actual pay amount in cents.

order_timerequired

string

The order creation time.

pay_timerequired

string

The payment time.

exchange_raterequired

any

The exchange rate (scaled by 100000000).

return_coderequired

string

"SUCCESS" on success, "FAIL" on any error.

successrequired

boolean

Whether the operation was successful.

error_code

string

Specific error code on failure (e.g. SYSTEM_ERROR). Null on success.

error_msg

string

Localized error message on failure. Null on success.

Try it

Merchant Credentials

m_number timestamp nonce_str sign

Parameters

order_noout_order_no

Click "Send Request"

Response

200 · application/json

{
  "result_code": "string",
  "out_order_no": "string",
  "currency": "AUD",
  "amount": 1000,
  "platform": "string",
  "pay_currency": "string",
  "pay_amount": 1000,
  "order_time": "2026-09-03T12:00:00Z",
  "pay_time": "2026-09-03T12:00:00Z",
  "exchange_rate": 1000,
  "return_code": "string",
  "success": true,
  "error_code": "string",
  "error_msg": "string"
}

400 · application/json

{
  "return_code": "FAIL",
  "success": false,
  "error_code": "PARAMETER_INVALID",
  "error_msg": "The amount field is required."
}

401 · application/json

{
  "return_code": "FAIL",
  "success": false,
  "error_code": "SIGNATURE_FAILED",
  "error_msg": "Signature verification failed."
}

500 · application/json

{
  "return_code": "FAIL",
  "success": false,
  "error_code": "SYSTEM_ERROR",
  "error_msg": "Internal server error."
}

GET/omipay/api/v3/refund/query

Query refund

Queries the status and details of a refund by its Omipay refund number or the merchant refund number.

Parameters

refund_no

string

The system refund number.

out_order_no

string

The merchant order number.

out_refund_no

string

The merchant refund number.

m_numberrequired

string

Merchant number issued by Omipay. Identifies the merchant account whose secret key is used to sign the request.

timestamprequired

string

Request time in milliseconds since the Unix epoch, passed as a string. Must be within 60 minutes of the server time (up to 5 minutes of future skew allowed).

nonce_strrequired

string

A unique random string for this request, used for replay protection. Generate a fresh value for every request.

signrequired

string

HMAC-SHA256 signature, uppercase hexadecimal. Computed over the string "m_number&timestamp&nonce_str&secret_key" using the merchant's secret key as the HMAC key.

Headers

Accept-Language

string

Optional. Language of the returned error messages: en (English, default) / zh-CN (Chinese).

Content-Type

string

Optional. application/json; charset=utf-8 by default.

Responses

200

OK

result_coderequired

string

The refund result code.

Enum

PaymentChannelConfirmedRefund accepted and in progress

PaymentChannelSuccessRefund completed successfully

OrganizationFailedRefund failed

ClearedRefund settled (non-card channels only)

success_time is only returned when result_code is PaymentChannelSuccess; otherwise it is null.

out_refund_norequired

string

The merchant refund number.

currencyrequired

string

The currency code.

amountrequired

any

The refund amount in cents.

refund_timerequired

string

The refund time.

success_timerequired

string

The refund success time.

return_coderequired

string

"SUCCESS" on success, "FAIL" on any error.

successrequired

boolean

Whether the operation was successful.

error_code

string

Specific error code on failure (e.g. SYSTEM_ERROR). Null on success.

error_msg

string

Localized error message on failure. Null on success.

Try it

Merchant Credentials

m_number timestamp nonce_str sign

Parameters

refund_noout_order_noout_refund_no

Click "Send Request"

Response

200 · application/json

{
  "result_code": "string",
  "out_refund_no": "R2026090300001",
  "currency": "AUD",
  "amount": 1000,
  "refund_time": "2026-09-03T12:00:00Z",
  "success_time": "2026-09-03T12:00:00Z",
  "return_code": "string",
  "success": true,
  "error_code": "string",
  "error_msg": "string"
}

400 · application/json

{
  "return_code": "FAIL",
  "success": false,
  "error_code": "PARAMETER_INVALID",
  "error_msg": "The amount field is required."
}

401 · application/json

{
  "return_code": "FAIL",
  "success": false,
  "error_code": "SIGNATURE_FAILED",
  "error_msg": "Signature verification failed."
}

500 · application/json

{
  "return_code": "FAIL",
  "success": false,
  "error_code": "SYSTEM_ERROR",
  "error_msg": "Internal server error."
}

POST/omipay/api/v3/token/bind

Bind card token

Initiates a card-token binding. On success the response contains a URL to the hosted card-entry page where the payer's card is securely captured and tokenized for later reuse.

Parameters

currencyrequired

string

The currency code; only AUD is allowed.

out_order_norequired

string

The merchant-side card ID / binding order number (must be unique per merchant).

notify_url

string

The async binding notification callback URL. Sent only for a successful binding — a failed binding is NOT notified. Omit this parameter to receive no asynchronous notification.

redirect_url

string

The redirect URL after successful binding.

m_numberrequired

string

Merchant number issued by Omipay. Identifies the merchant account whose secret key is used to sign the request.

timestamprequired

string

Request time in milliseconds since the Unix epoch, sent as a string (e.g. "1756872000000"). The signature is computed over this literal string. Must be within 60 minutes of the server time (up to 5 minutes of future skew allowed).

nonce_strrequired

string

A unique random string for this request, used for replay protection. Generate a fresh value for every request.

signrequired

string

HMAC-SHA256 signature, uppercase hexadecimal. Computed over the string "m_number&timestamp&nonce_str&secret_key" using the merchant's secret key as the HMAC key.

Headers

Accept-Language

string

Optional. Language of the returned error messages: en (English, default) / zh-CN (Chinese).

Content-Type

string

Optional. application/json; charset=utf-8 by default.

Responses

200

OK

bind_urlrequired

string

The bind card page URL (carries the binding number via the order_no query parameter).

return_coderequired

string

"SUCCESS" on success, "FAIL" on any error.

successrequired

boolean

Whether the operation was successful.

error_code

string

Specific error code on failure (e.g. SYSTEM_ERROR). Null on success.

error_msg

string

Localized error message on failure. Null on success.

Try it

Merchant Credentials

m_number timestamp nonce_str sign

Parameters

currencyout_order_nonotify_urlredirect_url

Click "Send Request"

Response

200 · application/json

{
  "bind_url": "string",
  "return_code": "string",
  "success": true,
  "error_code": "string",
  "error_msg": "string"
}

400 · application/json

{
  "return_code": "FAIL",
  "success": false,
  "error_code": "PARAMETER_INVALID",
  "error_msg": "The amount field is required."
}

401 · application/json

{
  "return_code": "FAIL",
  "success": false,
  "error_code": "SIGNATURE_FAILED",
  "error_msg": "Signature verification failed."
}

500 · application/json

{
  "return_code": "FAIL",
  "success": false,
  "error_code": "SYSTEM_ERROR",
  "error_msg": "Internal server error."
}

POST/omipay/api/v3/order/token

Charge card token

Charges a previously bound card token. On success the response contains the order number and a redirect URL when 3-D Secure verification or asynchronous processing is required.

Parameters

currencyrequired

string

The three-letter currency code (ISO 4217). Currently only AUD is supported.

amountrequired

any

The order amount in cents (smallest currency unit). For AUD, 100 = $1.00. Minimum amount is 50 (i.e. $0.50).

notify_url

string

The asynchronous payment-notification callback URL. Notifications are sent only for successful payments — failed payments are NOT notified (poll order/query instead), and refunds are never notified. Omit this parameter to receive no asynchronous notification.

redirect_url

string

The URL the payer is redirected to after completing payment.

out_order_norequired

string

The merchant order number (must be unique per merchant).

o_numberrequired

string

The branch (store) number.

order_inforequired

string

Product information (required). JSON-format string array; each item has item_name (non-empty string), item_count (> 0) and item_price (> 0, a decimal in MAJOR units — dollars, NOT cents). The sum of item_price × item_count must equal amount ÷ 100 (amount is in cents). Example: [{"item_name":"Product A","item_count":1,"item_price":1.00}] matches amount=100.

delivery_is_required

any

Whether the order requires a shipping address.

shipping_info

string

Shipping information (required when delivery_is_required is true). JSON-format string. Example:

{
  "recipient_name": "Zhang San",
  "recipient_phone": "13800138000",
  "recipient_address": "Address"
}

card_tokenrequired

string

The card token returned by the card-token binding flow.

m_numberrequired

string

Merchant number issued by Omipay. Identifies the merchant account whose secret key is used to sign the request.

timestamprequired

string

Request time in milliseconds since the Unix epoch, sent as a string (e.g. "1756872000000"). The signature is computed over this literal string. Must be within 60 minutes of the server time (up to 5 minutes of future skew allowed).

nonce_strrequired

string

A unique random string for this request, used for replay protection. Generate a fresh value for every request.

signrequired

string

HMAC-SHA256 signature, uppercase hexadecimal. Computed over the string "m_number&timestamp&nonce_str&secret_key" using the merchant's secret key as the HMAC key.

Headers

Accept-Language

string

Optional. Language of the returned error messages: en (English, default) / zh-CN (Chinese).

Content-Type

string

Optional. application/json; charset=utf-8 by default.

Responses

200

OK

order_norequired

string

The Omipay order number.

token_order_urlrequired

string

The 3-D Secure redirect URL (present when verification is required; empty otherwise).

return_coderequired

string

"SUCCESS" on success, "FAIL" on any error.

successrequired

boolean

Whether the operation was successful.

error_code

string

Specific error code on failure (e.g. SYSTEM_ERROR). Null on success.

error_msg

string

Localized error message on failure. Null on success.

Try it

Merchant Credentials

m_number timestamp nonce_str sign

Parameters

currencyamountnotify_urlredirect_urlout_order_noo_numberorder_infodelivery_is_requiredshipping_infocard_token

Click "Send Request"

Response

200 · application/json

{
  "order_no": "TRC260903XXXXXXXXXX",
  "token_order_url": "string",
  "return_code": "string",
  "success": true,
  "error_code": "string",
  "error_msg": "string"
}

400 · application/json

{
  "return_code": "FAIL",
  "success": false,
  "error_code": "PARAMETER_INVALID",
  "error_msg": "The amount field is required."
}

401 · application/json

{
  "return_code": "FAIL",
  "success": false,
  "error_code": "SIGNATURE_FAILED",
  "error_msg": "Signature verification failed."
}

500 · application/json

{
  "return_code": "FAIL",
  "success": false,
  "error_code": "SYSTEM_ERROR",
  "error_msg": "Internal server error."
}

GET/omipay/api/v3/order/tokens

Query card token list

Lists the bound card tokens for the current merchant. Provide a card token to look up a single binding.

Parameters

card_token

string

m_numberrequired

string

Merchant number issued by Omipay. Identifies the merchant account whose secret key is used to sign the request.

timestamprequired

string

Request time in milliseconds since the Unix epoch, passed as a string. Must be within 60 minutes of the server time (up to 5 minutes of future skew allowed).

nonce_strrequired

string

A unique random string for this request, used for replay protection. Generate a fresh value for every request.

signrequired

string

HMAC-SHA256 signature, uppercase hexadecimal. Computed over the string "m_number&timestamp&nonce_str&secret_key" using the merchant's secret key as the HMAC key.

Headers

Accept-Language

string

Optional. Language of the returned error messages: en (English, default) / zh-CN (Chinese).

Content-Type

string

Optional. application/json; charset=utf-8 by default.

Responses

200

OK

tokensrequired

array<TokenInfo>

The list of active card tokens.

card_tokenrequired

string

The card token.

masked_card_no

string

The masked card number (first 6 + ****** + last 4).

card_brand

string

The card brand (e.g. VISA, MASTERCARD).

expiry_month

string

The card expiry month (MM).

expiry_year

string

The card expiry year (YYYY).

card_country

string

The card issuing country.

bind_time

string

The binding time (ISO 8601).

order_no

string

The card-binding order number (order_no from token/bind).

out_order_no

string

The merchant-side binding order number (out_order_no from token/bind).

return_coderequired

string

"SUCCESS" on success, "FAIL" on any error.

successrequired

boolean

Whether the operation was successful.

error_code

string

Specific error code on failure (e.g. SYSTEM_ERROR). Null on success.

error_msg

string

Localized error message on failure. Null on success.

Try it

Merchant Credentials

m_number timestamp nonce_str sign

Parameters

card_token

Click "Send Request"

Response

200 · application/json

{
  "tokens": [
    {
      "card_token": "string",
      "masked_card_no": "string",
      "card_brand": "string",
      "expiry_month": "string",
      "expiry_year": "string",
      "card_country": "string",
      "bind_time": "string"
    }
  ],
  "order_no": "TRC260903XXXXXXXXXX",
  "out_order_no": "string",
  "return_code": "string",
  "success": true,
  "error_code": "string",
  "error_msg": "string"
}

400 · application/json

{
  "return_code": "FAIL",
  "success": false,
  "error_code": "PARAMETER_INVALID",
  "error_msg": "The amount field is required."
}

401 · application/json

{
  "return_code": "FAIL",
  "success": false,
  "error_code": "SIGNATURE_FAILED",
  "error_msg": "Signature verification failed."
}

500 · application/json

{
  "return_code": "FAIL",
  "success": false,
  "error_code": "SYSTEM_ERROR",
  "error_msg": "Internal server error."
}

POST/omipay/api/v3/token/unbind

Unbind card token

Unbinds (deletes) a previously bound card token so it can no longer be used for charges.

Parameters

card_tokenrequired

string

The card token to unbind.

unbind_reason

string

Optional unbind reason.

m_numberrequired

string

Merchant number issued by Omipay. Identifies the merchant account whose secret key is used to sign the request.

timestamprequired

string

Request time in milliseconds since the Unix epoch, sent as a string (e.g. "1756872000000"). The signature is computed over this literal string. Must be within 60 minutes of the server time (up to 5 minutes of future skew allowed).

nonce_strrequired

string

A unique random string for this request, used for replay protection. Generate a fresh value for every request.

signrequired

string

HMAC-SHA256 signature, uppercase hexadecimal. Computed over the string "m_number&timestamp&nonce_str&secret_key" using the merchant's secret key as the HMAC key.

Headers

Accept-Language

string

Optional. Language of the returned error messages: en (English, default) / zh-CN (Chinese).

Content-Type

string

Optional. application/json; charset=utf-8 by default.

Responses

200

OK

return_coderequired

string

"SUCCESS" on success, "FAIL" on any error.

successrequired

boolean

Whether the operation was successful.

error_code

string

Specific error code on failure (e.g. SYSTEM_ERROR). Null on success.

error_msg

string

Localized error message on failure. Null on success.

Try it

Merchant Credentials

m_number timestamp nonce_str sign

Parameters

card_tokenunbind_reason

Click "Send Request"

Response

200 · application/json

{
  "return_code": "string",
  "success": true,
  "error_code": "string",
  "error_msg": "string"
}

400 · application/json

{
  "return_code": "FAIL",
  "success": false,
  "error_code": "PARAMETER_INVALID",
  "error_msg": "The amount field is required."
}

401 · application/json

{
  "return_code": "FAIL",
  "success": false,
  "error_code": "SIGNATURE_FAILED",
  "error_msg": "Signature verification failed."
}

500 · application/json

{
  "return_code": "FAIL",
  "success": false,
  "error_code": "SYSTEM_ERROR",
  "error_msg": "Internal server error."
}

GET/omipay/api/v3/rate

Get exchange rate

Returns the exchange rate between a base currency and a target currency for a given payment platform.

Parameters

platform

string

WECHATPAYWeChat Pay

ALIPAYAlipay

Default: WECHATPAY

base_currencyrequired

string

The base currency code (e.g. CNY).

currencyrequired

string

The currency code (e.g. AUD).

m_numberrequired

string

Merchant number issued by Omipay. Identifies the merchant account whose secret key is used to sign the request.

timestamprequired

string

Request time in milliseconds since the Unix epoch, sent as a string (e.g. "1756872000000"). The signature is computed over this literal string. Must be within 60 minutes of the server time (up to 5 minutes of future skew allowed).

nonce_strrequired

string

A unique random string for this request, used for replay protection. Generate a fresh value for every request.

signrequired

string

HMAC-SHA256 signature, uppercase hexadecimal. Computed over the string "m_number&timestamp&nonce_str&secret_key" using the merchant's secret key as the HMAC key.

Headers

Accept-Language

string

Optional. Language of the returned error messages: en (English, default) / zh-CN (Chinese).

Content-Type

string

Optional. application/json; charset=utf-8 by default.

Responses

200

OK

raterequired

any

The exchange rate.

platformrequired

string

The payment platform identifier.

return_coderequired

string

"SUCCESS" on success, "FAIL" on any error.

successrequired

boolean

Whether the operation was successful.

error_code

string

Specific error code on failure (e.g. SYSTEM_ERROR). Null on success.

error_msg

string

Localized error message on failure. Null on success.

Try it

Merchant Credentials

m_number timestamp nonce_str sign

Parameters

platformbase_currencycurrency

Click "Send Request"

Response

200 · application/json

{
  "rate": "string",
  "platform": "string",
  "return_code": "string",
  "success": true,
  "error_code": "string",
  "error_msg": "string"
}

400 · application/json

{
  "return_code": "FAIL",
  "success": false,
  "error_code": "PARAMETER_INVALID",
  "error_msg": "The amount field is required."
}

401 · application/json

{
  "return_code": "FAIL",
  "success": false,
  "error_code": "SIGNATURE_FAILED",
  "error_msg": "Signature verification failed."
}

500 · application/json

{
  "return_code": "FAIL",
  "success": false,
  "error_code": "SYSTEM_ERROR",
  "error_msg": "Internal server error."
}

WebhookPOST {your notify_url}

Payment Result Notification

This is not an endpoint you call — it is a receiver you implement. When a payment, card binding, or refund reaches its final state, Omipay POSTs a JSON notification to the notify_url you provided when creating the order.

How it works

URL

Your notify_url, must be a publicly reachable HTTPS URL.

Verify

You must verify the signature before processing: sign = UpperHex(HMAC-SHA256(key = secret_key, message = m_number&timestamp&nonce_str&secret_key)). m_number is your merchant number — it is NOT part of the notification body.

Respond

Respond HTTP 200 on success (recommended body: success or {"success":true}). Any non-200 response or timeout is treated as a failure.

Retries

On failure, Omipay retries on a 15s / 30s / 1m / 5m / 30m / 1h / 2h schedule, up to 8 attempts. After retries are exhausted you can recover the final state via order/query or refund/query.

Idempotency

The same order may produce multiple notifications; handle them idempotently.

Notification Body Fields

return_code

string

The notification status. SUCCESS indicates the notification was delivered successfully.

nonce_str

string

Random string for signature verification; unique per notification.

timestamp

string

The notification timestamp (Unix milliseconds as a string), used for signature verification.

sign

string

HMAC-SHA256 signature (64-char uppercase hex). See the verification algorithm above.

order_no

string

The Omipay order number / card binding number / refund number.

out_order_no

string

The merchant order number (the out_order_no / out_refund_no submitted with the original request).

total_amount

integer

The total order amount in cents (0 for card binding notifications).

currency

string

The currency code (e.g. AUD).

order_time

string

The order creation time, yyyy-MM-dd HH:mm:ss (merchant timezone).

pay_time

string

The payment / binding / refund completion time, yyyy-MM-dd HH:mm:ss (merchant timezone); null when not completed.

Notification Example

POST · application/json

{
  "return_code": "SUCCESS",
  "nonce_str": "9d4a1c7e8f2b4c0a8e6d1f3a5b7c9d0e",
  "timestamp": "1756872000000",
  "sign": "5F1A3B…64-char-uppercase-hex",
  "order_no": "TRC260903XXXXXXXXXX",
  "out_order_no": "2026090300001",
  "total_amount": 1000,
  "currency": "AUD",
  "order_time": "2026-09-03 12:00:00",
  "pay_time": "2026-09-03 12:00:05"
}

WebhookPOST {your bind notify_url}

Bind Card Result Notification

This is not an endpoint you call — it is a receiver you implement. When a card binding (token/bind) reaches its final state, Omipay POSTs a JSON notification to the notify_url you provided in the bind request.

How it works

URL

Your notify_url, must be a publicly reachable HTTPS URL.

Verify

You must verify the signature before processing: sign = UpperHex(HMAC-SHA256(key = secret_key, message = m_number&timestamp&nonce_str&secret_key)). m_number is your merchant number — it is NOT part of the notification body.

Respond

Respond HTTP 200 on success (recommended body: success or {"success":true}). Any non-200 response or timeout is treated as a failure.

Retries

On failure, Omipay retries on a 15s / 30s / 1m / 5m / 30m / 1h / 2h schedule, up to 8 attempts. After retries are exhausted you can recover the final state via order/query or refund/query.

Idempotency

The same order may produce multiple notifications; handle them idempotently.

Notification Body Fields

return_code

string

The notification status. SUCCESS indicates the binding succeeded.

nonce_str

string

Random string for signature verification; unique per notification.

timestamp

string

The notification timestamp (Unix milliseconds as a string), used for signature verification.

sign

string

HMAC-SHA256 signature (64-char uppercase hex). See the verification algorithm above.

order_no

string

The Omipay card-binding number (TRCB...).

out_order_no

string

The merchant binding order number (the out_order_no submitted with token/bind).

currency

string

The currency code (currently always AUD for bindings).

bind_time

string

The binding completion time, yyyy-MM-dd HH:mm:ss (Sydney time).

card_token

string

The card token to use for subsequent token charges (POST /omipay/api/v3/order/token).

masked_card_no

string

The masked card number (first 6 + ****** + last 4).

card_brand

string

The card brand (e.g. VISA, MASTERCARD).

expiry_month

string

The card expiry month (MM).

expiry_year

string

The card expiry year (YYYY).

card_country

string

The card issuing country (ISO code).

card_holder_name

string

The cardholder name.

Notification Example

POST · application/json

{
  "return_code": "SUCCESS",
  "nonce_str": "7b3e9f1a2c4d6e8f0a1b2c3d4e5f6a7b",
  "timestamp": "1756872000000",
  "sign": "9C2E4B…64-char-uppercase-hex",
  "order_no": "TRCB260903XXXXXXXXXX",
  "out_order_no": "2026090300002",
  "currency": "AUD",
  "bind_time": "2026-09-03 12:00:05",
  "card_token": "ctok_9f8e7d6c5b4a3210",
  "masked_card_no": "424242******4242",
  "card_brand": "VISA",
  "expiry_month": "12",
  "expiry_year": "2030",
  "card_country": "AU",
  "card_holder_name": "ZHANG SAN"
}