Cashier Payment Integration

This document describes the integration process of the cashier integration mode.

In the cashier integration mode, after placing an order, the user jumps to the H5 cashier page built by PayerMax to pay for the order. the PayerMax H5 cashier page displays a list of optional payment methods, and supports adaptive device screen size, multi-language, and other features. With this integration mode, merchants do not need to develop a cashier page, which greatly simplifies merchant integration and shortens the go-live cycle.

For more information about the cashier integration mode, please refer to Overview of Integration Modes.

1. Integration Preparation

Register 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.3 Create a payment, call the cashier's order interface	`Merchant` -> `PayerMax`	/orderAndPay
5.1 Payment result asynchronous notification	`PayerMax` -> `Merchant`	/collectResultNotifyUrl
6.1 Querying Payment Transactions	`Merchant` -> `PayerMax`	/orderQuery

4. Environmental Information

Test environment request address：https:// pay-gate-uat.payermax.com/aggregate-pay/api/gateway/ <Interface PATH>
Production environment request address：https:// pay-gate.payermax.com/aggregate-pay/api/gateway/ <Interface PATH>

5. Integration Steps

5.1 Create Payment

Payments are created by calling the Create Payment/OrderAndPay API interface and initiating an HTTP POST request.PayerMax Cashier Integration Mode supports merchants to customize the available payment methods for users to choose from. If the merchant does not specify the payment method, the full amount of payment methods will be displayed by default, and the user interaction interface will display the referral link; if the merchant specifies the payment method, PayerMax cashier page will selectively display some of the available payment methods according to the request entry settings, and the user interaction interface will display in Cashier Payment Introduction.

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.

5.1.1 Use all payment methods

Create Payment/orderAndPay API example of an interface request:

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-14T06:29:50.085+00:00",
    "appId": "testb427ca0ef77d19bd25c83",
    "merchantNo": "TEST081764",
    "data": {
        "outTradeNo": "PTEST93137249",
        "subject": "diamond 700",
        "totalAmount": 3.99,
        "currency": "USD",
        "country": "US",
        "userId": "1800110891",
        "language": "en", # Specify the language of the PayerMax checkout page display
        "frontCallbackUrl": "https://your-payment.33t8y678tyy6rt.top/payment/front_callback?flag=ipaMbjQuest", # Merchant page that jumps after the user completes payment
        "notifyUrl": "https://your-payment.33t8y678tyy6rt.top/payment/payment_callback", # Payment result callback notification URL, if not specified, the payment result callback notification address configured by the merchant in the PayerMax Merchant Platform is used by default
        "reference": "your special info", # Customize the additional data and PayerMax will return this information to the merchant during the payment result callback     
        "integrate": "Hosted_Checkout",
        "expireTime": "1200" # Set the expiration time of this payment to 1200 seconds, i.e., if the user does not complete the payment within 20 minutes, the PayerMax system closes the order and determines that the payment has failed
    }
}'

If a merchant does not want to pass notifyUrl every time they make a payment, they can configure a unified payment callback result address through the PayerMax Merchant Platform.

Create Payment/orderAndPay API example of an interface request:

json

{
    "msg": "Success.",
    "code": "APPLY_SUCCESS",
    "data": {
        "redirectUrl": "https://cashier-n.payermax.com/v2/index.html#/payments?merchantId=TEST081764&merchantAppId=testb427ca0ef77d19bd25c83&country=US&tradeToken=T2019051406423972799219&language=en&token=358746abf4754e1cba682d1391336734&amount=3.99&currency=USD&version=1.4&cashierId=T2019051406423972799219&frontCallbackUrl=https%3A%2F%2Fyour-payment.33t8y678tyy6rt.top%2Fpayment%2Ffront_callback%3Fflag%3DipaMbjQuest&pmaxLinkV=1",
        "outTradeNo": "PTEST93137249",
        "tradeToken": "T2019051406423972799219",
        "status": "PENDING"
    }
}

5.1.2 Use non-CARD payment methods

Create Payment/orderAndPay API example of an interface request:

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-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 payment method but not the payment organization, 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.

Create Payment/orderAndPay API 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&currency=IDR&version=1.4&cashierId=T2019051409242877928306&frontCallbackUrl=https%3A%2F%2Fwww.your.com&pmaxLinkV=1",
        "outTradeNo": "TEST39627390559111746827473769",
        "tradeToken": "T2019051409242877928306",
        "status": "PENDING"
    }
}

5.1.3 Use non-CARD payment organizations

Create Payment/orderAndPay API example of an interface request:

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 '{
    "merchantNo": "TEST894366",
    "version": "1.4",
    "keyVersion": "1",
    "requestTime": "2025-05-14T06:30:02.844Z",
    "appId": "testf64019bf1e63ee3fb364c5",
    "data": {
        "outTradeNo": "test_3934784",
        "integrate": "Hosted_Checkout",
        "userId": "test34784",
        "subject": "Number of Coins8200",
        "country": "PH",
        "currency": "USD",
        "totalAmount": "1.00",
        "frontCallbackUrl": "https://your-pay.vshowapi.com/payUrl/return/1747204201786_3934784",
        "expireTime": "1800",
        "reference": "payermax",
        "language": "en",
        "paymentDetail": {
            "paymentMethodType": "WALLET", # Designated Payment Method
            "targetOrg": "GCASH" # Undesignated Payment Method
        },
        "notifyUrl": "https://your-pay.vshowapi.com/callback/payermax",
        "terminalType": "WAP"
    }
}'

Create Payment/orderAndPay API example of an interface request:

json

{
    "msg": "Success.",
    "code": "APPLY_SUCCESS",
    "data": {
        "redirectUrl": "https://cashier-n.payermax.com/static/processing.html?merchantId=TEST894366&merchantAppId=testf64019bf1e63ee3fb364c5&tradeToken=T2019051406661275799086&country=PH&language=tl&token=0f5444f8f4b045a38f20632575498637&version=1.4&paymentMode=WALLET&targetOrg=GCASH&cashierRequestNo=T202505140666127579908620250514063002952415488&cashierId=T2019051406661275799086&orderLan=tl&countryLan=tl&strategyLan=LUBCO&pmaxLinkV=1",
        "outTradeNo": "test_3934784",
        "tradeToken": "T2019051406661275799086",
        "status": "PENDING"
    }
}

5.1.4 Use CARD payment methods

Create Payment/orderAndPay API example of an interface request:

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

Create Payment/orderAndPay API 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&currency=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
    }
}

5.2 Jump to PayerMax checkout page

Create Payment/orderAndPay API 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.

5.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.

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 theCreate Payment/orderAndPay API frontCallbackUrlof the interface request,the second part is the extra parameters attached to PayerMax. Below is a complete example of a jump URL:

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.

5.4 Get Payment Results

5.4.1 Adoption of notification of payment results

See Get Payment Result Integration - Adoption of Payment Result Notification.

5.4.2 Inquiry via Payment Orders

See Get Payment Result Integration - Inquiry via payment order.

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

Acquiring Basic Products

CARD

GOOGLEPAY

APPLEPAY

Subscription and Autp Debit

Drop In

Tokenization

Auth-Capture

ChargeBack

Risk Control

Troubleshooting

API Disbursement

Payment Method List

Europe

Cashier Payment Integration ​

1. Integration Preparation ​

2. Interaction Process ​

3. Interface List ​

4. Environmental Information ​

5. Integration Steps ​

5.1 Create Payment ​

5.1.1 Use all payment methods ​

5.1.2 Use non-CARD payment methods ​

5.1.3 Use non-CARD payment organizations ​

5.1.4 Use CARD payment methods ​

5.2 Jump to PayerMax checkout page ​

5.3 Jump to payment result page ​

5.4 Get Payment Results ​

5.4.1 Adoption of notification of payment results ​

5.4.2 Inquiry via Payment Orders ​

6. Test Go Live ​

7. Troubleshooting ​

Cashier Payment Integration

1. Integration Preparation

2. Interaction Process

3. Interface List

4. Environmental Information

5. Integration Steps

5.1 Create Payment

5.1.1 Use all payment methods

5.1.2 Use non-CARD payment methods

5.1.3 Use non-CARD payment organizations

5.1.4 Use CARD payment methods

5.2 Jump to PayerMax checkout page

5.3 Jump to payment result page

5.4 Get Payment Results

5.4.1 Adoption of notification of payment results

5.4.2 Inquiry via Payment Orders

6. Test Go Live

7. Troubleshooting