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
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

Please refer to the Payment Result Integration.