Get Payment Result Integration

This document describes the integration process for obtaining payment results.

1. Integration Preparation

• Interface registration 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.

• 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:

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

2. 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"
  }
}'

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

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

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": ""
  }
}

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.