# PayByLink Integration

::: tip  
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）**](https://mmc.payermax.com/#/login)：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.

## 1. Integration Preparation

+ [Register developer center account](https://docs.payermax.com/en/202606-version/developer/integration-guide.md#_3-2-register-as-a-developer)；

+ [Upload test merchant public key](https://docs.payermax.com/en/202606-version/developer/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/202606-version/developer/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/202606-version/developer/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/202606-version/developer/integration-guide.md#_3-6-open-integrated-payment-methods)；

+ [View request addresses for different environments](https://docs.payermax.com/en/202606-version/developer/integration-guide.md#_2-environmental-information)；

+ [Understand the principles of request message signing and verification](https://docs.payermax.com/en/202606-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 Client as Merchant 
    participant Checkout as PayerMax Cashier Page
    participant PMServer as PayerMax Server
    participant Channel as Payment Channel
Wallet/Bank, etc.

    %% 1. Link Creation Phase
    Client->>PMServer: 1.1 Create link
via PayerMax Merchant Portal or API
    PMServer-->>Client: 1.2 Return payment link

    %% 2. Link Provision Phase
    Client-->>User: 2.1 Provide link
Online link or Offline QR code

    %% 3. Access and Payment Phase
    User->>Checkout: 3.1 Access link
    Checkout->>Checkout: 3.2 Render PayerMax Cashier page
Load order info
    User->>Checkout: 4.1 Select payment method
Click Pay
    Checkout->>PMServer: 4.2 Payment request
    PMServer->>Channel: 4.3 Payment request
    PMServer-->>Checkout: 4.4 Payment result
Possible redirectUrl
    Checkout->>Checkout: 4.5 Redirect to PayerMax payment result page

    %% 4. Obtain Payment Result (Logic Box)
    rect rgb(235, 245, 255)
        Note over Client, PMServer: Obtain Payment Result
        
        Note over Client, PMServer: Via Payment Result Notification
        PMServer->>Client: 5.1 Asynchronous notification of payment result
        Client->>Client: 5.2 Update payment status
        Client-->>PMServer: 5.3 Return response

        Note over Client, PMServer: Via Payment Order Query
        Client->>PMServer: 6.1 Query payment transaction
        Client->>Client: 6.2 Update payment status
    end

    %% 5. Link Management Phase
    Client->>PMServer: 7.1 Invalidate merchant link
    PMServer-->>Client: 7.2 Return request result
    Client->>PMServer: 8.1 Query payment link details
    PMServer-->>Client: 8.2 Return request result
```

## 3. Interface List

| Associative Interaction Timing                   | Calling direction        | Interface PATH                                                                                                                                            |
| ------------------------------------------------ | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1.1 Creating Links                               | `Merchant` -> `PayerMax` | [/createPaybylink](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=cn#/paths/aggregate-pay-api-gateway-createPaybylink/post) |
| 5.1 Asynchronous notification of payment results | `PayerMax` -> `Merchant` | [/payLinkResultNotifyUrl](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=cn#/paths/payLinkResultNotifyUrl/post)             |
| 6.1 Check Payment Transactions                   | `Merchant` -> `PayerMax` | [/orderQuery](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=cn#/paths/aggregate-pay-api-gateway-orderQuery/post)           |
| 7.1 Invalid Payment Links                        | `Merchant` -> `PayerMax` | [/expirePaybylink](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=cn#/paths/aggregate-pay-api-gateway-expirePaybylink/post) |
| 8.1 Check Payment Link Details                   | `Merchant` -> `PayerMax` | [/queryPaybylink](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=cn#/paths/aggregate-pay-api-gateway-queryPaybylink/post)   |

## 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 Create through MMC

Currently, PayerMax allows merchants to log in to the [Merchant Platform (MMC)](https://mmc.payermax.com/#/login) to create one-time payment links and generate QR codes. The specific path is: **Payment** → **PaybyLink** → **Create Link** .

Complete in 4 steps:

(a) Create a link;

(b) Enter order information;

(c) Generate link/QR code;

(d) Send to the user to complete payment (after the user completes the payment, the result can be queried by logging in to MMC or via API).

#### 5.1.2 Create via API

Merchants can integrate [/createPaybylink API](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=cn#/paths/aggregate-pay-api-gateway-createPaybylink/post) interfaces to create payment links through system calls.

[/createPaybylink API](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=cn#/paths/aggregate-pay-api-gateway-createPaybylink/post) Example of an interface request:

``` js
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](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=cn#/paths/aggregate-pay-api-gateway-createPaybylink/post) 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](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=cn#/paths/aggregate-pay-api-gateway-expirePaybylink/post) interface, actively disable the payment link.

[/expirePaybylink API](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=cn#/paths/aggregate-pay-api-gateway-expirePaybylink/post) Example of an interface request:

``` js
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](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=cn#/paths/aggregate-pay-api-gateway-expirePaybylink/post) 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](https://docs.payermax.com/en/202606-version/acquiring/start-integration/payment-acceptance/cashier-payment/payermax-checkout.md).

### 5.4 Check Payment Result

See [Cashier Payment Integration - 5.4 Get Payment Results](https://docs.payermax.com/en/202606-version/acquiring/start-integration/payment-acceptance/cashier-payment/payermax-checkout.md#_4-4-get-payment-result)。

### 5.5 Inquiry Link Details

[/queryPaybylink API](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=cn#/paths/aggregate-pay-api-gateway-queryPaybylink/post) Example of an interface request:

``` js
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](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=cn#/paths/aggregate-pay-api-gateway-queryPaybylink/post) 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](https://docs.payermax.com/en/202606-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/202606-version/acquiring/testing/acceptance.html).

After passing the acceptance test, the merchant can [configure  integration information for production environments](https://docs.payermax.com/en/202606-version/developer/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/202606-version/appendix/collection/transaction-status.md). Meanwhile, in [FAQs](https://docs.payermax.com/en/202606-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.