Skip to content

Drop In Payment Integration

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.

1. Integration Preparation

2. Interaction Process

3. Interface List

Associative Interaction TimingCalling directionInterface TypeInterface PATH
1.3 Getting Drop in Initialization InformationMerchant -> PayerMaxBack-end Interface/applyDropinSession
1.6 Create and mount PayerMax componentsMerchant Client -> PayerMax Drop In JS SDKFront-end InterfacePMdropin.create
1.6 Create and mount PayerMax componentsMerchant Client -> PayerMax Drop In JS SDKFront-end InterfacePMdropin.mount
1.6 Create and mount PayerMax componentsMerchant Client -> PayerMax Drop In JS SDKFront-end InterfacePMdropin.on
2.2 Get paymentTokenMerchant Client -> PayerMax Drop In JS SDKFront-end InterfacePMdropin.emit
3.4 Creating a payment, calling the Drop In ordering interfaceMerchant -> PayerMaxBack-end Interface/orderAndPay
4.1 Asynchronous notification of payment resultsPayerMax -> 商户Back-end Interface/collectResultNotifyUrl
5.1 Check Payment TransactionsMerchant -> PayerMaxBack-end Interface/orderQuery

4. Environmental Information

  • Test environment request address:https:// pay-gate-uat.payermax.com/aggregate-pay/api/gateway/ <Interface PATH>

  • Integrated Environment:https:// pay-gate.payermax.com/aggregate-pay/api/gateway/ <Interface PATH>

5. Integration Steps

5.1 Getting Drop in Initialization Information

The merchant server through the /applyDropinSession API 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 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.1",
        "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
        }
}'

The actual payment methods available for this order can be specified via the request parameter componentList, the value of which must be a payment method that has been contracted by the merchant. Merchants can check their contracted payment methods via Merchant Platform(MMC) or consult PayerMax technical support.

/applyDropinSession API 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
<script src="https://cdn.payermax.com/dropin/js/pmdropin.min.js"></script>
  1. Embed an iframes on the merchant page by going over the div tag.
html
<div class="frame-card">  
    <!-- 表单内容 -->
</div>
  1. 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              
})
  1. 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, 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
  })
  1. Merchant server: calls the /orderAndPay API interface to initiate the HTTP POST request and create the payment.

Note:

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

5.4.2 Inquiry via Payment Orders

See Get Payment Result Integration - 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 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.

After passing the acceptance test, the merchant can configure 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. Meanwhile, in FAQs, 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.

Was this page helpful?

Thank you for your help in improving PayerMax Product Docs!

Last updated:

Released under the MIT License.