# Merchant-customized Checkout Integration Under the Specific Payment Method integration mode, after a user places an order, they are redirected to the specified APM wallet page to make the payment. Under this integration mode, merchants need to develop their own checkout page. ## 1. Interaction Flow ```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 Checkout as PayerMax Cashier participant PMServer as PayerMax Server participant Channel as Payment Channel Wallet/Bank, etc. %% 1. Ordering Phase User->>Client: 1.1 Select product and place order Client->>MServer: 1.2 Place order MServer->>PMServer: 1.3 Create payment Call Cashier checkout API PMServer->>PMServer: Create transaction PMServer-->>MServer: 1.4 Return payment creation response Including PayerMax Cashier URL MServer-->>Client: 1.4 Return response Client->>Checkout: 2.1 Redirect to PayerMax Cashier page %% 2. Payment Phase User->>Checkout: 3.1 Select payment method and submit payment Checkout->>PMServer: 3.2 Payment request PMServer->>Channel: 3.3 Payment request PMServer-->>Checkout: 3.4 Response Including PayerMax payment result URL Checkout->>Checkout: 3.5 Redirect to PayerMax payment result page %% 3. Return to Merchant User->>Checkout: 4.1 User clicks [Return to Merchant] Checkout-->>Client: 4.2 Redirect to merchant-specified page %% 4. Obtain Payment Result rect rgb(235, 245, 255) Note over MServer, PMServer: Obtain Payment Result Note over MServer, PMServer: Via Payment Result Notification PMServer->>MServer: 5.1 Asynchronous notification of payment result MServer->>MServer: 5.2 Update payment status MServer-->>PMServer: 5.3 Return response Note over MServer, PMServer: Via Payment Order Query MServer->>PMServer: 6.1 Query payment transaction PMServer-->>MServer: 6.2 Transaction details, including payment result MServer->>MServer: 6.3 Update payment status end ``` ## 2. API List | Associated Interaction Sequence | Call Direction | API PATH | | :--- | :--- | :--- | | 4.1 Create payment, call checkout order creation API | 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.4 Payment result asynchronous notification | PayerMax -> Merchant | [/collectResultNotifyUrl](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=cn#/paths/collectResultNotifyUrl/post) | | 4.4 Query payment transaction | Merchant -> PayerMax | [/orderQuery](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=cn#/paths/aggregate-pay-api-gateway-orderQuery/post) | ## 3. Environment Information - **Test environment request address**：https:// `pay-gate-uat.payermax.com`/aggregate-pay/api/gateway/ `` - **Production environment request address**：https:// `pay-gate.payermax.com`/aggregate-pay/api/gateway/ `` ## 4. Integration Steps ### 4.1 Create Payment Payments are created by calling the [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) interface and initiating an HTTP POST request. Under the Specific Payment Method integration mode, the PayerMax checkout page will selectively display a portion of the available payment methods based on the request input parameters. ::: 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 greater 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. ::: #### 4.1.1 Use non-CARD payment methods [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: ```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 '{ "version": "1.5", "keyVersion": "1", "requestTime": "2025-05-14T17:25:39.064+08:00", "appId": "test7e94124c208abbfc7e2792ecfa", "merchantNo": "TEST0114787283", "data": { "outTradeNo": "TEST39627390559111746827473769", "integrate": "Hosted_Checkout", "subject": "IDR 53,000", "totalAmount": "53000", "currency": "IDR", "country": "ID", "userId": "1177295", "frontCallbackUrl": "https://www.your.com", "notifyUrl": "https://middlepay.your.com/api_server/v2/finance/callback/order/TEST39627390559111746827473769", "paymentDetail": { "paymentMethodType": "WALLET", # Designated Payment Method "targetOrg": "", # Undesignated Payment Method } } }' ``` If you specify only the `paymentMethodType` but not the `targetOrg`, the PayerMax Cashier page will only show all the payment organizations under that payment method, but not the other payment methods. For example, if the payment country is Indonesia and the payment method is e-wallet, PayerMax Cashier page will show supported Indonesian e-wallets, such as DANA, OVO, GOPAY and so on. If `targetOrg` is specified as OVO at the same time, opening the returned link will directly redirect to the OVO wallet to complete the payment. [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 { "msg": "Success.", "code": "APPLY_SUCCESS", "data": { "redirectUrl": "https://cashier-n.payermax.com/v2/index.html#/payments?merchantId=TEST0114787283&merchantAppId=test7e94124c208abbfc7e2792ecfa&country=ID&tradeToken=T2019051409242877928306&paymentMode=WALLET&language=id&token=3acc37542e204765a6d11b86bf0bc930&amount=53000¤cy=IDR&version=1.4&cashierId=T2019051409242877928306&frontCallbackUrl=https%3A%2F%2Fwww.your.com&pmaxLinkV=1", "outTradeNo": "TEST39627390559111746827473769", "tradeToken": "T2019051409242877928306", "status": "PENDING" } } ``` #### 4.1.2 Use CARD payment methods [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: ```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 '{ "version": "1.5", "keyVersion": 1, "requestTime": "2025-05-14T16:30:27.174+08:00", "appId": "test516e8ab74578be8eecd8c4803fbe", "merchantNo": "TEST010117960578", "data": { "outTradeNo": "test5141630270627", "integrate": "Hosted_Checkout", "subject": "US $4.99 Stargem", "totalAmount": 4.99, "currency": "USD", "country": "US", "frontCallbackUrl": "https://pay.your.com/official_v2/redirect/web_payermax_web_v1", "userId": "test_1743900006925", "reference": "gp_huq_u", "notifyUrl": "https://pay.your.com/official_v2/notify/web_payermax_web_v1", "paymentDetail": { "paymentMethodType": "CARD", # Designated payment Methods "allowedCardOrg": [ # Specify the deck, which can be empty "MASTERCARD" ] } }' ``` If the merchant wants to limit the card brand that the user pays with, this can be done by setting the request entry `paymentDetail.allowedCardOrg`. As in the above example, if you specify the card brand as MASTERCARD, then when PayerMax renders the checkout page, it will only display payment organizations that support MASTERCARD. If `allowedCardOrg` is not specified, all contracted card brands will be displayed. [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 { "msg": "Success.", "code": "APPLY_SUCCESS", "data": { "redirectUrl": "https://cashier-n.payermax.com/v2/index.html#/payments?merchantId=TEST010117960578&merchantAppId=test516e8ab74578be8eecd8c4803fbe&orderNo=test5141630270627&country=US&tradeToken=T2019051408217377899667&paymentMode=CARD&targetOrg=*&token=acd8b556379140ee9a6ea067d6e68e35&amount=4.99¤cy=USD&version=1.4&cashierId=T2019051408217377899667&frontCallbackUrl=https%3A%2F%2Fpay.your.com%2Fofficial_v2%2Fredirect%2Fweb_payermax_web_v1&pmaxLinkV=1", "outTradeNo": "test5141630270627", # Merchant trade order number, consistent with outTradeNo in the request "tradeToken": "T2019051408217377899667", # PayermMax Transaction Number } } ``` ### 4.2 Jump to PayerMax checkout page [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` represents the PayerMax checkout page URL, and after receiving the response, the merchant can redirect to jump to the PayerMax checkout page, where the user completes the payment. ### 4.3 Jump to payment result page After the user completes the payment, the PayerMax Cashier page redirects to jump to the PayerMax Payment Results page.The PayerMax Payment Results page displays the results of the payment (as shown in the image below), and the page contains **Close** or **Back** button, when the user clicks on it, it jumps to the page `frontCallBackUrl` specified by the merchant. ![](https://img-cdn-sg.payermax.com/public/20250617-9bc6bb34-8c22-47e6-80a8-ab9935f7be5d.png) Merchants should ensure that the `frontCallBackUrl` they pass in is available to external browsers. The differences between the different `frontCallBackUrl` forms of the jump are as follows: | frontCallBackUrl form | Jump flow after payment completion | Recommended or Not | Advantages | Disadvantages | | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | ----------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | | Ordinaryh5 (http/https) | Stay in the system browser and display the H5 page | No | / | Does not have the ability to evoke an app | | Built-in active evoke APP logic h5 (http/https) | Display this H5 page, and at the same time, the logic within the page actively recognizes the scenario for merchant app evocation action, or stays on this page | Yes | Flexible logic and controlled processes | Complex development, to evoke the APP still need to use URL Scheme or AppLink/Universal Link | | URL Scheme (Customized scheme://) | The system automatically tries to evoke the APP specified by Scheme. If the APP exists and has permission, it can open the corresponding APP; If the APP does not exist or has no permission, it stays in the system browser and displays a blank page; | No | Easy to develop | No degradation logic, will show a blank page when APP is not evoked | | AppLink/Universal Link (http/https) | The system automatically tries to evoke the APP specified by Scheme. If the APP exists and has permission, it can open the corresponding APP; If the APP doesn't exist or doesn't have permission, it stays in the system browser and displays the content of the degraded H5 page | Yes | Development logic is relatively simple, can be downgraded to use H5 to deal with business logic | | The URL back to Merchant consists of two parts, the first part is the[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) `frontCallbackUrl`of the interface request,the second part is the extra parameters attached to PayerMax. Below is a complete example of a jump URL: ![](https://img-cdn-sg.payermax.com/public/20250702-7ba2c515-5e5c-4fb0-89b4-429712872124.png) The additional parameters attached to PayerMax include: - `outTradeNo`：Merchant Order Number; - `tradeToken`：PayerMax order number; - `status`：Order Status. In particular, please do not use this value to update the merchant order status directly, you should follow Step 4: Get Payment Result as the basis for processing as a way to ensure the accuracy of the transaction status. ### 4.4 Get Payment Result #### 4.4.1 Payment Result Notification See [Get Payment Result Integration - Payment Result Notification](https://docs.payermax.com/en/202606-version/acquiring/start-integration/related-capabilities-integration/payment-result.md#_3-1-payment-result-notification). #### 4.4.2 Payment Result Inquiry See [Get Payment Result Integration - Payment Result Inquiry](https://docs.payermax.com/en/202606-version/acquiring/start-integration/related-capabilities-integration/payment-result.md#_3-2-payment-result-inquiry).