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 Interfaces

Interaction Sequence Diagram/Related Interaction Timing	Call Direction/Direction of Call	Interface Address/API Endpoint
Call Payment API to place an order	Merchant -> Checus	/orderAndPay
Asynchronously notify the merchant of the result	Checus -> Merchant	/collectResultNotifyUrl
Query transaction result	Merchant -> Checus	/orderQuery

Integration Steps

1. Register a developer center account and enable the payment method.
2. Configure the payment result notification callback (notifyUrl).
3. Obtain merchant public key, platform public key, AppID, and other information.
4. Set up the IP whitelist for the test environment.
5. Understand the signature mechanism (signing and verification).
6. Initiate the first payment using the Payment Creation Interface/ orderAndPay API
7. Receive the asynchronous notification or call the Transaction Query/orderQuery API to check the payment result.
8. Record the returned PaymentTokenID for subsequent payments.

Core Process

Create Payment

• Interface: Payment Creation Interface/orderAndPay API
• Payment Method: The first payment uses the specified CARD payment method; subsequent payments can use the PaymentTokenID

General Parameter Description

When using Token Payment, the following basic fields should be included in the Payment Creation Interface/orderAndPay APIrequest:

• outTradeNo: Merchant system order number (unique)
• totalAmount: Amount
• currency: Currency type
• country: User's country
• userId: User identifier
• frontCallbackUrl: Redirect address after payment completion
• notifyUrl: Payment result notification callback (can be configured uniformly in the merchant management platform)
• integrate: Fixed as Hosted_Checkout
• expireTime: Order closing time, in seconds. Default range: 1800~86400，values outside this range will be forcibly corrected.
• paymentMethodType: Payment method type, fixed as "CARD"
• allowedCardOrg: Optional, allowed card brands, such as [ "VISA", "MASTERCARD" ]，Empty means all cards are allowed.
• tokenForFutureUse: Optional, whether to enable Token Payment (Required for Token Payment, and the value must be "true")
• paymentTokenID: Payment Token, only returned after the first payment, used for subsequent payments

Response

• tradeToken: Checus transaction number
• redirectUrl: Returns the Cashier URL; the user needs to enter bank card information on the Checus cashier page.
• status: Order status (PENDING / SUCCESS)
• Flow without 3DS Verification (When the user passes paymentTokenID for subsequent payments):
  • The system directly returns status=SUCCESS, along with tradeToken and outTradeNo。
  • redirectUrlwill not be returned.
  • The merchant can assume the payment is successful, but still needs to confirm via notification or query.
• Flow requiring 3DS Verification (When the user makes the first payment with tokenForFutureUse as true OR passes paymentTokenID for subsequent payments):
  • The system returns status=PENDING and redirectUrl.
  • The merchant redirects the user to the Checus Cashier page.
  • After the user completes verification, Checus updates the order status to success.
  • The merchant confirms the final result via callback or query.

Key Tips:

• Do not rely solely on the status returned by the Payment Creation Interface / orderAndPay API to update your local order.
• For Cashier Payment Integration, tradeToken, outTradeNo and redirectUrl are always returned.

Get Payment Result

Please refer to Payment Result Integration.

Pay Using PaymentTokenID

• Subsequent payments do not require card information; direct deduction can be completed by simply passing userId + PaymentTokenID in the Payment Creation Interface /orderAndPay API.

PaymentTokenID Query

Merchants can use the PaymentTokenID Query/inquirePaymentToken API interface to query all PaymentTokenIDs bound to a specific user.

Call Direction: Merchant → Checus

Interface Address: /inquirePaymentToken

Key Request Fields:

• userId: User identifier
• tokenScope: Fixed value "tokenAcq"
• paymentMethodType: Payment method type (Optional)
• cardOrg: Card brand (Optional when paymentMethodType is CARD)
• paymentTokenID: Specify a particular Token to query (Optional)

PaymentTokenID Unbinding

When a user wishes to remove a bound Token, the merchant can use the paymentTokenID Unbinding/removePaymentToken API interface to delete the Token. Once unbound, the Token can no longer be used for payment.

Call Direction: Merchant → Checus

Interface Address: /removePaymentToken

Key Request Fields:

• userId: User identifier
• paymentTokenID: The Token to be unbound
• removeReason: Reason for unbinding

Interaction Flow

Key Interfaces

Interaction Sequence Diagram/Related Interaction Timing	Call Direction/Direction of Call	Interface Address/API Endpoint
Call Payment API to place an order	Merchant -> Checus	/orderAndPay
Asynchronously notify the merchant of the result	Checus -> Merchant	/collectResultNotifyUrl
Query transaction result	Merchant -> Checus	/orderQuery

Integration Steps

1. Register a developer center account and enable the payment method.
2. Configure the payment result notification callback (notifyUrl).
3. Obtain merchant public key, platform public key, AppID, and other information.
4. Set up the IP whitelist for the test environment.
5. Understand the signature mechanism (signing and verification).
6. Initiate the first payment using the Payment Creation Interface/ orderAndPay API
7. Receive the asynchronous notification or call the Transaction Query/orderQuery API to check the payment result.
8. Record the returned PaymentTokenID for subsequent payments.

Core Process

Create Payment

• Interface:Payment Creation Interface/orderAndPay API
• Payment Method:
  • First Payment: Use the specified CARD payment method to complete the payment; the system returns the PaymentTokenID。
  • Subsequent Payment: Use the PaymentTokenIDto complete the deduction, without re-entering card information.

General Parameter Description

When using Token Payment, the following basic fields should be included in the Payment Creation Interface/orderAndPay APIrequest:

• outTradeNo: Merchant system order number (unique)
• totalAmount: Amount
• currency: Currency type
• country: User's country
• userId: User identifier
• frontCallbackUrl: Redirect address after payment completion
• notifyUrl: Payment result notification callback (can be configured uniformly in the merchant management platform)
• integrate: Fixed as Direct_Payment
• expireTime: Order closing time, in seconds. Default range: 1800~86400; values outside this range will be forcibly corrected.
• paymentMethodType: Payment method type, fixed as "CARD"
• allowedCardOrg: Optional, allowed card brands, such as [ "VISA", "MASTERCARD" ], Empty means all cards are allowed.
• tokenForFutureUse: Optional, whether to enable Token Payment (Required for Token Payment, and the value must be "true")
• paymentTokenID: Payment Token, only returned after the first payment, used for subsequent payments

Response Parameters

• tradeToken: Checus transaction number
• redirectUrl: Returns the 3DS URL if 3DS verification is required
• status: Order status (PENDING / SUCCESS)
• Flow without 3DS Verification:
  • The system directly returns status=SUCCESS, along with tradeToken and outTradeNo。
  • redirectUrl will not be returned.
  • The merchant can consider the payment successful, but still needs to confirm via notification or query.
• Flow requiring 3DS Verification:
  • The system returns status=PENDING and redirectUrl.
  • The merchant redirects the user to the 3DS verification page.
  • After the user completes verification, Checus updates the order status to success.
  • The merchant confirms the final result via callback or query.

Key Tips:

• Do not rely solely on the status returned by the Payment Creation Interface /orderAndPayAPI to update your local order.
• Both tradeToken and outTradeNo are always returned, regardless of whether the 3DS is required or not.

Get Payment Result

Please refer to Payment Result Integration.。

PaymentTokenID Query

Merchants can use the PaymentTokenID Query/inquirePaymentToken API nterface to query all PaymentTokenIDs bound to a specific user.

Call Direction: Merchant → Checus

Interface Address: /inquirePaymentToken

Key Request Fields:

• userId: User identifier
• tokenScope: Fixed value "tokenAcq"
• paymentMethodType: Payment method type (Optional)
• cardOrg: Card brand (Optional when paymentMethodType is CARD)
• paymentTokenID: Specify a particular Token to query (Optional)

PaymentTokenID Unbinding

When a user wishes to remove a bound Token, the merchant can use the PaymentTokenID Unbinding/removePaymentToken API interface to delete the Token. Once unbound, the Token can no longer be used for payment.

Call Direction: Merchant → Checus

Interface Address: /removePaymentToken

Key Request Fields:

• userId:User identifier
• paymentTokenID:The Token to be unbound
• removeReason:Reason for unbinding

Interaction Flow

Key APIs

Interaction	Direction	Interface Type	API / Method
1.3 Get Drop-in Component Initialization Data	Merchant -> Checus	Backend API	/applyDropinSession
1.6 Create and Mount Checus component	Merchant Client -> Checus Drop-in JS SDK	Frontend API	PMdropin.create
1.6 Create and Mount Checus component	Merchant Client -> Checus Drop-in JS SDK	Frontend API	PMdropin.mount
1.6 Create and Mount Checus component	Merchant Client -> Checus Drop-in JS SDK	Frontend API	PMdropin.on
2.2 Get Payment Token	Merchant Client -> Checus Drop-in JS SDK	Frontend API	PMdropin.emit
3.4 Create Payment via Drop-in Component	Merchant -> Checus	Backend API	/orderAndPay
4.1 Payment Result Notification	Checus -> Merchant	Backend API	/collectResultNotifyUrl
5.1 Query Payment Transaction	Merchant -> Checus	Backend API	/orderQuery

Card Payment Integration Steps

1. Create Payment Session

Call the Drop-in Component Initialization API to initiate a POST request to create payment.

Retrieve clientKey and sessionKeyfrom the response. These are required to initialize the frontend component.

{
    'Content-Type': 'application/json;charset=utf-8',
    'Accept': 'application/json',
    'sign': <Refer to: https://docs-v2.checus.com/en/doc-center/developer/config-settings.html>
};

request.body =
    {
        "version": "1.1",
        "keyVersion": "1",
        "requestTime": <replace>,
        "merchantNo": <replace>,
        "appId": <replace>,
        "data": {
            "country": "ID",
            "currency": "IDR",
            "totalAmount":"50",
            "userId": "20251025_0834",
            "tokenForFutureUse": true, 
            "componentList":["APPLEPAY","CARD"]
        }
    }

response={
  "msg": "",
  "code": "APPLY_SUCCESS",
  "data": {
    "sessionKey": "bf2c47b085e24c299e45dd56fd751a70",
    "clientKey": "bbd8d2639a7c4dfd8df7d005294390df"
    }
}

2. Render Component

Download the Demo example replace the clientKey and sessionKey , and open locally to see the result.

• Import JS component.

  <script src="https://dropin.checus.com/dropin/js/pmdropin.min.js"></script>

• Add mount container.

  <div class="frame-card">
    <!-- form will be added here -->
  </div>

• Initialize the component.

  // 初始化卡组件
  const card = PMdropin.create('card', {
    clientKey: "client public key", // Obtained from data.clientKey in Step 1
    sessionKey: "session token", // Obtained from data.sessionKey in Step 1
    sandbox: false, // Default is false, i.e., production environment
    hideSaveCard: false, //Whether to hide the "save card" option; default is false (shown)
    hideCardBrands: false, //Whether to hide card brand logos; default is false (shown)
  });
  // Mount the instance
  card.mount('.frame-card'); // Mounts to the first matching DOM element
  // Component ready event
  card.on('ready', () => {
      // Remove custom loading indicator
  })

• (Optional) Listen for form status changes

Real-time callbacks will be triggered when the status changes, which can be used to determine whether the payment button is enabled.

card.on('form-check', (res) => {
  // res.isFormValid indicates the form validation status: false/true
  // true form validation passed, payment can be attempted；false: validation failed, payment button should remain disabled
  console.log('[dropin][form-check]:', res)
})

• Checking the token payment agreement.

If the Token Payment agreement is not checked, the process will proceed to a standard payment flow, and the PaymentTokenID will not be returned to the merchant after payment completion. The PaymentTokenID will only be returned to the merchant after payment completion if the user checks the Token agreement.

• Retrieve the payment token and submit the payment.

Before calling the payment API, check if the payment is allowed. If allowed, use the obtained paymentToken to initiate the payment request.

  card.emit('setDisabled', true) // Disable form after clicking Pay button to prevent duplicate submissions
  card.emit('canMakePayment')
    .then(res => {
      if (res.code === 'APPLY_SUCCESS') {
        const paymentToken = res.data.paymentToken // Payment token to be used in the payment API
        // Call payment API
        // Merchant requests backend API to create order 
        // Construct request parameters with paymentToken
          _postapi('orderAndPay',params).then(res =>{
            const code = (res || {}).code
            //Return payment result to frontend
            if (code == 'APPLY_SUCCESS') {     
              //Payment successful, display result
            } else {
              //Payment failed, display result
            }
      }
        card.emit('setDisabled', false) // Re-enable form after payment API completes
      }
    })
    .catch(err => {
      card.emit('setDisabled', false) // Re-enable form on error
    })

3. Backend Order Creation

Trigger

After canMakePayment returns APPLY_SUCCESS, obtain the paymentTokenand call the /orderAndPay API from the merchant backend to create the order.

Request Flow

• The merchant frontend transmits the paymentToken to the merchant backend; the first payment invokes the Frontend Component for payment, and subsequent payments can use the PaymentTokenID.
• The merchant server generates a unique outTradeNo and initiates a payment request to Checus.

Response

• tradeToken: Checus transaction number
• redirectUrl: Returns the Cashier URL if 3DS verification is required
• status: Order status (PENDING / SUCCESS)
• Flow without 3DS Verification:
  • After creating the payment, the system directly returns the transaction status as "Success," along with the tradeToken and the merchant order number (outTradeNo).
  • redirectUrl will not be returned.
  • The merchant can confirm the payment completion based on the returned status, without the need for additional redirection or verification.
• Flow requiring 3DS Verification:
  • After creating the payment, the system returns the transaction status as "Pending" and provides a Checus Cashier URL.
  • Please redirect the user to this page to complete 3DS verification.
  • After the user completes verification, the payment status will be updated. The merchant can confirm the final status via the payment result notification or order query.

Key Tips:

• Do not rely solely on the status returned by the Payment Creation Interface/orderAndPayAPI to update your local order.
• Both tradeToken and outTradeNo are always returned, regardless of whether the 3DS is required or not.

For detailed request fields, please refer to the Drop-in Component payment API.

  {
    'Content-Type': 'application/json;charset=utf-8',
    'Accept': 'application/json',
    'sign': <XXX>
  };

  {
    "appId": <replace>,
        "version": "1.4",
        "merchantNo": <replace>,
        "requestTime": "2024-06-05T10:46:01.694+08:00",
        "keyVersion": "1",
        "data": {
                "totalAmount": 77.44,
                "country": "HK",
                "expireTime": "7200",
                "paymentDetail": {
                        "paymentMethodType": "CARD",
                        "paymentToken": "332e4cc1af1740aeafe9e7df82aeb5a1",
                        "buyerInfo": {
                                "clientIp": "59.82.59.92",
                                "userAgent": "Chrome"
                        },
                        "sessionKey": "86409e2c04b44536a484caa5ce3ce0e9"
                },
                "frontCallbackUrl": <replace>,
                "subject": "GoGeal PTE. LTD.",
                "outTradeNo": <Merchant Order Number (must be unique)>,
                "notifyUrl": <replace>,
                "currency": "HKD",
                "userId": "3ff0495692d152be96d84dbc9352dc57",
                "integrate": "Direct_Payment",
                "terminalType": "WEB"
        }
  }

4. Get Payment Result

Please refer to Payment Result Integration.。

5. Pay Using PaymentTokenID

• Subsequent payments do not require card information; direct deduction can be completed by simply passing userId + PaymentTokenID in the Payment Creation Interface/orderAndPay API

6. PaymentTokenID Query

Merchants can use thepaymentTokenID Query /inquirePaymentToken API interface to query all PaymentTokenIDs bound to a specific user.

Call Direction: Merchant → Checus

Interface Address: /inquirePaymentToken

Key Request Fields:

• userId: User identifier
• tokenScope: Fixed value "tokenAcq"
• paymentMethodType: Payment method type (Optional)
• cardOrg: Card brand (Optional when paymentMethodType is CARD)
• paymentTokenID: Specify a particular Token to query (Optional)

7. PaymentTokenID Unbinding

When a user wishes to remove a bound Token, the merchant can use the paymentTokenID Unbinding/removePaymentToken API interface to delete the Token. Once unbound, the Token can no longer be used for payment.

Call Direction: Merchant → Checus

Interface Address: /removePaymentToken

Key Request Fields:

• userId: User identifier
• paymentTokenID: The Token to be unbound
• removeReason: Reason for unbinding

Card Frontend API

Usage Guide

The Drop-in Component provides standard API methods for frontend integration. Core methods are accessed via PMdropin.API

Method	Description	Reference
create	Initialize component	See 1.1
mount	Mount component to page	See 1.2
on	Listen to component events	See 1.3
emit	Trigger component methods	See 1.4

1. create — Initialize Component

const card = PMdropin.create('card', options);

• ComponentName: Currently supports 'card' (Card Payments)
• options parameter:

Parameter	Type	Required	Default	Description
clientKey	string	✅	-	Client public key
sessionKey	string	✅	-	Session token
sandbox	boolean	❌	false	Enable sandbox mode
language	string	❌	'en'	Display language
theme	string	❌	'light'	Default theme
customLocalization	object	❌	-	Custom language pack
customTheme	object	❌	-	Custom styles
grayscale	string	❌	'0'	Page grayscale (0-1)
isRtl	boolean	❌	false	Right-to-left layout support
hideSaveCard	boolean	❌	false	Hide "Save Card" option
hideCardBrands	boolean	❌	false	Hide card brand logos
hideCardHolderName	boolean	❌	false	Hide cardholder name field
saveCardChecked	boolean	❌	true	Default "Save Card" checked state
ignoreUserCheckedCache	boolean	❌	false	Ignore cached user selection

2. mount — Mount Component

card.mount('#card-frame');  // Mount to the specified DOM element

Supports both id and class selectors.

3. on — Listen to Component Events

card.on('ready', () => {
  // Component loading complete
});

card.on('form-check', (res) => {
  if (res.isFormValid) {
    // Form validation passed, can enable payment button
  }
});

Event Name	Description
ready	Enable sandbox mode
form-check	Returns real-time form validation status (res.isFormValid = true/false)

4. emit — Call Component Methods

Common Methods

Method	Parameter	Description
canMakePayment	-	Validate form and get paymentToken
setDisabled	boolean	Enable/disable form interaction
switchLanguage	string	Switch language
switchTheme	string	Switch theme
addLocalization	object	Add custom language pack
addTheme	object	Add custom theme
setRtl	boolean	Enable RTL layout
setGrayscale	string	Set page grayscale (0-1)

4.1 canMakePayment — Validate Form and Get paymentToken

card.emit('canMakePayment')
  .then(res => {
    if (res.code === 'APPLY_SUCCESS') {
      const paymentToken = res.data.paymentToken;
      // Use token to initiate backend payment
    }
  })
  .catch(err => {
    console.error('Payment failed:', err);
  });

Response Structure

// Success
{
  code: 'APPLY_SUCCESS',
  data: {
    paymentToken: 'xxx'
  },
  msg: ''
}

// Failure
{
  code: 'FORM_INVALID',  // or UNKNOWN_ISSUE
  msg: 'Invalid params: cvv'
}

Code	Description
APPLY_SUCCESS	Successfully obtained paymentToken
FORM_INVALID	Form validation failed
UNKNOWN_ISSUE	Other exception errors

4.2 - 4.8 Other examples of emit usage

For more configuration, please refer to Card Customization

// Set form to non-editable state
card.emit('setDisabled', true);

// Switch language
card.emit('switchLanguage', 'zh-CN');

// Enable right-to-left layout
card.emit('setRtl', true);

// Set page grayscale to 100%
card.emit('setGrayscale', '1');

Card Customization

Through customizing language and theme styles, you can better adapt to your website's UI and user experience.

1. Language Localization

1.1 Using Preset Languages

Support setting language parameter for quick language switching:

PMdropin.create('card', {
  clientKey: '',
  sessionKey: '',
  language: 'zh' // zh: Chinese, en: English (default)
});

Can also dynamically switch through:

PMdropin.emit('switchLanguage', 'zh');

1.2 Custom Language

If preset languages don't meet requirements, can add custom fields through customLocalization:

PMdropin.create('card', {
  clientKey: '',
  sessionKey: '',
  customLocalization: {
    // Add Chinese example
    'zh': {
      loading: 'Loading',
      loadingFailed: 'Loading failed',
      refresh: 'Refresh',
      confirm: 'Confirm',
      cancel: 'Cancel',
      removeCard: 'Remove Card',
      removeCardTip: 'Are you sure to remove the currently selected card?',
      addNewCard: 'Use New Card',
      useSavedCard: 'Use Saved Card',
      cardnum: 'Card Number',
      cardnumHint: 'XXXX XXXX XXXX XXXX',
      cardnumErrTip: 'Incorrect card number',
      cardbinErrTip: {
        // {cardOrg} variable field, no need to translate
        CARD_NOT_SUPPORT: '{cardOrg} not supported, please check card number or try another card',
        // {cardType} variable field, no need to translate
        CARD_INVALID: 'Card type {cardType} not supported',
        CARD_NO_INVALID: 'Please confirm if card number input is correct',
      },
      expdate: 'Expiry Date',
      expdateHint: 'MM/YY',
      expdateErrTip: 'Incorrect expiry date',
      cvv: 'CVV/CVC',
      cvvHint: '123',
      cvvErrTip: 'CVV/CVC format incorrect',
      name: 'Cardholder Name',
      nameHint: 'XX XX',
      nameErrTip: 'Name format incorrect',
      saveCardInfoTip: 'Save information for next payment',
      // Below are new multilingual fields
      // Local card additional collection elements
      buyerEmail: 'Email',
      buyerEmailHint: '',
      buyerEmailErrTip: 'Format error, please verify',
      buyerFullName: 'Full Name',
      buyerFullNameHint: '',
      buyerFullNameErrTip: 'Format error, please verify',
      buyerFirstName: 'First Name',
      buyerFirstNameHint: '',
      buyerFirstNameErrTip: 'Format error, please verify',
      buyerLastName: 'Last Name',
      buyerLastNameHint: '',
      buyerLastNameErrTip: 'Format error, please verify',
      // Peru Document(ID)
      dni: 'DNI',
      dniHint: '',
      dniErrTip: 'Format error, please verify',
      // Argentina Document(ID)
      dni_cuit: 'DNI/CUIT',
      dni_cuitHint: '',
      dni_cuitErrTip: 'Format error, please verify',
      // South Africa Document(ID)
      idCard: 'ID',
      idCardHint: '',
      idCardErrTip: 'Format error, please verify',
      // Colombia Document(ID)
      cc: 'CC',
      ccHint: '',
      ccErrTip: 'Format error, please verify',
      // Mexico Document(ID)
      curp: 'CURP',
      curpHint: '',
      curpErrTip: 'Format error, please verify',
      // Brazil Document(ID)
      cpf: 'CPF',
      cpfHint: '',
      cpfErrTip: 'Format error, please verify',
      // Chile/Paraguay/Uruguay Document(ID)
      ci: 'CI',
      ciHint: '',
      ciErrTip: 'Format error, please verify',
      buyerPhoneNo: 'Phone Number',
      buyerPhoneNoHint: '',
      buyerPhoneNoErrTip: 'Format error, please verify',
      buyerPhoneNoRegion: 'Phone Area Code',
      buyerPhoneNoRegionHint: '',
      buyerPhoneNoRegionErrTip: 'Format error, please verify',
    }
  },
  ...
});

Dynamic addition method:

PMdropin.emit('addLocalization', {
  'zh': {
    // Parameters as shown above
  }
});

2. Theme Styles

2.1 Using Preset Themes

Supports light(default) and dark themes:

PMdropin.create('card', {
  clientKey: '',
  sessionKey: '',
  theme: 'dark'
});

Dynamic switching:

PMdropin.emit('switchTheme', 'dark');

2.2 Custom Theme

Can customize CSS variables to override theme styles through customTheme:

PMdropin.create('card', {
  clientKey: '',
  sessionKey: '',
  customTheme: [
    {
      name: 'red',
      base: 'light',
      style: `:root {
        --color-primary: #e60000;
        --bg-primary: #fff;
        --border-radius-primary: 8px;
        // ... 其他样式
      }`
    }
  ]
});

Can also add dynamically:

PMdropin.emit('addTheme', [{ name: 'red', base: 'light', style: '...' }]);