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
Upload test merchant public key, get the platform public key, AppID, test merchant number and other integration information;
Configure the callback address (WebHook), including the payment result callback address, refund result callback address, and so on;
Understand the principles of request message signing and verification, for generating a
signsignature string for each HTTP request Header.
2. Interaction Process
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 |
| 1.6 Create and mount PayerMax components | Merchant Client -> PayerMax Drop In JS SDK | Front-end Interface | PMdropin.create |
| 1.6 Create and mount PayerMax components | Merchant Client -> PayerMax Drop In JS SDK | Front-end Interface | PMdropin.mount |
| 1.6 Create and mount PayerMax components | Merchant Client -> PayerMax Drop In JS SDK | Front-end Interface | PMdropin.on |
| 2.2 Get paymentToken | Merchant Client -> PayerMax Drop In JS SDK | Front-end Interface | PMdropin.emit |
| 3.4 Creating a payment, calling the Drop In ordering interface | Merchant -> PayerMax | Back-end Interface | /orderAndPay |
| 4.1 Asynchronous notification of payment results | PayerMax -> 商户 | Back-end Interface | /collectResultNotifyUrl |
| 5.1 Check Payment Transactions | Merchant -> PayerMax | Back-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:
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
}
}'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:
{
"msg": "success",
"code": "APPLY_SUCCESS",
"data": {
"sessionKey": "bf2c47b085e24c299e45dd56fd751a70",
"clientKey": "bbd8d2639a7c4dfd8df7d005294390df"
}
}5.2 Render the Drop in
- Introduce the CDN package on the relevant HTML page.
<script src="https://cdn.payermax.com/dropin/js/pmdropin.min.js"></script>- Embed an
iframeson the merchant page by going over thedivtag.
<div class="frame-card">
<!-- 表单内容 -->
</div>- Initialize PayerMax Frames。
// 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
})- 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 button can be clicked or not.
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
- Merchant client: the user clicks to initiate a payment, checks if the payment is available, and gets the
paymentToken.
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
})- 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:
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:
{
"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.