Drop-in Integration Step

This guide is for developers and provide details to integrate online payment functionality through Drop-in from scenarios such as payment subscriptions.

The core steps and data flow of the integration process are shown in the following figure. You can flexibly participate in the modules according to your actual needs.

1: SDK Installation

Method 1: Install the cil-dropin-components SDK as a dependency of your project using npm or yarn.

npm

npm install cil-dropin-components

yarn

yarn add cil-dropin-components

Method 2: Load the JS resource via CDN

It is recommended to use our provided index.min.js as a fallback in case the CDN fails to load.

Latest version:
https://cdn.jsdelivr.net/npm/cil-dropin-components@latest/dist/index.min.js

Specific version:
https://cdn.jsdelivr.net/npm/cil-dropin-components@1.0.4/dist/index.min.js

2: SDK Import

Import the DropInSDK into your front-end code to use its features in your page. The import method varies depending on your technology stack.

import DropInSDK from 'cil-dropin-components'

Import the DropInSDK into your front-end code to use its features in your page. The import method varies depending on your technology stack.

Add a container element to the front-end page to render the DropIn component, for example:

<div id="dropInApp"></div>

4: Obtain sessionID

Before initializing the DropInSDK, you must first obtain the sessionID. The backend obtains the sessionID from the response of calling the integration API, which needs to be extracted and passed to the front-end DropInSDK.

For more parameter details, see the LinkPay API Interface details.

5: DropIn SDK Initialization:

Initialize the DropInSDK using the sessionID obtained from the previous step and other necessary parameters to render the payment interface and process user delivery:

const sdk = new DropInSDK({
  id: '#dropInApp',
  type: 'payment',
  sessionID: 'your-session-id',
  locale: 'en-US',
  mode: 'embedded',
  environment: 'UAT',
  appearance: {
    colorBackground: '#fff'
  },
  payment_completed: handlePaymentCompleted,
  payment_failed: handlePaymentFailed,
  payment_not_preformed: handlePaymentNotPreformed,
  payment_cancelled: handlePaymentCancelled
});

Required Parameters:

• id: CSS Contaner Selector
• type: Component Type
• sessionID: Obtained the unique sessionID from payment API.
• locale: Interface language code(e.g., 'en-US'、'zh-CN')
• mode: Display Mode('embedded' or 'fullPage')
• environment: SDK environment(e.g., 'UAT' for Sandbox，'HKG_prod' for Production)

Optional Parameters:

• appearance: Customize interface style
• Callback function: See next step
• Callback function: See next step：Please refer to SDK reference for more parameters options.

6: Handling response from Payment API

Process the payment callback returned by the DropInSDK, record key data (such as merchantTransID), update the UI, and trigger subsequent operations.

• payment_completed: When payment is successful. return:{ type: 'payment_completed', merchantTransID, sessionID }

  • store merchantTransID(For future transaction enquiry and refund)
  • Update UI to show "Payment Successful"

• payment_failed: When payment is failed / declined. return: { type: 'payment_failed', merchantTransID, sessionID, code, message }

  • store merchantTransID、code and message
  • Display error message (such as “Transaction Failed：{message}”)

• payment_not_preformed: Triggered when payment is not executed (e.g. user does not complete the payment process) return: { type: 'payment_not_preformed', merchantTransID, sessionID, code, message }

  • store merchantTransID and code
  • Display prompts (e.g. "Payment not completed, please try again")

• payment_cancelled: Triggered when the user cancels the payment return: { type: 'payment_cancelled', sessionID }

  • Display prompt (e.g. "Payment Cancelled")

7: Handling Payment webhooks:

Set the webhook endpoint from step 4 to receive asynchronous notifications from Evonet. Notifications typically contain the following fields:

• result: payment status code
• merchantOrderID: To check order status
• merchantTransID: To carry out payment refunds
• status: Order status code, used to update the database order status
• Other parameters：time, amount, etc.

Parameters please refer to API Explorer LinkPay Notification。

8: Using Drop-in for subscriptions(Coming)

It is possible to use Drop-in to setup subscription scenario, the integration flow is about the same as above, only few minor adjustments as below:

First Time Subscription:

1. Change in the 4th step (Obtain sessionID) When calling the LinkPay API, use the following parameters:

{
  "userInfo": {
    "reference": "your_user_reference"
  },
  "paymentMethod": {
    "recurringProcessingModel": "Subscription"
  }
}

2. Save the Token
   • After payment is completed, store the token from either webhook or payment response API.
   • Store the token.value in your system and bind it with userInfo.reference.

Subsequent subscription (MIT Transaction)

• Use the Payment API to initiate the transaction.
• The request parameters must include (see the Appendix Payment API interface for details):

{
  "paymentMethod": {
    "token": {
      "value": "之前保存的token值"
    },
    "recurringProcessingModel": "Subscription"
  }
}

• Order Tracking: Use merchantTransID to track the order ID of the subsequence payments.
• Capture transactions:
  • captureAfterHours should set to "0" for immediate capture
  • If this field is not provided, the merchant must later call the POST /capture API to perform manual capture.