Drop-in
    • Drop-in Overview
    • Drop-in Integration Step
    • Drop-in Integration Step - 中文
    • SDK Parameter Reference - 中文
    • SDK Parameter Reference

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

    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.

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

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

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

    9: Using Drop-in to save cards (Save Card)#

    Drop-in supports letting shoppers save their card during checkout, so the card can be reused for future payments without re-entering the card details. The integration flow is about the same as the standard payment flow above, with the following adjustments:

    Step 1: Enable Save Card when creating the order#

    In the 4th step (Obtain sessionID), when calling the LinkPay API, use the following parameters to enable the Save Card feature and bind the saved card to a specific user:
    {
  "userInfo": {
    "reference": "your_user_reference"
  }
}
    userInfo.reference: A unique identifier of the user in your system, used to associate the saved card token.
    Once enabled, Drop-in will display a "Save card" checkbox on the card payment form.

    Step 2: Shopper opts in within Drop-in#

    The shopper ticks the "Save card" checkbox in the Drop-in card form before completing the payment. Only when the checkbox is selected will the card be tokenized and saved.

    Step 3: Receive and store the Token#

    After payment is completed, retrieve the token from either the webhook notification (step 7) or the GET Payment API.
    Store the token.value in your system and bind it with userInfo.reference.

    Step 4: Pay later with the saved Token#

    For subsequent payments, use the Payment API to initiate the transaction with the saved token. The request parameters must include (see the Appendix Payment API interface for details):
    {
  "paymentMethod": {
    "token": {
      "value": "previously saved token value"
    }
  }
}
    Order Tracking: Use merchantTransID to track the order ID of the subsequent payments.
    Capture transactions:
    captureAfterHours should be 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.
    Previous
    Drop-in Overview
    Next
    Drop-in Integration Step - 中文
    Built with