Get Payment Result

1. Interaction Process

%%{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
2.1 Payment Transaction Inquiry	Merchant -> PayerMax	/orderQuery

3. Get Payment Result

When an order reaches a final state, PayerMax will synchronize the payment status to the merchant via Payment Result Notification. 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 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 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", // 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 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.

-- 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 Query Payment Result

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 No.
  }
}'

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&timestamp=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).