Refund Integration

This document describes the refund integration process.

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.

2. Interaction Process

3. Interface List

Associative Interaction Timing	Calling direction	Interface PATH
2.2 & 2.3 Initiate a Refund	Merchant -> PayerMax	/refund
3.1 Refund result notification	PayerMax -> Merchant	/refundResultNotifyUrl
4.1 Check refund transactions	Merchant -> PayerMax	/refundQuery

4. Integration Steps

4.1 Initiate a Refund

After the user successfully pays, the merchant can initiate a refund through the Refund Application API interface or through the PayerMax Merchant Platform（MMC）.

The order must meet the following conditions to successfully initiate a refund:

• The payment has been successful;

• Not in the refund process;

• The refund has not been successful;

• Within 365 days after the order payment is successful;

• The merchant account balance is sufficient to pay the refund. PayerMax will deduct the refund amount from your pending settlement account (pending settlement amount). If the amount in the pending settlement account (pending settlement amount) is insufficient, it will return REFUND_INSUFFICIENT_BALANCE. After receiving this error code, please wait for a successful payment transaction and initiate it again;

• If a refund is initiated through the merchant platform, please confirm whether the initiator has the authority to apply for a refund.

If you still want to initiate a refund even though the refund conditions are not met, we recommend that you use the PayerMax Payout Service to process a refund.

After the refund application is successful, the refund amount will be returned to the user's account according to the original transaction method. For example: if the user pays through Paytm Wallet, after the refund is successful, the amount will be returned to the user's Paytm Wallet account.

Note:

The refund amount will usually be returned to the user's bank account within 21 days. However, due to channel restrictions, the actual arrival time may vary from bank to bank.

4.1.1 Refunds through the Merchant Platform

After the merchant activates PayerMax Merchant Platform (MMC), he can log in to PayerMax Merchant Platform (MMC), enter Payment → Order Search, search for the transaction order that needs to be refunded, enter the details page of the order, and click the Initiate a Refund button.

Merchants can set up refund application approval as needed. If the refund approval function is not set, after the refund application is initiated, no approval is required and the refund process is executed directly. If you need to activate the refund approval function, please refer to How to enable the refund approval function.

For orders that have been rejected or failed to be refunded, you can apply for a refund again as long as they are within the refund validity period.

4.1.2 Refunds via the Refund API

Interface request example of Refund Application /refund API:

curl --request POST \
  --url https://pay-gate-uat.payermax.com/aggregate-pay/api/gateway/refund \
  --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-17T09:20:54.047+00:00",
  "appId": "3b242b56a8b64274bcc37dac281120e3",
  "merchantNo": "020213827212251",
  "data": {
    "outRefundNo": "R1642411016202", # Merchant refund order number
    "refundAmount": 10000,
    "refundCurrency": "IDR",
    "outTradeNo": "P1642410680681", # The merchant order number to be refunded
    "tradeToken": "T2025020713159038685354",
    "comments": "20220117070423TI408900055079",
    "refundNotifyUrl": "https://www.payermax.com" # Refund result callback notification interface
  }
}'

Interface response example of Refund Application /refund API:

{
  "code": "APPLY_SUCCESS",
  "msg": "",
  "data": {
    "outRefundNo": "R1642411016202",
    "tradeOrderNo": "20220117091121TI366100056090",
    "refundTradeNo": "20220117091657TI790000055087",
    "status": "REFUND_PENDING"
  }
}

4.2 Get Refund Results

After PayerMax successfully accepts the application, it will initiate a refund request to the bank or institution, and synchronize the merchant's refund status through Callback Notification API. The refund status is as follows:

Refund Status	Description	Remark
REFUND_SUCCESS	Refund successful	A successful refund only means that the channel has successfully accepted the refund application. The specific arrival time varies due to channel restrictions. After you successfully initiate a refund application, the refund amount is expected to be returned to the user's bank account within 21 days. Due to channel constraints, the refund status is only for checking whether the acceptance is successful. It does not currently support querying the actual status of the refund funds processing. However, each channel generally follows the following rules to process refunds: 1. After the refund request is successfully accepted, the funds will be returned to the user's bank card or account used for payment within 1-21 days. 2. If a customer complaint occurs, the merchant can respond to the user according to the above statement. If the refund on the user side is not processed within the effective time, you can contact PayerMax for after-sales support.
REFUND_PENDING	Refund in progress
REFUND_FAILED	Refund failed

4.1.1 Notification of refund results

After a successful refund, PayerMax will proactively call back the callback address specified by the merchant and initiate Result Notifications API. PayerMax may call back to notify the merchant multiple times until receiving a successful response from the merchant.

Merchants can set the refund result callback address in two ways:

1. Specify through interface parameters: When applying for a refund, set the request input parameter refundNotifyUrl of Refund Application /refund API . This configuration is only effective for a single payment and can override the global configuration.

2. Configure through the merchant platform: Configure a unified refund result callback address through the PayerMax merchant platform. For specific configuration methods, see Integration Guide - Configure integration information for the test environment. This configuration is effective for all refund applications.

Interface request example of Result Notifications /refundResultNotifyUrl API:

curl --request POST \
  --url https://pay-gate-uat.payermax.com/RefundResultNotifyUrl \
  --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": "Success.",
  "keyVersion": "1",
  "appId": "3b242b56a8b64274bcc37dac281120e3",
  "merchantNo": "020213827212251",
  "notifyTime": "2022-01-17T09:33:54.540+00:00",
  "notifyType": "REFUND",
  "data": {
    "outRefundNo": "R1642411016202",
    "refundTradeNo": "20220117091657TI790000055087",
    "outTradeNo": "P1642410680681",
    "refundAmount": 10000,
    "refundCurrency": "IDR",
    "refundFinishTime": "2023-10-20T03:28:23.092Z",
    "status": "REFUND_SUCCESS"
  }
}'

Merchants can use data.status to determine the refund status. Please do not use code or msg to determine the refund status.

Interface response example of Result Notifications /refundResultNotifyUrl API:

{
  "code": "SUCCESS",
  "msg": "Success"
}

After receiving the refund 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 refund result notification with a notification frequency of 0s/30s/300s/600s/3600s/43200s, and a maximum of 6 times.

If the refund status is unclear or the merchant has not received a refund result notification from PayerMax, merchant could query through refund transaction to get the refund result.

Special reminder:

For refunds initiated through the merchant platform, PayerMax will not initiate a refund result callback notification to the merchant by default. If you need to activate it, please contact the PayerMax technical support team.

4.1.2 Query Through Refund Transaction

Merchants can also call Transaction Inquiry /orderQuery API interface to get payment results.

Interface request example of Transaction Inquiry /orderQuery API:

curl --request POST \
  --url https://pay-gate-uat.payermax.com/aggregate-pay/api/gateway/refundQuery \
  --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:01:23.737+00:00",
  "appId": "a0dddd1f622243cb9aa1b676e808b5f8",
  "merchantNo": "02021382719993",
  "data": {
    "outRefundNo": "R1642411016202"
  }
}'

Interface response example of Transaction Inquiry /orderQuery API:

{
  "code": "APPLY_SUCCESS",
  "msg": "",
  "data": {
    "outRefundNo": "R1642411016202",
    "refundTradeNo": "20220117091657TI790000055087",
    "totalAmount": 10000,
    "refundCurrency": "IDR",
    "outTradeNo": "P1642410680681",
    "status": "REFUND_SUCCESS",
    "refundFinishTime": "2023-10-20T03:28:23.092Z",
    "resultMsg": "Success"
  }
}

Merchants can use code to determine whether the refund query is successful or not, and use data.status to further determine the refund status. Please do not use code, msg or data.resultMsg to determine the refund status.

4.1.3 Through Merchant Platform

Regardless of the method used to initiate a refund, merchants can log in to the PayerMax Merchant Platform (MMC) and check the refund results and progress through Payment → Refund Search.

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.