Paybylink Integration
This document describes the integration process of the PayerMax paybylink payments integration model.
When using paybylink payments, the merchant creates a payment link and the user pays using that payment link. PayerMax offers two ways to use the link payment feature:
Based on PayerMax Merchant Platform（MMC）：no API integration required, just register and open an MMC platform account to create and manage payment links.
Based on paybylink API：Several APIs must be integrated, and merchants can meet personalized and more flexible link creation and management.
For more information about the Link Payment Integration Mode, 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 PATH |
| 1.1 Creating Links | Merchant -> PayerMax | /createPaybylink |
| 5.1 Asynchronous notification of payment results | PayerMax -> Merchant | /payLinkResultNotifyUrl |
| 6.1 Check Payment Transactions | Merchant -> PayerMax | /orderQuery |
| 7.1 Invalid Payment Links | Merchant -> PayerMax | /expirePaybylink |
| 8.1 Check Payment Link Details | Merchant -> PayerMax | /queryPaybylink |
4. Environmental Information
Test Environment：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 Create Payment Links
PayerMax offers two ways to create payment links.
5.1.1 Created through MMC
After the merchant has activated the PayerMax Merchant Platform（MMC）, they can log in to the PayerMax Merchant Platform（MMC）, go to → → to create a one-time payment link and generate a QR code, as shown below.
After creating the payment link, merchants also need to enter order information, including the receiving country/region, order amount, order description, link expiration date, and link notes.
Order amount：unit price of goods * quantity of goods;
Order Description：When a payment is made, it is displayed to the user, either with descriptive information about the product or the purpose of receiving payment, etc;
Link Note：Not displayed to the user, it will be returned to the merchant via the
linkDescriptionfield of the Payment Results Callback API.
Once the information is filled in, the payment link and its QR code can be generated as shown below.
5.1.2 Created via API
Merchants can integrate /createPaybylink API interfaces to create payment links through system calls.
/createPaybylink API Example of an interface request:
curl --request POST \
--url https://pay-gate-uat.payermax.com/aggregate-pay/api/gateway/createPaybylink \
--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": "2022-01-22T10:00:00.500+08:00",
"appId": "6666c8b036a24579974497c2f9a33333",
"merchantNo": "010213834784554",
"data": {
"merchantLinkId": "paylinktest001",
"linkType": "ONETIME",
"expiresTime": "86400",
"country": "ID",
"currency": "IDR",
"totalAmount": "40000",
"language": "en",
"description": "冬季新款运动鞋",
"linkDescription": "链接收款衣物鞋帽",
"userInfo": {
"userId": "98",
"username": "孟艳"
},
"goodsDetails": [
{
"goodsName": "运动鞋",
"goodsDescription": "冬季新款减震跑步运动鞋",
"quantity": "2",
"price": "20000",
"goodsCurrency": "IDR",
"showUrl": "http://dummyimage.com/400x400"
}
],
"merchantInfo": {
"logoUrl": "http://dummyimage.com/logo/100x100",
"contactEmail": "i.bbnettq@qq.com"
},
"notifyUrl": "http://srprnjkx.bv/ifgarmv"
}
}'/createPaybylink API Example of an interface request:
{
"code": "APPLY_SUCCESS",
"msg": "SUCCESS.",
"data": {
"linkId": "iwockllp",
"merchantLinkId": "paylinktest001",
"linkUrl": "https://www.payermax.link/qltvlsd",
"linkStatus": "ACTIVE",
"qrCodeUrl": "https://www.payermax.link/imagesqrcode",
"expiresAt": "2022-11-01T10:00:00.000+08:00"
}
}5.2 Failed Payment Links
After creating a payment link, the merchant can through /expirePaybylink API interface, actively disable the payment link.
/expirePaybylink API Example of an interface request:
curl --request POST \
--url https://pay-gate-uat.payermax.com/aggregate-pay/api/gateway/expirePaybylink \
--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": "2022-01-22T10:00:00.500+08:00",
"appId": "6666c8b036a24579974497c2f9a33333",
"merchantNo": "010213834784554",
"data": {
"merchantLinkId": "paybylinktest001" # Payment Link ID
}
}'/expirePaybylink API Example of an interface response:
{
"code": "APPLY_SUCCESS",
"msg": "SUCCESS.",
"data": {
"linkId": "jyirffse",
"merchantLinkId": "paybylinktest001", # Payment Link ID
"linkStatus": "ACTIVE",
"expiresAt": "2022-10-20T10:00:00.500+08:00",
"linkUrl": "https://www.payermax.link/mtfbpomjw",
"qrCodeUrl": "https://www.payermax.link/images/mtfbpomjwquc/qrcode"
}
}5.3 Jump to PayerMax checkout page
Users can jump to the PayerMax cashier page via a payment link or QR code. After selecting a payment method, the payment request is initiated and the payment process and experience is similar to cashier payment.
5.4 Check Payment Result
See Cashier Payment Integration - 5.4 Get Payment Results。
5.5 Inquiry Link Details
/queryPaybylink API Example of an interface request:
curl --request POST \
--url https://pay-gate-uat.payermax.com/aggregate-pay/api/gateway/queryPaybylink \
--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": "2022-01-22T10:00:00.500+08:00",
"appId": "6666c8b036a24579974497c2f9a33333",
"merchantNo": "010213834784554",
"data": {
"merchantLinkId": "paybylinktest001"
}
}'/queryPaybylink API Example of an interface response:
{
"code": "APPLY_SUCCESS",
"msg": "SUCCESS.",
"data": {
"linkId": "jyirffse",
"merchantLinkId": "paybylinktest001",
"totalAmount": "10000",
"country": "ID",
"currency": "IDR",
"linkStatus": "ACTIVE",
"expiresAt": "2022-11-22T10:00:00.500+08:00",
"linkUrl": "https://www.payermax.link/mtfbpomjw",
"qrCodeUrl": "https://www.payermax.link/images/mtfbpomjwquc/qrcode",
"description": "冬季新款运动鞋",
"linkDescription": "链接收款衣物鞋帽",
"payByLinkInfo": [ # Payment information. Non-empty if the link is paid.
{
"outTradeNo": "order2022001",
"status": "SUCCESS",
"completeAt": "2022-10-20T10:00:00.500+08:00",
"paymentDetails": [
{
"targetOrg": "",
"paymentMethodType": "CARD",
"cardInfo": {
"cardOrg": "VISA",
"cardIdentifierNo": "625244*********9483"
}
}
]
}
],
"goodsDetails": { # Product Information. Non-null if the link is paid.
"goodsId": "ZAK1002",
"goodsName": "MacPro 14",
"quantity": "1",
"price": "14999.00",
"showUrl": "https: //xxx.xxx.com/SKU1239438283"
}
}
}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.