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

Interface registration developer center account；
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;
Setting up a test environment server IP whitelist；
Configure and enable the appropriate payment methods；
View request addresses for different environments；
Understand the principles of request message signing and verification, for generating a sign signature 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 Payment → PaybyLink → Create Linkto 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 linkDescription field 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:

json

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

json

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

json

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

Overview of Integration Modes

Payment Method List

Acquiring Products Integration

Acquiring Basic Products

CARD

GOOGLEPAY

APPLEPAY

Subscription and Autp Debit

Integration Mode Connection

Drop In

Related Capabilities Integration

ChargeBack

Risk Control

Integration Testing

Troubleshooting

Integration

API Disbursement

Payment Method List

Europe

Related Capabilities (Notification/Transaction Inquiry)

Transaction Report

Global Collection

Paybylink Integration

1. Integration Preparation

2. Interaction Process

3. Interface List

4. Environmental Information

5. Integration Steps

5.1 Create Payment Links

5.1.1 Created through MMC

5.1.2 Created via API

5.2 Failed Payment Links

5.3 Jump to PayerMax checkout page

5.4 Check Payment Result

5.5 Inquiry Link Details

6. Test Go Live

7. Troubleshooting

Overview of Integration Modes

Acquiring Basic Products

CARD

GOOGLEPAY

APPLEPAY

Subscription and Autp Debit

Drop In

ChargeBack

Risk Control

Troubleshooting

API Disbursement

Payment Method List

Europe

Paybylink Integration ​

1. Integration Preparation ​

2. Interaction Process ​

3. Interface List ​

4. Environmental Information ​

5. Integration Steps ​

5.1 Create Payment Links ​

5.1.1 Created through MMC ​

5.1.2 Created via API ​

5.2 Failed Payment Links ​

5.3 Jump to PayerMax checkout page ​

5.4 Check Payment Result ​

5.5 Inquiry Link Details ​

6. Test Go Live ​

7. Troubleshooting ​

Paybylink Integration

1. Integration Preparation

2. Interaction Process

3. Interface List

4. Environmental Information

5. Integration Steps

5.1 Create Payment Links

5.1.1 Created through MMC

5.1.2 Created via API

5.2 Failed Payment Links

5.3 Jump to PayerMax checkout page

5.4 Check Payment Result

5.5 Inquiry Link Details

6. Test Go Live

7. Troubleshooting