Getting Started

Environment Setup

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

Test	https://p-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
Place order via Payment API	Merchant -> Checus	/orderAndPay
Async notification to merchant	Checus -> Merchant	/collectResultNotifyUrl
Query transaction result	Merchant -> Checus	/orderQuery

Integration Steps

1. Create a payment session

Call orderAndPay API to create a payment (POST).

In hosted checkout you can choose:

• No specific payment method: display all available payment methods.
• Specified payment method: display only the method indicated in the request.

Common Parameter Description

Regardless of the payment method your users choose, the following basic fields must be included in the request:

• outTradeNo: Merchant system order number (unique)
• totalAmount: Amount
• currency: Currency
• country: User's country
• userId: User identifier
• frontCallbackUrl: URL to redirect the user after payment completion
• notifyUrl: Callback URL for payment result notifications (can also be configured in the Merchant Management Platform)
• integrate: Fixed value to Hosted_Checkout
• expireTime: Order closure time in seconds. Default range: 1800–86400; values outside this range will be automatically adjusted

Specific Payment Method Selection

Goal	Description	Illustration	Configuration
Display all payment methods	Show all available payment methods		Do not pass the paymentDetail field
Limit by payment type without specifying provider	For example, restrict to online banking; the checkout will display T-Pay, SberPay, etc.		Set paymentDetail.paymentMethodType, e.g., "NET_BANKING"
Limit to specific payment provider	For example, only show SberPay		Set paymentDetail.targetOrg, e.g. "SBERBANK"
Limit to card payments	For example, display all card payments only		Set paymentDetail.paymentMethodType = "CARD"

2. Redirect to Checus checkout

After a successful orderAndPay API call, redirect the customer to the returned redirectUrl to complete payment.

3. Redirect to the Payment Result Page

After the user completes the payment, Checus will display a result page. When the user clicks Return or Close button, they will be redirected to the frontCallbackUrl you specified in the request. Please ensure that this URL is accessible from external browsers.

Redirect Logic Comparison (frontCallbackUrl)

Redirect form	Flow	Recommendation	Pros	Cons
In-page H5 to App	Detects and launches app after page load (via URL Scheme / App Link)	Recommended	Controllable and flexible	Complex, multi-scenario support needed
App Link / Universal Link (http/https)	System auto-opens app, fallback to web if failed	Recommended	Supports fallback, better user experience	Requires app configuration
Standard H5 (http/https)	Stays on browser page	Not recommended	Simple implementation	Cannot open app, poor UX
URL Scheme (scheme://)	Tries to open app, blank if failed	Not recommended	Simple implementation	No fallback, blank screen risk

Checus Appended Parameters

When redirecting to frontCallbackUrl, Checus will automatically append the following parameters:

• outTradeNo: Merchant order ID
• tradeToken: Checus order ID
• status: current order status (for display only, not for updating order state)

Do not rely on status parameter to update the merchant order. Always use Payment Result Notification or Query API to ensure accurate transaction results.

4. Retrieve Payment Result

Method 1. Payment Result Notification

After the payment is completed, Checus will send a Payment Result Notification to collectResultNotifyUrl API endpoint.

The notification may be retried multiple times until a successful response is returned.

Configure webhook URL via:

• Via API request: Provide the notifyUrl parameter in the /orderAndPay request. Applies to this order only.
• Via Merchant Plantform: Configure a global callback URL in the Plateform. Applies to all orders.

You must return a success response once the notification is processed.

If no response or a failure is returned, Checus will retry according to the following schedule: 0s / 30s / 300s / 600s / 3600s / 43200s (up to 6 attempts).

Method 2. Active Query

If no notification is received, or the order status remains unclear, you may actively call the Order Query /orderQuery to retrieve the payment result.

You should use the code field to determine whether the query request itself was successful, and use data.status to determine the payment status.

Do not rely on code, msg, or data.resultMsg to determine payment status.

Refer to the Error Code List for troubleshooting in case of errors.

Payment Status Codes List

Status	Description
SUCCESS	Payment succeeded
PENDING	Waiting for payment
FAILED	Payment failed
CLOSED	Timed out, order closed