Get Payment Result Integration
This document describes the integration process for obtaining payment results.
1. Integration Preparation
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;
Understand the principles of request message signing and verification, for generating a
sign
signature string for each HTTP request Header.If the merchant server has restrictions on access to external IP addresses, you need to add the PayerMax server IP address to the whitelist of the merchant server, please consult PayerMax technical support for production and test environment IP addresses.
2. Interaction Process
3. Interface List
Associative Interaction Timing | Calling direction | Interface PATH |
1.1 Payment result notification | PayerMax -> Merchant | /collectResultNotifyUrl |
2.1 Payment Transaction Inquiry | Merchant -> PayerMax | /orderQuery |
4. Integration Steps
PayerMax supports two ways to get payment results. Payment result states include the following:
Status | Description | Notes |
SUCCESS | Transaction Successful | User Payment Successful |
PENDING | Transaction Processing | Waiting for User to Complete Payment |
FAILED | Transaction Failed | Payment Failed |
CLOSED | Transaction Close | User has not completed payment within the validity period |
4.1 Adoption of Payment Result Notification
After the payment is completed, PayerMax will initiate a callback to the callback address specified by the merchant to initiate a notification of the payment result API .PayerMax may make multiple callbacks to notify the merchant until it receives a successful response from the merchant.
Merchants can set the payment result callback address in two ways:
Specified via interface parameter: set the request /orderAndPay API entry
notifyUrl
when creating a payment. This configuration only takes effect for a single payment and can override the global configuration.Configuration through the merchant platform: Configure the unified payment callback result address through PayerMax merchant platform. This configuration is effective for all payment transactions.
Payment result notification API Request example:
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 '{
"code": "APPLY_SUCCESS",
"msg": "",
"keyVersion": "1",
"appId": "3b242b56a8b64274bcc37dac281120e3",
"merchantNo": "020213827212251",
"notifyTime": "2022-01-17T09:33:54.540+00:00",
"notifyType": "PAYMENT",
"data": {
"outTradeNo": "P1642410680681",
"tradeToken": "T2024062702289232000001",
"totalAmount": 10000,
"currency": "IDR",
"country": "ID",
"status": "SUCCESS",
"completeTime": "2023-10-20T03:28:23.092Z",
"paymentDetails": [
{
"paymentMethodType": "WALLET",
"targetOrg": "DANA",
"paymentTokenID": "PMTOKEN20230710080439571142400031000"
}
],
"reference": "020213827524152"
}
}'
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
Merchants can determine the refund status through data.status
.
Payment result notification API Response example:
-- Response successful
{
"msg": "Success",
"code": "SUCCESS" # PayerMax relies on the code to determine whether the notification is successful. If it is not SUCCESS, the notification is considered to have failed and PayerMax will resend it.
}
2
3
4
5
After receiving the payment result notification, the merchant can return success or failure. If the merchant does not respond or fails to respond, PayerMax will try to resend the payment result notification with a notification frequency of 0s/30s/300s/600s/3600s/43200s
, and a maximum of 6 times
.
When the order status is unclear or the merchant has not received the payment result notification from PayerMax, the merchant can proactively inquiry via payment order , get the payment result.
4.2 Inquiry via payment order
Merchants can also obtain payment results by transaction query/orderQuery API interface.
Transaction inquiry/orderQuery API Interface request example:
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": "a0dddd1f622243cb9aa1b676e808b5f8",
"merchantNo": "02021382719993",
"data": {
"outTradeNo": "P1642410680681" # Merchant order number
}
}'
2
3
4
5
6
7
8
9
10
11
12
13
14
15
Transaction inquiry/orderQuery API Interface response example:
{
"msg": "Success.",
"code": "APPLY_SUCCESS",
"data": {
"reference": "reference查询和回调返回",
"country": "SA",
"totalAmount": 10,
"outTradeNo": "DEVTest1669616467952",
"currency": "SAR",
"channelNo": "DMCP000000000177005",
"thirdChannelNo": "4ikqJ6ktEqyRawE1dvqb9c",
"paymentCode": "2312121212",
"tradeToken": "T2024062702289232000001",
"completeTime": "2023-10-20T03:28:23.092Z",
"paymentDetails": [
{
"targetOrg": "*",
"cardInfo": {
"cardOrg": "VISA",
"country": "SA",
"cardIdentifierNo": "400555******0001",
"cardIdentifierName": "**ngwei"
},
"payAmount": 10,
"exchangeRate": "1",
"paymentMethod": "CARD",
"payCurrency": "SAR",
"paymentMethodType": "CARD"
}
],
"fees": {
"merFee": {
"url": "https://cashier-n-test-new.payermax.com/static/invoice.html?country=AE&merchantNo=P01010113843429×tamp=1687769788704&version=1.0&orderTaxToken=XWXFKKBOPExplK4aX0r7wgiMtiAMLBKObPFdCMpM9HmCq3AAOob%252BcAZOkP27Kh3W",
"amount": "100",
"currency": "SAR"
}
},
"status": "SUCCESS",
"resultMsg": ""
}
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
Merchants can use the code
in the request response to determine whether the query request is successful, and use data.status
to further determine the refund status. Please do not use code
, msg
or data.resultMsg
to determine the refund status.
5. 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.
6. 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.