Drop-in Integration Step

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 Integration

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

npm install cil-dropin-components
or
yarn add 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.

import DropInSDK from '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/[email protected]/dist/index.min.js

2: Adding Drop-in to a HTML container

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

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

3: 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.

Fetch Session ID

Open Recipe

📘
Note
Transaction authentication of the interaction interface is completed through the SignKey (in the Authorization request header) and KeyID in the request header.

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

4: 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
Other parameters：Please refer to SDK reference for more parameters options.

5: 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")

Sample Code：

function handlePaymentCompleted(params) {
  const result = { type: 'payment_completed', ...params };
  displayPaymentStatus('Payment Successful', 'success', result);
  return result;
}

function handlePaymentFailed(params) {
  const result = {
    type: 'payment_failed',
    ...params,
    code: params.code || 'Decline Code',
    message: params.message || 'Decline Message'
  };
  console.error('Payment Failed:', result);
  displayPaymentStatus(`Payment Failed: ${result.message}`, 'error', result);
  return result;
}

function handlePaymentNotPreformed(params) {
  const result = {
    type: 'payment_not_preformed',
    ...params,
    code: params.code || 'Response Code',
    message: params.message || 'Response Message'
  };
  console.warn('Payment Declined:', result);
  displayPaymentStatus('Payment Declined, please retry', 'warning', result);
  return result;
}

function handlePaymentCancelled(params) {
  const result = { type: 'payment_cancelled', ...params };
  console.log('Payment Cancelled:', result);
  displayPaymentStatus('Payment is cancelled', 'info', result);
  return result;
}

function displayPaymentStatus(message, statusType, result) {
  const statusEl = document.getElementById('status');
  statusEl.innerHTML = `
    <div style="padding: 16px; border: 1px solid">
      <h3>${message}</h3>
      <p>Type: ${result.type}</p>
      ${result.merchantTransID ? `<p>Transaction ID: ${result.merchantTransID}</p>` : ''}
      ${result.sessionID ? `<p>Session ID: ${result.sessionID}</p>` : ''}
      ${result.code ? `<p>Response Code: ${result.code}</p>` : ''}
      ${result.message ? `<p>Response Message: ${result.message}</p>` : ''}
    </div>
  `;
}

6: 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.

Notification from Webhook

Open Recipe

📘
Note
After receiving a notification, the plain text "SUCCESS" must be returned to indicate successful receipt. If no response is received, the system will periodically resend asynchronous notifications at the specified frequency (15/15/30/180/1800/1800/1800/1800/3600 seconds) until a "SUCCESS" message is received or the maximum number of notifications is reached.

Parameters please refer to API Explorer interaction Notification。

7: Using Drop-in for subscriptions

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:

Change in the 4th step (Obtain sessionID） When calling the Interaction API, use the following parameters:

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

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": "Previously saved token value"
    },
    "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.

Subscription Payment

Open Recipe

Drop-in Integration Step

1: SDK Integration

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

Method 2: Load the JS resource via CDN

2: Adding Drop-in to a HTML container

3: Obtain sessionID

Note

4: DropIn SDK Initialization:

5: Handling response from Payment API

6: Handling Payment webhooks:

Note

7: Using Drop-in for subscriptions

First Time Subscription:

Subsequent subscription (MIT Transaction)

8: Other Optional APIs:

Get Payment Details

Capture Payment

Refund Payment