# Drop In Payment Integration ::: tip This document describes the integration process of the Drop In integration model. ::: With the pre-built front-end UI components, PayerMax can dynamically display payment information input forms according to the different payment methods selected by users. At the same time, merchants can also customize the language, style and other features of the components. For more information about the Drop In component model, please refer to [Overview of Integration Modes](https://docs.payermax.com/en/202506-version/acquiring/introduction/integration-mode.md). ## 1. Integration Preparation + [Register developer center account](https://docs.payermax.com/en/202506-version/acquiring/integration-guide.md#_3-2-register-as-a-developer)； + [Upload test merchant public key](https://docs.payermax.com/en/202506-version/acquiring/integration-guide.md#_3-4-1-configure-key-information-for-the-test-environment), get the platform public key, AppID, test merchant number and other integration information; + [Configure the callback address (WebHook)](https://docs.payermax.com/en/202506-version/acquiring/integration-guide.md#_3-4-2-configure-the-callback-address-for-the-test-environment), including the payment result callback address, refund result callback address, and so on; + [Setting up a test environment server IP whitelist](https://docs.payermax.com/en/202506-version/acquiring/integration-guide.md#_3-5-setting-up-a-whitelist-of-server-ips-for-the-test-environment)； + [Configure and enable the appropriate payment methods](https://docs.payermax.com/en/202506-version/acquiring/integration-guide.md#_3-6-open-integrated-payment-methods)； + [View request addresses for different environments](https://docs.payermax.com/en/202506-version/acquiring/integration-guide.md#_2-environmental-information)； + [Understand the principles of request message signing and verification](https://docs.payermax.com/en/202506-version/developer/config-settings.md), for generating a `sign` signature string for each HTTP request Header. ## 2. Interaction Process ```mermaid %%{init: { 'theme': 'base', 'themeVariables': { 'primaryColor': '#e6f0ff', 'primaryTextColor': '#333', 'primaryBorderColor': '#5b9bd5', 'lineColor': '#888', 'actorMargin': 40, 'noteBkgColor': '#0056b3', 'noteTextColor': '#ffffff', 'noteBorderColor': '#004a99' } }}%% sequenceDiagram participant User as User participant Page as Merchant Page participant Component as PayerMax Drop-in Component participant MServer as Merchant Server participant PMServer as PayerMax Server participant Channel as Payment Channel Wallet/Bank, etc. %% 1. Initialization Phase User->>Page: 1.1 Select product and place order Page->>MServer: 1.2 Send order information e.g., Country, Currency, etc. MServer->>PMServer: 1.3 Get Drop-in initialization info clientKey and sessionKey PMServer-->>MServer: 1.4 Return results clientKey and sessionKey MServer-->>Page: 1.5 Return results including clientKey and sessionKey Page->>Component: 1.6 Create and mount PayerMax component %% 2. Token Acquisition Phase User->>Page: 2.1 User enters payment information Page->>Component: 2.2 Request paymentToken Component->>PMServer: 2.3 Get paymentToken PMServer-->>Component: 2.4 Return result including paymentToken Component-->>Page: Return paymentToken %% 3. Order Submission and Payment User->>Page: 3.1 Confirm payment Page->>Component: 3.2 Submit payment including paymentToken Component->>MServer: 3.3 Submit order including paymentToken MServer->>PMServer: 3.4 Create payment Call Drop-in checkout API PMServer->>Channel: 3.5 Payment request PMServer-->>MServer: 3.6 Return result MServer-->>Component: 3.7 Return result Component-->>Page: 3.8 Return result %% 4. Obtain Payment Result (Logic Box) rect rgb(235, 245, 255) Note over MServer, PMServer: Obtain Payment Result Note over MServer, PMServer: Via Payment Result Notification PMServer->>MServer: 4.1 Asynchronous notification of payment result MServer->>MServer: 4.2 Update payment status MServer-->>PMServer: 4.3 Return response Note over MServer, PMServer: Via Payment Order Query MServer->>PMServer: 6.1 Query payment transaction PMServer-->>MServer: 6.2 Transaction details, including payment result MServer->>MServer: 6.3 Update payment status end ``` ## 3. Interface List | Associative Interaction Timing | Calling direction | Interface Type | Interface PATH | | -------------------------------------------------------------- | ---------------------------------------------- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 1.3 Getting Drop in Initialization Information | `Merchant` -> `PayerMax` | `Back-end Interface` | [/applyDropinSession](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=cn#/paths/aggregate-pay-api-gateway-applyDropinSession/post.html) | | 1.6 Create and mount PayerMax components | `Merchant Client` -> `PayerMax Drop In JS SDK` | `Front-end Interface` | [PMdropin.create](https://docs.payermax.com/en/202506-version/receipt/front-end-component/configuration-card.md#_1-1-create) | | 1.6 Create and mount PayerMax components | `Merchant Client` -> `PayerMax Drop In JS SDK` | `Front-end Interface` | [PMdropin.mount](https://docs.payermax.com/en/202506-version/receipt/front-end-component/configuration-card.md#_1-2-mount) | | 1.6 Create and mount PayerMax components | `Merchant Client` -> `PayerMax Drop In JS SDK` | `Front-end Interface` | [PMdropin.on](https://docs.payermax.com/en/202506-version/receipt/front-end-component/configuration-card.md#_1-3-on) | | 2.2 Get paymentToken | `Merchant Client` -> `PayerMax Drop In JS SDK` | `Front-end Interface` | [PMdropin.emit](https://docs.payermax.com/en/202506-version/receipt/front-end-component/configuration-card.md#_1-4-emit) | | 3.4 Creating a payment, calling the Drop In ordering interface | `Merchant` -> `PayerMax` | `Back-end Interface` | [/orderAndPay](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=cn#/paths/aggregate-pay-api-gateway-orderAndPay(for-drop-dont-copy-me)/post.html) | | 4.1 Asynchronous notification of payment results | `PayerMax` -> `商户` | `Back-end Interface` | [/collectResultNotifyUrl](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=cn#/paths/collectResultNotifyUrl/post.html) | | 5.1 Check Payment Transactions | `Merchant` -> `PayerMax` | `Back-end Interface` | [/orderQuery](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=cn#/paths/aggregate-pay-api-gateway-orderQuery/post.html) | ## 4. Environmental Information - **Test environment request address**：https:// `pay-gate-uat.payermax.com`/aggregate-pay/api/gateway/ `` - **Integrated Environment**：https:// `pay-gate.payermax.com`/aggregate-pay/api/gateway/ `` ## 5. Integration Steps ### 5.1 Getting Drop in Initialization Information The merchant server through the [/applyDropinSession API](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=cn#/paths/aggregate-pay-api-gateway-applyDropinSession/post.html) interface, initiates an HTTP POST request to obtain the client token `clientKey` and the session token `sessionKey` required for the initialization of the drop in. [/applyDropinSession API](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=cn#/paths/aggregate-pay-api-gateway-applyDropinSession/post.html) Example of an interface request: ``` js curl --request POST \ --url https://pay-gate-uat.payermax.com/aggregate-pay/api/gateway/applyDropinSession \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --header 'sign: FPFVT3o227JrFRbqu19boZCpVVTF9KznxyRawUmxpfXilHV/0yK46haPhAjNu1hPUMy7Vw/ILXhfzffNm4Fj0apWknlTY9OJxnSoQxS9BTFtc61tn5yV1q69x/kkBl82/qwg+XTJ4fOzy7Mar3VaC1E2PlDA6RkkKBUyNE6RYgsdB+Su7an4+4HVTNAnoe74WyvBgxTLMNg28igBTdqxaO3w/UBY6ObVp7vkqkQGdL1Y+HgmMYaAVwrM3+ALWGId0sJ+YqTY4WJ+0xCRGhaSnybiIjZsQEYyID68WNUfuavDLDsEhaMm/HfQvf5p0R1Ltovp3wwJnEbQcjY458iX5A==' \ --data '{ "version": "1.4", "keyVersion": "1", "requestTime": "2025-05-14T16:30:27.174+08:00", "appId": "test516e8ab74578be8eecd8c4803fbe", "merchantNo": "TEST010117960578", "data": { "country": "MY", # Acquiring Country "currency": "MYR", # Order Currency "totalAmount":"50", # Order Amount "userId": "20220622_00086", # User ID, must remain unique "componentList":["APPLEPAY","CARD"] # Specify the payment methods available for this order payment } }' ``` You can specify the available payment methods for this order using the `componentList` request parameter. Currently, only **`CARD`**, **`APPLEPAY`**, and **`GOOGLEPAY`** are supported. Please ensure you have signed up for the corresponding payment method. You can check your signed-up payment method through the [**Merchant Platform (MMC)**](https://mmc.payermax.com/#/login) or contact PayerMax technical support. [/applyDropinSession API](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=cn#/paths/aggregate-pay-api-gateway-applyDropinSession/post.html) Example of an interface response: ``` json { "msg": "success", "code": "APPLY_SUCCESS", "data": { "sessionKey": "bf2c47b085e24c299e45dd56fd751a70", "clientKey": "bbd8d2639a7c4dfd8df7d005294390df" } } ``` ### 5.2 Render the Drop in 1. Introduce the CDN package on the relevant HTML page. ``` html ``` 2. Embed an `iframes` on the merchant page by going over the `div` tag. ``` html ``` 3. Initialize PayerMax Frames。 ``` js // Initializing card components const card = PMdropin.create('card', { clientKey: "客户端公钥", // obtained in step 1.1 data.clientKey sessionKey: "会话令牌", // obtained in step 1.1 data.sessionKey sandbox: false, // The default is false, which means that the production environment hideSaveCard: false, //Whether to hide the save card information option, the default is false show hideCardBrands: false, //Whether to hide the logo of the card brand in the upper left corner, the default is false show }); // Example of mounting card.mount('.frame-card'); // Mounts to the first dom element it matches. // Timing of component loading completion card.on('ready', () => { // Remove customized loading }) ``` 4. Listen to form filling status and set payment button dynamically (optional). By listening to the events of the form, you can monitor the legitimacy of the information filled in by the user in real time, so as to dynamically set whether the **Payment** button can be clicked or not. ``` js card.on('form-check', (res) => { // res.isFormValid is the form status. The value is false/true // true means the form passes the validation and can be paid, false means the validation doesn't pass and can't be paid, and the pay button can't be clicked. console.log('[dropin][form-check]:', res) }) ``` Download the complete [Drop In Integration DEMO](https://img-cdn-sg.payermax.com/public/20250703-85aff055-dea2-4851-87c9-acd1a439c94f.zip), replace `sessionKey` and `clientKey`, then you can run it locally and view the frontend component integration sample. ### 5.3 Create Payment 1. Merchant client: the user clicks to initiate a payment, checks if the payment is available, and gets the `paymentToken`. ``` js card.emit('setDisabled', true) // Freeze the form after clicking the payment button to prevent double submission of the payment process card.emit('canMakePayment') .then(res => { if (res.code === 'APPLY_SUCCESS') { const paymentToken = res.data.paymentToken // Payment token, payment interface usage // Initiates the payment interface // The merchant itself requests the backend interface to place the order // The merchant itself constructs the request parameters with params, which need to be accompanied by a paymentToken. _postapi('orderAndPay',params).then(res =>{ const code = (res || {}).code //Merchants return payment results to the front end if (code == 'APPLY_SUCCESS') { //Payment success, show payment result } else { //Payment failure, show payment result } } card.emit('setDisabled', false) // Unfreeze form after payment interface completion } }) .catch(err => { card.emit('setDisabled', false) // Unfreeze form after an exception occurs }) ``` 2. Merchant server: calls the [/orderAndPay API](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=cn#/paths/aggregate-pay-api-gateway-orderAndPay(for-drop-dont-copy-me)/post.html) interface to initiate the HTTP POST request and create the payment. ::: warning Note: 1. In card payment, 3DS authentication process may be triggered. Please refer to [Card Payment - Drop In Integration - Complete 3DS Authentication](https://docs.payermax.com/en/202506-version/acquiring/start-integration/integrate-by-payment-method/card/frontend-component.md#_5-4-complete-3ds-authentication). 2. After the payment is created, the merchant can specify the payment shutdown time in seconds for a single payment via the interface entry `expireTime`, the value of which must be greater than 1800 (30 minutes) and less than 86400 (24 hours). If the value passed in is less than 1800, the system will reset to the minimum value of 30min; if the value passed in is less than 86400, the system will reset to the maximum value of 86400. If the merchant doesn't specify it, the specific shutdown time will be different according to the payment method used. ::: [/orderAndPay API](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=cn#/paths/aggregate-pay-api-gateway-orderAndPay(for-drop-dont-copy-me)/post.html) Example of an interface request: ``` js curl --request POST \ --url 'https://pay-gate-uat.payermax.com/aggregate-pay/api/gateway/orderAndPay' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --header 'sign: FPFVT3o227JrFRbqu19boZCpVVTF9KznxyRawUmxpfXilHV/0yK46haPhAjNu1hPUMy7Vw/ILXhfzffNm4Fj0apWknlTY9OJxnSoQxS9BTFtc61tn5yV1q69x/kkBl82/qwg+XTJ4fOzy7Mar3VaC1E2PlDA6RkkKBUyNE6RYgsdB+Su7an4+4HVTNAnoe74WyvBgxTLMNg28igBTdqxaO3w/UBY6ObVp7vkqkQGdL1Y+HgmMYaAVwrM3+ALWGId0sJ+YqTY4WJ+0xCRGhaSnybiIjZsQEYyID68WNUfuavDLDsEhaMm/HfQvf5p0R1Ltovp3wwJnEbQcjY458iX5A==' \ --data '{ "requestTime": "2025-05-28T03:52:42.591-02:00", "keyVersion": "1", "appId": "tested7c863c439a9e29b4519867965a", "version": "1.4", "merchantNo": "TEST10116880289", "data": { "integrate": "Direct_Payment", # In Drop In mode, specify Direct_Payment "totalAmount": 39.99, "country": "SA", "expireTime": "3600", "paymentDetail": { # When payment is made, it is fetched via the canMakePayment event response of the JS SDK's emit interface, non-null "paymentToken": "TEST12637c2c2d942239d9a2661c4ad14f9", "buyerInfo": { "clientIp": "176.16.34.144", "userAgent": "Chrome" }, # When paid, fetched via the response of the JS SDK's create interface, non-null "sessionKey": "test29632c3643768e3b65ef6a31c9ce" # Non-null in Drop In mode }, "frontCallbackUrl": "https://front.your.com/pay/index.html", "subject": "River Game HK Limited", "outTradeNo": "ov1_da78b1f3c2f9443b966347fc89305fc9", "notifyUrl": "https://notify.your.com/pay/paymentWebHookPayerMaxServlet", "currency": "SAR", "userId": "1822613953000446", "terminalType": "WEB" } }' ``` [/orderAndPay API](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=cn#/paths/aggregate-pay-api-gateway-orderAndPay(for-drop-dont-copy-me)/post.html) Example of an interface response: ``` json { "msg": "Success.", "code": "APPLY_SUCCESS", "data": { "outTradeNo": "test_da78b1f3c2f9443b966347fc89305fc9", "tradeToken": "T2024052805951921811176", "status": "SUCCESS" } } ``` ### 5.4 Get Payment Results [Create Payment/orderAndPay API](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=cn#/paths/aggregate-pay-api-gateway-orderAndPay/post.html) The `data.status` of the interface response is not a payment end-state and therefore should not be used by merchants to update payment results directly. #### 5.4.1 Adoption of notification of payment results See [Get Payment Result Integration - Adoption of Payment Result Notification](https://docs.payermax.com/en/202506-version/acquiring/start-integration/related-capabilities/payment-result.md#_4-1-adoption-of-payment-result-notification). #### 5.4.2 Inquiry via Payment Orders See [Get Payment Result Integration - Inquiry via payment order](https://docs.payermax.com/en/202506-version/acquiring/start-integration/related-capabilities/payment-result.md#_4-2-inquiry-via-payment-order). ## 6. Test Go Live After the merchant has completed the above integration steps, he/she can initiate the actual payment request for preliminary testing and validation, please refer to [Integration Testing - Start a test](https://docs.payermax.com/en/202506-version/receipt/test-cases.md) for the specific steps. After the test is passed and before the final release, the merchant must contact PayerMax technical support to submit the order information for the test so that PayerMax can check the request logs and data to confirm that you have correctly integrated the relevant capabilities, as described in [Integration Testing - Initiate Acceptance](https://docs.payermax.com/en/202506-version/acquiring/testing/acceptance.md). After passing the acceptance test, the merchant can [configure integration information for production environments](https://docs.payermax.com/en/202506-version/acquiring/integration-guide.md#_7-3-configuring-integration-information-for-production-environments) and prepare for the opening of the volume. In addition, under **Acquiring Product Integration**, there are integration documents for the various payment methods supported by PayerMax, which contain instructions for testing each payment method. ## 7. Troubleshooting For response errors during testing or acceptance, you can refer to [Troubleshooting - Error Code](https://docs.payermax.com/en/202506-version/appendix/collection/transaction-status.md). Meanwhile, in [FAQs](https://docs.payermax.com/en/202506-version/appendix/faq/collection/cashier-direct-api.md), we summarize and list all kinds of common problems and how to deal with them. You can also contact PayerMax technical support team directly for any questions during integration, testing and acceptance.