Notification / Notification of Refund Result

Scenario

When a refund occurs for an order of pickup vouchers during the fund custody period, ECPay will proactively send refund notifications at scheduled intervals daily. Upon receiving the proactive refund notification from ECPay, the merchant should respond promptly and accurately to acknowledge the receipt of the message.

Step 1. ECPay：
Send refund notification messages to the platform merchant or merchant’s designated server URL(RefundNotifyURL) via ServerPost method.
Step 2. Platform merchant / Merchant：
Receive the proactive refund notification message from ECPay and verify if the checksum matches.
Step 3. Platform merchant / Merchant：
After verifying that the checksum matches, please respond with RtnCode 1.

Special Note:

The platform merchant/store’s provided [RefundNotifyURL] domain needs to be applied and opened in advance with ECPay for firewall access.
If the response is not correctly acknowledged (RtnCode=1), the system will resend the message to the platform merchant/merchant after a 5 to 15-minute interval. This process will be repeated up to four times within the same day.
If the platform merchant/merchant continues to receive proactive refund notifications from ECPay, please check if they have not responded correctly (RtnCode=1) to ECPay.
You can also use the “Query Order Refund Information API” to check the refund status of an order.

Message format

Accept：text/html
Content Type：application/json
HTTP Method：POST

Request (JSON format)

PlatformID String(10)

Platform ID

This is used by platform merchants and will be provided by ECPay.
For platform merchants, please populate with [MerchantID].
For general merchants, please set as null.

MerchantID String(10)
Required

Merchant ID (provided by ECPay)

RqHeader Object
Required

Request header

Timestamp Number
Required

Please convert the transmission time to a timestamp (GMT+8). ECPay will use this parameter to convert the current time to Unix Timestamp and verify the time interval of this API call.

Special Note：

ECPay will verify the timestamp.If ECPay receives the request is more 10 minutes late than the timestamp, the transaction will be failed.
Merchants are suggested to synchronize the time of a computer on client- or server-side to another server or nearest reference time source.
For more details can be seen here; another online tool can be found here.

Data Object
Required

Payload of JSON that has been encrypted.

CheckMacValue String
Required

Checksum

Please refer to the Appendix Checksum Mechanism.

Request Example (JSON format)

				
					{
    "PlatformID": "3002599",
    "MerchantID": "2000132",
    "RqHeader": {
        "Timestamp": 1525168923
    },
    "Data": "…",
    "CheckMacValue": "…"
}

Message payload of Data (JSON format)

Special Note: Please urlencode the JSON string firstly and then do AES encryption.

MerchantID String(10)

Merchant ID (provided by ECPay)

MerchantTradeNo String(25)

Transaction ID (provided by the merchant).

TradeAmount Int

Order Amount

TotalRefundAmount Int

The total refunded amount for this order, excluding the current refund amount.

RefundAmount Int

The refund amount for this transaction.

Data Example (JSON format)

				
					{
    "MerchantID": "2000132",
    "MerchantTradeNo":"CBX20220302153064851",
    "TradeAmount":1000,
    "TotalRefundAmount":500,
    "RefundAmount":200  
}

Response (JSON format)

PlatformID String(10)

Platform ID

MerchantID String(10)

Merchant ID

RpHeader Object

Response header

Timestamp Number

Unix timestamp

TransCode Int

Response codes to indicate whether the payload is successfully accepted.

1: Payload (i.e. MerchantID, RqHeader, and Data) is successfully accepted by ECPay.
Others: failed.

TransMsg String(200)

Response message to indicate whether the payload is successfully accepted.

Data String

Payload of JSON that has been encrypted.

CheckMacValue String

Checksum

Please refer to the Appendix Checksum Mechanism.

Response Example (JSON format)

				
					{
    "PlatformID": "3002599",
    "MerchantID": "2000132",
    "RpHeader": {
        "Timestamp": 1525169058
    },
    "TransCode": 1,
    "TransMsg": "",
    "Data": "…",
    "CheckMacValue": "…"  
}

Message payload of Data (JSON format)

RtnCode Int

Response codes to indicate whether the API is successfully executed or not.

1: API is successfully executed.
Others: failed.
For more details please see error codes.

RtnMsg String(200)

Response messages.

Data Example(JSON format)

				
					{
    "RtnCode": 1,
    "RtnMsg": "Success"
}

Special Note:

The refunded amount refers to the funds that have been uploaded to the funds custody system and confirmed by the bank.
Due to the bank’s operational schedule, the refund notification will be sent as follows:

- If the issue date is the same as the refund date
  The refund notification will be sent after 02:00 on the day following the issue date plus two days.
  For example, if the ticket is issued on July 1st at 10:00 and returned on the same day at 15:00, the refund notification will be scheduled to be sent after 02:00 on July 3rd.
- If the ticket issue date is different from the refund date
  The refund notification will be sent after 02:00 on the day following the refund day.
  For example, if the ticket is issued on July 1st at 10:00 and returned on July 5th at 21:00, the refund notification will be scheduled to be sent after 02:00 on July 6th.

Green World