Welcome to the elite way of handling payments. This guide walks you through the Drop-in SDK and API—a lightweight, high-performance integration that handles the heavy lifting of security and UI while you focus on building your business.

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.

🛠 Phase 1: Setting the Stage (Client-side)

👍

Goal: Drop a secure payment frame into your site with zero CSS stress.

1. SDK Integration

Include our lightweight JavaScript engine 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

2. Adding Drop-in to an HTML container

Place a simple container in your HTML. This is where the Drop-in UI will elegantly materialize.

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

⚡ Phase 2: Igniting the Engine (Server-side & Initialization)

👍

Goal: Secure a handshake between your server and ours.

3. Fetch the "Golden Ticket" (SessionID)

Before initializing the DropInSDK, you must first obtain the sessionID from interaction API By Calling interaction API, you can decide the transaction expiry time, transaction type, user's data to collect.

📘

Note

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

• Security First: Authenticate using your SignKey and KeyID in the headers.
• The Payload: Define the amount, currency, and transaction type.
• The Result: Your server receives a unique sessionID—pass this to your frontend to unlock the payment vault.

💡If you aim to create a subscription payment

1. The below parameter is mandatory for creating subscription payment

2. Save the Token

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

Example

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

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:

Here is the minimum mandatory value to initialize the SDK. Let's check from SDK reference to get more optional and default setting.

Example

const sdk = new DropInSDK({
  id: '#dropApp', 
  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
});

📡 Phase 3: Mastering the Lifecycle (Handling Results)

There are 2 ways to reflects the latest status of order, SDK events and Webhooks. While SDK events can is an instant browser-side notification used to update your UI immediately; and Webhooks are server-to-server messages to update the final transaction status, which can be retry to ensure your database stays in sync even if the customer goes offline. Both are important and necessary tools for catching-up the order situation.

5. Handling Payment Callbacks

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

✅ payment_completed: Success! Store the merchantTransID immediately—you’ll need it for future refunds or status lookups.

❌ Other Error Handling: Use the returned message to show friendly, actionable tips to your users if a payment fails.

For the full specification of SDK event, please refer to SDK Event Reference.

6. Handling Payment Webhooks:

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

For parameters, please refer to API Explorer interaction Notification.

📘

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.

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:

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

   JSON

   {
     "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):
  JSON

  {
    "paymentMethod": {
      "token": {
        "value": "Previously saved token value"
      },
      "recurringProcessingModel": "Subscription"
    }
  }

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

8. Other Value-Added Drop-in Functions

• Recurring & Subscriptions -
• Card Bin Verification - to validate a customer’s card number before enabling payment. To support merchant perform additional business-specific validation before the transaction proceeds.

9. Other Optional APIs:

Get Payment Details

Using GET /payment/{merchantTransID} to query a payment status, merchantTransID is obtained from payment.merchantTransInfo.merchantTransID

Capture Payment

For authorized transactions, this API can be used to carry out capture POST /payment/{merchantTransID}/capture

Refund Payment

For transaction that is captured, use POST /payment/{merchantTransID}/refund to carry out partial or full refund of the transaction.