# Tokenization - Direct API Payment Integration

::: tip  
This document introduces the integration process of **Tokenization direct API payment integration mode**. 
:::

::: warning Note:
Merchants need to have PCI qualifications before they can use the CARD payment method to integrate API mode Token payment.
:::

In direct API integration mode, merchants need to build their own payment pages, such as cashier page, payment result page, etc. Therefore, this mode requires merchants to invest more R&D costs.

For more information about direct API integration mode, please refer to [Overview of Integration Modes](https://docs.payermax.com/en/202606-version/acquiring/introduction/integration-mode.html).

## 1. Integration Preparation

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

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

+ [View request addresses for different environments](https://docs.payermax.com/en/202606-version/acquiring/integration-guide.html#_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 Client
    participant MServer as Merchant Server
    participant PMServer as PayerMax Server
    participant Channel as Payment Channel
Wallet/Bank, etc.

    %% 1. Order and Payment Initiation
    User->>Client: 1.1 Select product and place order
    Client-->>User: 1.2 Return merchant checkout page
    User->>Client: 1.3 Fill in payment info
Confirm payment
    Client->>MServer: 1.4 Initiate payment
    MServer->>PMServer: 1.5 Create payment, call Direct API payment interface
with tokenForFutureUse=true
    PMServer->>Channel: 1.6 Payment request
    Channel-->>PMServer: 1.7 Return request result
    PMServer-->>MServer: 1.8 Return request result
May include redirectUrl

    %% 2. Trigger User Authentication (Logic Box)
    rect rgb(235, 245, 255)
        Note over User, Channel: User Authentication Flow
        MServer-->>Client: 1.9 Return request result
May include redirectUrl
        Client->>Client: 2.0 Redirect to redirectUrl and initiate authentication
(e.g., Wallet Login / 3DS Auth, etc.)
        User->>Client: 2.1 Enter authentication info
        Client->>Channel: 2.2 Send authentication request
        Channel->>Channel: 2.3 Authentication processing
        Channel-->>Client: 2.4 Redirect to merchant page
        Channel-->>PMServer: 3.1 Payment result notification
    end

    %% 3. Obtain Payment Result (Logic Box)
    rect rgb(235, 245, 255)
        Note over MServer, PMServer: Obtain Payment Result
        
        Note over MServer, PMServer: Via Payment Result Notification
        PMServer->>MServer: 4.1 Asynchronous notification of payment result
including paymentTokenID
        MServer->>MServer: 4.2 Update payment status
        MServer-->>PMServer: 4.3 Return response

        Note over MServer, PMServer: Via Payment Order Query
        MServer->>PMServer: 5.1 Query payment order
        PMServer-->>MServer: 5.2 Return payment order information
including paymentTokenID
        MServer->>MServer: 5.3 Update payment status
    end

    %% 4. Display Results
    Client->>MServer: 6.1 Get payment result
    Client->>Client: 6.2 Display payment result
```

## 3. Interface List

| Associative Interaction Timing                           | Calling direction        | Interface PATH                                                                                                                                    |
| -------------------------------------------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1.3 Create a payment, call the cashier's order interface | `Merchant` -> `PayerMax` | [/orderAndPay](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=cn#/paths/aggregate-pay-api-gateway-orderAndPay/post) |
| 4.1 Asynchronous notification of payment results         | `PayerMax` -> `Merchant` | [/collectResultNotifyUrl](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=cn#/paths/collectResultNotifyUrl/post)     |
| 5.1 Querying 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)   |

## 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 Create Payment

Create a payment by calling[Direct API Payment/orderAndPay API](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=cn#/paths/aggregate-pay-api-gateway-orderAndPay/post) interface, initiating an HTTP POST request.

::: warning Note:
Merchants can specify the payment close time in seconds for a single payment via the interface entry `expireTime`, the value 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 does not specify it, the exact time to close the payment will be different depending on the payment method used.
:::

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

``` json
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 '{
    "version": "1.4",
    "keyVersion": "1",
    "requestTime": "2025-05-21T07:56:20.657+00:00",
    "appId": "test81af1bdd45c4be5318305e279061",
    "merchantNo": "TEST20118706753",
    "data": {
        "outTradeNo": "test598684645",
        "subject": "Women's Long Skirts",
        "integrate": "Direct_Payment",
        "totalAmount": "74.99",
        "currency": "USD",
        "country": "AU",
        "userId": "84645",
        "language": "en",
        "reference": "2476598332645",
        "frontCallbackURL": "https://your.com/checkout-2/order-received/84645",
        "notifyUrl": "https://your.com/?wc-api=wc_payermaxcallback",
        "terminalType": "WEB",
        "paymentDetail": {
            "paymentMethodType": "CARD",
            "tokenForFutureUse": true, // Token payment logo
            "cardInfo": {
                "cardIdentifierNo": "455803****0807",
                "cardHolderFullName": "test holder",
                "cardExpirationMonth": "08",
                "cardExpirationYear": "19",
                "cvv": "808"
            },
            "buyerInfo": {
                "firstName": "Deborah",
                "lastName": "Swinstead",
                "email": "your@gmail.com",
                "phoneNo": "0609 031 114",
                "address": "Test Address",
                "city": "Holden Hill",
                "region": "SA",
                "zipCode": "5088",
                "clientIp": "211.52.321.225",
                "userAgent": "Mozilla/5.0 (iPad; CPU OS 18_4_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/22E252 [FBAN/FBIOS;FBAV/513.1.0.55.90;FBBV/735017191;FBDV/iPad13,16;FBMD/iPad;FBSN/iPadOS;FBSV/18.4.1;FBSS/2;FBID/tablet;FBLC/en_GB;FBOP/5;FBRV/737247184]"
            }
        },
        "goodsDetails": [
            {
                "goodsId": "49373",
                "goodsName": "Women's Long Skirts",
                "quantity": "2",
                "price": "38",
                "goodsCategory": "skirt",
                "showUrl": "https://your.com/product/womens-floral-print-elastic-high-waist-pleated-ruffle-flowy-long-skirts/"
            }
        ],
        "shippingInfo": {
            "firstName": "test",
            "lastName": "test",
            "email": "test@gmail.com",
            "phoneNo": "0609 031 114",
            "address1": "Test Address",
            "address2": "un",
            "address3": "Test Address, SA 5088",
            "city": "Holden Hill",
            "region": "SA",
            "state": "SA",
            "country": "AU",
            "zipCode": "5088"
        },
        "billingInfo": {
            "firstName": "test",
            "lastName": "test",
            "email": "test@gmail.com",
            "phoneNo": "0609 031 114",
            "address1": "Test Address",
            "address2": "un",
            "address3": "Test Address, SA 5088",
            "city": "Holden Hill",
            "region": "SA",
            "state": "SA",
            "country": "AU",
            "zipCode": "5088"
        },
        "envInfo": {
            "deviceLanguage": "en-AU",
            "screenHeight": "1180",
            "screenWidth": "820"
        }
    }
}'
```

Response result when `No 3ds verification required`:

``` json
{
    "msg": "Success.",
    "code": "APPLY_SUCCESS",
    "data": {
        "outTradeNo": "test_da78b1f3c2f9443b966347fc89305fc9",
        "tradeToken": "T2024052805951921811176",
        "status": "SUCCESS"
    }
}
```

Response result when `3ds verification required`:

``` json
{
    "msg": "Success.",
    "code": "APPLY_SUCCESS",
    "data": {
        // If the payment is subject to 3ds verification, the 3ds verification address will be returned and the user needs to complete the verification
        "redirectUrl": "https://cashier-n.payermax.com/index.html#/cashier/home?merchantId=020213827212251&merchantAppId=3b242b56a8b64274bcc37dac281120e3&country=ID&tradeToken=TOKEN20220117091121294138752&language=en&token=IHjqkZ8%2F%2FFcnfDPxWTvJFOrulUAKfXFUkxHJSiTdlnjnX1G6AOuTiSl6%2BN05EzxTaJkcSsSyGh5a1q%2FACwWN0sDD%2FgwY5YdWu3ghDcH2wqm%2BJIcEh0qZqo%2BQFnXp65bvkLZnY7VO7HwZGzyrpMBlPhfRCQxwBbc6lJcSYuPf%2Fe8%3D&amount=10000¤cy=IDR&frontCallbackUrl=https%3A%2F%2Fwww.payermax.com",
        "outTradeNo": "test_da78b1f3c2f9443b966347fc89305fc9",
        "tradeToken": "T2024052805951921811176",
        "status": "PENDING"
    }
}
```

In order to protect the security of user payment, PayerMax or payment channels may initiate additional user authentication process, common ones are [3DS in card payment](https://docs.payermax.com/en/202606-version/acquiring/start-integration/related-capabilities/3ds.html), user login for wallet payment and so on. If the user authentication is initiated, the interface response will additionally return `redirectUrl` and `data.status=PENDING`, and the user can use `redirectUrl` to redirect to the corresponding page, where the user can complete the authentication.

### 5.2 Jump to User Authentication

[Create Payment/orderAndPay API](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=cn#/paths/aggregate-pay-api-gateway-orderAndPay/post) The interface response `redirectUrl` indicates the user authentication page URL, after the merchant receives the response, it can redirect the jump, and the user completes the authentication information filling and submitting in this page.

### 5.3 Get Payment Result

#### 5.3.1 Adoption of notification of payment results

See [Get Payment Result Integration - Adoption of Payment Result Notification](https://docs.payermax.com/en/202606-version/acquiring/start-integration/related-capabilities/payment-result.html#_4-1-adoption-of-payment-result-notification).

Token payment notification example:

``` js
curl --request POST \
  --url https://pay-gate-uat.payermax.com/collectResultNotifyUrl \
  --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 '{
    "appId": "ff4f0273d212386sdxxxxxxxxx",
    "code": "APPLY_SUCCESS",
    "data": {
        "country": "UN",
        "totalAmount": 9.99,
        "channelNo": "PPC8xxxx017516227301xxxx",
        "outTradeNo": "ORDxxxx51006xx",
        "completeTime": "2025-07-04T09:52:11.249Z",
        "currency": "USD",
        "tradeToken": "T20xxx704098xxxx349xx",
        "paymentDetails": [
            {
                "cardInfo": {
                    "cardOrg": "VISA",
                    "country": "NZ",
                    "cardIdentifierNo": "123456******1234",
                    "cardIdentifierName": "Z**************"
                },
                "paymentTokenID": "PMTOKEN20230424072005899168200035002", //This field is returned only when Token is paid
                "paymentMethodType": "CARD"
            }
        ],
        "thirdChannelNo": "151764",
        "status": "SUCCESS"
    },
    "keyVersion": "1",
    "merchantNo": "P01010118640464",
    "msg": "Success.",
    "notifyTime": "2025-07-04T09:52:11.280Z",
    "notifyType": "PAYMENT"
}'
```

Merchant response parameter example:

``` json
{
  "msg": "Success",
  "code": "SUCCESS"
}
```

#### 5.3.2 Inquiry via Payment Orders

See [Get Payment Result Integration - Inquiry via payment order](https://docs.payermax.com/en/202606-version/acquiring/start-integration/related-capabilities/payment-result.html#_4-2-inquiry-via-payment-order).

Query input parameters:

``` js
curl --request POST \
  --url https://pay-gate-uat.payermax.com/aggregate-pay/api/gateway/orderQuery \
  --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-17T07:51:15.597+00:00",
  "appId": "a0dddd1f622243cb9aa11234e808b5f8",
  "merchantNo": "02021382716699",
  "data": {
    "outTradeNo": "P164241068068119384" # Merchant order number
  }
}'
```

Response result:

``` json
{
  "msg": "Success.",
  "code": "APPLY_SUCCESS",
  "data": {
    "reference": "reference查询和回调返回",
    "country": "SA",
    "totalAmount": 10,
    "outTradeNo": "P164241068068119384",
    "currency": "SAR",
    "channelNo": "DMCP000000000177005",
    "thirdChannelNo": "4ikqJ6ktEqyRawE1dvqb9c",
    "paymentCode": "2312121212",
    "tradeToken": "T2024062702289232000001",
    "completeTime": "2023-10-20T03:28:23.092Z",
    "paymentDetails": [
      {
        "cardInfo": {
          "cardOrg": "VISA",
          "country": "SA",
          "cardIdentifierNo": "400555******0001",
          "cardIdentifierName": "**ngwei"
        },
        "paymentMethodType": "CARD",
        "paymentTokenID": "PMTOKEN20230424072005899168200035002", //This field is returned only when Token is paid
        "payAmount": 10,
        "exchangeRate": "1",
        "paymentMethod": "CARD",
        "payCurrency": "SAR"
      }
    ],
    "status": "SUCCESS",
    "resultMsg": ""
  }
}
```
### 5.4 Payment Using PaymentTokenID

Follow the above 4 steps, after the user completes the payment, PayerMax will return the `PaymentTokenID` to the merchant. The merchant needs to save the `PaymentTokenID` and record which user and payment method the `paymentTokenID` belongs to; When making subsequent payments, the merchant uses [/orderAndPay API](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=en#/paths/aggregate-pay-api-gateway-orderAndPay/post) to pass the `payment method`, `user ID` and `PaymentTokenID` to PayerMax to complete the deduction, and no longer needs to send sensitive card information such as `cardInfo`.

#### 5.4.1 Create Payment

Merchants integrate [/orderAndPay API](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=en#/paths/aggregate-pay-api-gateway-orderAndPay/post) through API mode to complete order payment.

[/orderAndPay API](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=en#/paths/aggregate-pay-api-gateway-orderAndPay/post) Interface request example:

``` 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 API mode, specify Direct_Payment
        "totalAmount": 39.99,
        "country": "SA",
        "expireTime": "3600",
        "paymentDetail": {
            "buyerInfo": {
                "clientIp": "176.16.34.144",
                "userAgent": "Chrome"
            },
            "paymentMethodType": "CARD",
            "paymentTokenID": "PMTOKEN20230424072005899168200035002" 
        },
        "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"
    }
}'
``` 

Response result when `No 3ds verification required`:

``` json
{
    "msg": "Success.",
    "code": "APPLY_SUCCESS",
    "data": {
        "outTradeNo": "test_da78b1f3c2f9443b966347fc89305fc9",
        "tradeToken": "T2024052805951921811176",
        "status": "SUCCESS"
    }
}
```

Response result when `3ds verification required`:

``` json
{
    "msg": "Success.",
    "code": "APPLY_SUCCESS",
    "data": {
        // If the payment is subject to 3ds verification, the 3ds verification address will be returned and the user needs to complete the verification
        "redirectUrl": "https://cashier-n.payermax.com/index.html#/cashier/home?merchantId=020213827212251&merchantAppId=3b242b56a8b64274bcc37dac281120e3&country=ID&tradeToken=TOKEN20220117091121294138752&language=en&token=IHjqkZ8%2F%2FFcnfDPxWTvJFOrulUAKfXFUkxHJSiTdlnjnX1G6AOuTiSl6%2BN05EzxTaJkcSsSyGh5a1q%2FACwWN0sDD%2FgwY5YdWu3ghDcH2wqm%2BJIcEh0qZqo%2BQFnXp65bvkLZnY7VO7HwZGzyrpMBlPhfRCQxwBbc6lJcSYuPf%2Fe8%3D&amount=10000¤cy=IDR&frontCallbackUrl=https%3A%2F%2Fwww.payermax.com",
        "outTradeNo": "test_da78b1f3c2f9443b966347fc89305fc9",
        "tradeToken": "T2024052805951921811176",
        "status": "PENDING"
    }
}
```

#### 5.4.2 Get Payment Results

To obtain the payment result, please refer to [Adoption of notification of payment results](https://docs.payermax.com/en/202606-version/receipt/tokenization/direct-api.md#_5-3-1-adoption-of-notification-of-payment-results) and [Inquiry via Payment Orders](https://docs.payermax.com/en/202606-version/receipt/tokenization/direct-api.md#_5-3-2-inquiry-via-payment-orders) in step 4.

## 6. PaymentTokenID Management

Merchants can query all `PaymentTokenID`s bound to a user through the [PaymentTokenID Query API](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=en#/paths/aggregate-pay-api-gateway-inquirePaymentToken/post) interface. When a user wants to remove the bound `PaymentTokenID`, the merchant can remove the `PaymentTokenID` through the [PaymentTokenID Unbinding API](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=en#/paths/aggregate-pay-api-gateway-removePaymentToken/post).

### 6.1 Query PaymentTokenID

Merchants can query all `PaymentTokenID`s bound to a user based on the payment method, or specify a `PaymentTokenID` to query. The query result will return the corresponding masked card number and the status of the corresponding `PaymentTokenID`.

[PaymentTokenID query API](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=en#/paths/aggregate-pay-api-gateway-inquirePaymentToken/post) Interface request example:

``` json
{
    "version": "1.5",
    "keyVersion": "1",
    "requestTime": "{{requestTime}}",
    "appId": "6666c8b036a24579974497c2f9a33333",
    "merchantNo": "010213834784554",
    "data": {
        "userId": "songjiuhuaTest", // Required
        "tokenScope": "tokenAcq", // Required, fixed value tokenAcq
        "paymentMethodType": "CARD", // Optional
        "targetOrg": null, // Optional This field is optional when the value of paymentMethodType is not CARD.
        "cardOrg": "MASTERCARD", // Optional. This field is optional when the value of paymentMethodType is CARD.
        "paymentTokenID": "PMTOKEN20250626075108220812006000001" // Optional. If not filled, all paymentTokenIDs bound to the user will be returned.
    }
}
```

[PaymentTokenID query API](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=en#/paths/aggregate-pay-api-gateway-inquirePaymentToken/post) interface response example:

``` json
{
    "msg": "",
    "code": "APPLY_SUCCESS",
    "data": {
        "tokenList": [
            {
                "tokenScope": "tokenMit",
                "cardInfo": "538774******9957",
                "merchantInitiated": true,
                "paymentTokenStatus": "Activated",
                "userId": "songjiuhuaTest",
                "paymentTokenExpiry": "2099-12-31T23:59:59.000Z",
                "targetOrg": "",
                "ifCVV": "N",
                "paymentTokenID": "PMTOKEN20250523093224475590582000114",
                "accountDisplay": "",
                "paymentMethodType": "CARD",
                "brand": "MASTERCARD"
            },
            {
                "tokenScope": "tokenMit",
                "cardInfo": "538774******1234",
                "merchantInitiated": true,
                "paymentTokenStatus": "Activated",
                "userId": "songjiuhuaTest",
                "paymentTokenExpiry": "2099-12-31T23:59:59.000Z",
                "targetOrg": "",
                "ifCVV": "N",
                "paymentTokenID": "PMTOKEN20250523092615726590582000110",
                "accountDisplay": "",
                "paymentMethodType": "CARD",
                "brand": "MASTERCARD"
            }
        ]
    }
}
``` 

### 6.2 Unbinding PaymentTokenID

When the user wants to remove the bound `PaymentTokenID`, the merchant can remove the `PaymentTokenID` through this interface. After removing the `PaymentTokenID`, the merchant will no longer be able to use the `PaymentTokenID` to initiate payment.

[PaymentTokenID unbinding API](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=en#/paths/aggregate-pay-api-gateway-removePaymentToken/post) Interface request example:

``` json
{
  "version": "1.2",
  "keyVersion": "1",
  "requestTime": "2022-01-22T10:00:00.500+08:00",
  "appId": "46153e2b787241ae8b01857bb087d1bd",
  "merchantNo": "010229810189301",
  "data": {
    "userId": "songjiuhuaTest",
    "paymentTokenID": "PMTOKEN20250523093224475590582000114",
    "removeReason": "user want to remove it"
  }
}
``` 

[PaymentTokenID unbinding API](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=en#/paths/aggregate-pay-api-gateway-removePaymentToken/post) Interface response example:

``` json
{
  "code": "APPLY_SUCCESS",
  "msg": "Success",
  "data": {
    "paymentTokenID": "PMTOKEN20250523093224475590582000114",
    "userId": "songjiuhuaTest",
    "paymentTokenStatus": "Deleted"
  }
}
``` 

## 7. 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/acquiring/integration-guide.html#_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.

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