# Get Payment Result ## 1. 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 Client as Merchant participant PM as PayerMax %% 1. Initial Notification PM->>Client: 1.1 Payment result notification Client->>PM: 1.2 Response result %% 2. Retransmission Logic rect rgb(235, 245, 255) Note over Client, PM: Retransmit Payment Result Note right of Client: If Merchant Response Code is NOT "SUCCESS" PM->>Client: 1.3 Retransmit payment result end %% 3. Active Query Client->>PM: 2.1 Query payment order PM-->>Client: 2.2 Return payment order details ``` ## 2. Interface List | Associative Interaction Timing | Calling direction | Interface PATH | | ------------------------------- | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- | | 1.1 Payment result notification | `PayerMax` -> `Merchant` | [/collectResultNotifyUrl](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=cn#/paths/collectResultNotifyUrl/post) | | 2.1 Payment Transaction Inquiry | `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. Get Payment Result When an order reaches a final state, PayerMax will synchronize the payment status to the merchant via [Payment Result Notification](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=cn#/paths/collectResultNotifyUrl/post). Merchants can also proactively query the payment status. The payment statuses are as follows: | 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 | ### 3.1 Payment Result Notification Merchants can set the payment result callback address in two ways: - Specify via interface parameters: When creating a payment, set the `notifyUrl` parameter in the [/orderAndPayAPI](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=cn#/paths/aggregate-pay-api-gateway-orderAndPay/post) request. This configuration only takes effect for a single payment and overrides the merchant platform configuration. - Configure via the merchant platform: Configure a unified payment callback URL via the PayerMax Merchant Platform: **Service Settings** → **Development Configuration**. This configuration takes effect for all payment transactions. [Payment Result Notification API](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=cn#/paths/collectResultNotifyUrl/post) request example: ``` json 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", // Determine the payment status via `data.status` "completeTime": "2023-10-20T03:28:23.092Z", "paymentDetails": [ { "paymentMethodType": "WALLET", "targetOrg": "DANA", "paymentTokenID": "PMTOKEN20230710080439571142400031000" } ], "reference": "020213827524152" } }' ``` [Payment result notification API](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=cn#/paths/collectResultNotifyUrl/post) Response example: > Upon receiving the notification, please respond according to the example. If there is no response or an incorrect response, PayerMax will retry 6 times; > Since an incorrect response will trigger an online exception alarm, if the response is incorrect over a long period, the system may mute your alarm function, at which point the alarm will become completely invalid. ``` json -- Successful response { "msg": "Success", "code": "SUCCESS" // PayerMax relies on the "code" to determine if the notification was successful. If it is not "SUCCESS", it is deemed a failure, and PayerMax will resend the notification. } ``` ### 3.2 Payment Result Inquiry [Transaction inquiry/orderQuery API](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=cn#/paths/aggregate-pay-api-gateway-orderQuery/post) Interface request example: ``` json 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 No. } }' ``` [Transaction inquiry/orderQuery API](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=cn#/paths/aggregate-pay-api-gateway-orderQuery/post) Interface response example: ``` json { "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": "" } } ``` ## 4. FAQ **1. Repeatedly Receiving Notifications** If the merchant does not respond or the response fails (the code is not `SUCCESS`), PayerMax will resend the payment result notification. The notification frequency is `0s/30s/300s/600s/3600s/43200s`, with a maximum of `6 retries`. **2. Under what circumstances will PayerMax send a callback?** A callback will be sent when the payment reaches its final state (Success/Failed/Closed).