Getting Started

Environment Setup

Before you begin, make sure you have completed the Set Up Test Environment step.

Test	https://pay-gate-uat.checus.com/aggregate-pay/api/gateway/<PATH>
Production	https://pay-gate-hk-prod.checus.com/aggregate-pay/api/gateway/<PATH>

Interaction Flow

Key APIs

Interaction	Direction	API / Method
Create payout request	Merchant → Checus	/paymentOrderPay
Payout result webhook	Checus → Merchant	/disbursementResultNotifyUrl
Query payout	Merchant → Checus	/paymentOrderQry

Integration Steps

Before you start

• Download the payout application template and collect the user's payout details in your app or website.
• Construct request parameters according to the “Filling Rules” table in the Payout Application Template (fields with pink background are required).
• Payout requests are irreversible once submitted.

1. Create a payout session

Call Apply for Payout/paymentOrderPay API with POST to create a payout.

Each order you submit must pass idempotency checks. Include a unique orderId in the request.

If Checus detects a duplicate orderId, it returns code=ORDER_REPEAT together with the current order status.

2. Obtain payout results

Method 1. Result notification

After processing, Checus calls your Payout Result Notification/disbursementResultNotifyUrl API. It may retry multiple times until you return a successful response.

Callbacks usually occur when the transaction reaches a terminal state (e.g., Success, Failed, Bounceback); if the Processing state requires merchant/user awareness, a prior notification may be sent.

How to configure the callback URL:

• Pass via API: provide notifyUrl in /paymentOrderPay, effective for the current order only;
• Platform setting: configure a global callback URL in the Merchant Portal, applied to all orders.

Upon receiving the notification, you should return a processing result. If there is no response or a failure is returned, Checus retries at the following intervals: 0s / 30s / 300s / 600s / 3600s / 43200s, up to 6 retries.

Method 2. Proactively query the result

If no notification is received or the order status is unclear, call Payout Query/paymentOrderQry API to obtain the result.

Use the response code to judge whether the query itself succeeded, and use data.status to determine the payout status.

Payout status list

2.1 Main status enum

Status	Description	Guidance
SUCCESS	Payout succeeded	-
PENDING	Payout processing	1. After submission the order enters PENDING until a terminal state (SUCCESS / FAILED / BOUNCEBACK). 2. Multiple situations may occur under PENDING; see sub-status section.
FAILED	Payout failed	Refer to Error Codes for causes
BOUNCEBACK	Funds returned	In some countries, financial systems may return funds after initially returning success due to reasons such as: – Invalid/frozen beneficiary account – Bank or clearing network issues The order status changes from SUCCESS to BOUNCEBACK, and funds are returned to the merchant account.

2.2 Sub-status (for PENDING)

Main Status	Sub-status	Description	Merchant guidance
PENDING	PEND_RFI_MATERIAL	Materials required	Financial system triggered review; submit supplementary materials. Check email/portal notifications and upload required files.
PENDING	REVIEW	Under review	Materials submitted; Checus reviewing, feedback expected in 0–3 business days. No action needed.
PENDING	TRANSMIT	Processing	Transaction in progress; wait for the final result.

---

Error Codes

• Error codes are grouped by scenario:

  Category	Description
  Server request limits	Returned when frequency/IP rules trigger protection
  Merchant configuration	Signature keys, contract activation, and other onboarding checks
  Order submission	Parameter format, duplicate orders, system errors during submission
  Order validation	Amount limits, beneficiary info checks, risk control restrictions
  Order query	Errors related to the query API

• Error examples Synchronous response example (e.g., error when creating payout):

  {
    "msg": "Invalid account or not active",
    "code": "INVALID_ACCOUNT"
  }

  Asynchronous callback example (e.g., transaction failed):

  {
    "appId": "4701b0a908a14312b3c8452b448256dw",
    "code": "APPLY_SUCCESS",
    "data": {
      "transactionUtcTime": "2024-08-29T12:50:38 +0000",
      "status": "FAILD",
      "responseCode": "INVALID_ACCOUNT",
      "responseMsg": "Invalid account or not active"
      // other fields omitted
    },
    "msg": "Success.",
    "notifyType": "PAYOUT"
  }

• Server request limit error codes

  Code	Description	Notes
  REQ_TIME_OVER_TIME	requestTime effective in two minutes	Request time differs from server by >2m
  ILLEGAL_IP_REQUEST	illegal ip request	Request IP not in allowlist; contact Checus
  TOO_MANY_REQUEST	Exceed request limitation, please retry later	Rate limited; retry later

• Merchant configuration error codes

  Subcategory	Code	Description	Notes
  Signature/keys	MERCHANT_APP_INVALID	Signature key is not configured.	Key not configured
  Signature/keys	SIGN_VERIFY_FAILED	The signature verify failed.	Signature failed
  Contract/merchant	CONTRACT_INVALID	Merchant has not signed the contract or payment methods.	Not contracted or methods not enabled
  Contract/merchant	MERCHANT_INVALID	The merchant has been offline.	Merchant status issue

• Order submission error codes

  Subcategory	Code	Description	Notes
  Request validation	PARAMS_INVALID	The {field} is incorrect.	Field format invalid
  Request validation	ORDER_REPEAT	The order number repeat.	Duplicate order
  System error	SYSTEM_ERROR	System is busy, Please try again later.	Try again later

• Order validation error codes

  Subcategory	Code	Description	Notes
  Payment method and amount limits	PAYMENT_METHOD_NOT_AVAILABLE	The payment method is not available.	Payment method unavailable
  		AMOUNT_LIMIT_UNMATCHED	The amount does not meet the limit requirements	Amount does not meet limits
  		AMOUNT_NOT_ENOUGH	Insufficient balance	Insufficient balance
  Beneficiary account/info validation	INVALID_ACCOUNT	Invalid account or not active	Invalid or inactive beneficiary
  		ACCOUNT_BLOCKED	Account blocked or frozen	Account frozen
  		INVALID_EMAIL	Email address is incorrect.	Invalid email format
  		MISMATCHED_NAME	Payee name does not match the account	Name/account mismatch
  Sub-merchant info issues	SUBMERCHANT_NOT_REGISTERED	The subMerchantNo is not registered	Sub-merchant not filed or incorrect
  		SUBMERCHANT_REGISTRATION_FAILED	The subMerchantNo registration failed	Sub-merchant registration failed
  Risk control and others	RFI_BLACKLIST	Rejected due to failure of beneficiary to submit request information	Compliance materials not submitted
  		DECLINED_BY_RISK	Beneficiary bank rejected credit	Declined by risk control
  		PAYMENT_FAILED	Payment failed	Payment failed

• Order query error codes

  Code	Description	Notes
  ORDER_NOT_EXIST	The order does not exist.	Order does not exist or is processing