Refund Integration

PayerMax supports initiating refunds via both the Merchant Portal and API.

1. Refund Prerequisites (General Conditions)

The following conditions must be met for an order to successfully initiate a refund:

• The payment method supports refunds.
• The order status is Payment Successful.
• The order is not currently undergoing another refund process.
• The refund amount is less than or equal to the refundable amount of the order.
• The application time is within 180 days after the successful payment.
• The pending settlement balance is sufficient (PayerMax will deduct the refund amount from the pending settlement; if insufficient, it will return REFUND_INSUFFICIENT_BALANCE).
• (Merchant Portal Refund) The operator has been granted refund permissions.

2. Merchant Portal Refund

1. Log in to the Merchant Portal.
2. Go to Acquiring Product → Order Query.
3. Find the target order, enter the details page, click the Refund button, and follow the process to complete the subsequent steps.

3. Refund via API

3.1 Interaction Flow

%%{init: {
  'theme': 'base',
  'themeVariables': {
    'primaryColor': '#e6f0ff',
    'primaryTextColor': '#333',
    'primaryBorderColor': '#5b9bd5',
    'lineColor': '#888',
    'actorMargin': 40,
    'noteBkgColor': '#0056b3',
    'noteTextColor': '#ffffff',
    'noteBorderColor': '#004a99'
  }
}}%%
sequenceDiagram
    participant User as User
    participant Client as Merchant Side
    participant PayerMax as PayerMax
    participant Channel as Payment Channel
Wallet/Bank, etc.

    %% 1. Request Refund
    User->>Client: 1.1 Request refund

    %% 2. Initiate Refund Logic Box
    rect rgb(235, 245, 255)
        Note over Client, PayerMax: Initiate Refund
        
        Note over Client, PayerMax: Via PayerMax Merchant Portal
        Client->>PayerMax: 2.1 Log in to PayerMax Merchant Portal
        Client->>PayerMax: 2.2 Select order and initiate refund

        Note over Client, PayerMax: Via Refund API
        Client->>PayerMax: 2.3 Call refund request API to initiate refund
    end

    %% 3. Channel Processing
    PayerMax->>Channel: 2.4 Refund request
    Channel-->>PayerMax: 2.5 Refund request response

    %% 4. Refund Result Logic Box
    rect rgb(235, 245, 255)
        Note over Client, PayerMax: Obtain Refund Result
        
        Note over Client, PayerMax: Via Refund Result Notification
        PayerMax->>Client: 3.1 Refund result notification
        Client->>PayerMax: 3.2 Refund notification response

        Note over Client, PayerMax: Via Refund Transaction Query
        Client->>PayerMax: 4.1 Call refund transaction query
        PayerMax-->>Client: 4.2 Return refund details
    end

3.2 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

3.3 Initiate Refund

Refund Application /refund API Request Example:

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

3.4 Get Refund Results

Once PayerMax successfully accepts the refund, it will initiate a refund request to the channel via the original payment path, and synchronize the merchant's refund status through the Refund Notification. Merchants can also actively query to obtain the refund status. The refund statuses are as follows:

Refund Status	Description
REFUND_SUCCESS	Refund successful
REFUND_PENDING	Refund pending
REFUND_FAILED	Refund failed

3.4.1 Refund Notification

Once the refund reaches its final state, PayerMax will actively notify the callback address specified by the merchant and initiate a Refund Notification. PayerMax may send callback notifications multiple times until a successful response is received from the merchant.

The refund result callback address can be configured in two ways:

1. Specify via API parameters: When applying for a refund, set the request input parameter refundNotifyUrl in the Refund Application /refund API. This configuration only takes effect for a single payment and can override the Merchant Portal configuration.

2. Configure via the Merchant Portal: Configure a unified refund result callback address through the PayerMax Merchant Portal. For specific configuration methods, please refer to Integration Guide - Configure Integration Information for the Test Environment. This configuration applies to all refund applications.

Please note that the refund status should be determined by data.status. Do not use code or msg to determine the refund status.

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" //Please note that the refund status should be determined by data.status. Do not use code or msg to determine the refund status.
  }
}'

Interface response example of Result Notifications /refundResultNotifyUrl API:

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

3.4.2 Refund Inquiry

Interface request example of Refund Inquiry /refundQuery 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 Refund Inquiry /refundQuery API:

{
  "code": "APPLY_SUCCESS",
  "msg": "",
  "data": {
    "outRefundNo": "R1642411016202",
    "refundTradeNo": "20220117091657TI790000055087",
    "totalAmount": 10000,
    "refundCurrency": "IDR",
    "outTradeNo": "P1642410680681",
    "status": "REFUND_SUCCESS", //Please note that the refund status should be determined by data.status. Do not use code or msg to determine the refund status.
    "refundFinishTime": "2023-10-20T03:28:23.092Z",
    "resultMsg": "Success"
  }
}

4. FAQ

1. Will refunds initiated via the Merchant Portal trigger callback notifications?

By default, refunds initiated from the Merchant Portal will not trigger callback notifications. If you need to enable this, you can Submit a Ticket to contact PayerMax staff for configuration.

2. Will refunds initiated via API be recorded on the Merchant Portal?

Regardless of how the refund is initiated, merchants can log in to the PayerMax Merchant Portal and go to Acquiring Product → Refund Query to check the refund results and progress.

3. Does the Merchant Portal support a refund approval workflow?

Refund transactions initiated through the Merchant Portal support setting up a refund approval workflow. Please refer to the document How to Enable Payout/Refund Approval Process.

4. Does a successful refund status mean the user has received the funds?

A successful refund only indicates that the channel provider has successfully accepted the refund application. The actual time of arrival varies depending on channel restrictions.

5. Refund Arrival Timeframe

Once you have successfully initiated a refund application, the refund amount is expected to be returned to the user via the original payment path within 21 days.

6. How to track the actual fund flow after a successful refund?

Due to channel constraints, the refund status can only be used to check whether the application was successfully accepted; tracking the actual real-time status of the refund fund processing is currently not supported. However, various channels generally process refunds according to the following rules:

1. After the refund request is successfully accepted, the funds will be returned to the user via the original path within 21 days.

2. In case of customer complaints, the merchant can respond to the user based on the timeframe mentioned above. If the refund is not received on the user's end within the effective timeframe, you can Submit a Ticket to reach out to PayerMax staff for support.