Scenario
Upon the completion of an order return or ticket redemption, ECPay will proactively send a daily notification at a scheduled time. The merchant should promptly and accurately acknowledge receipt of this notification upon receiving it from ECPay.
- Step 1. ECPay：Send notification messages to the platform merchant or merchant’s designated server URL(UseStatusNotifyURL) via ServerPost method.
- Step 2. Platform merchant / Merchant：Receive the proactive 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 [UseStatusNotifyURL] 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
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).
FreeTradeNo String(20)
TicketList Array[Object]
List of Redeemed or Refunded Tickets.
TicketType String(1)
Types of tickets.
- 1：Pickup voucher
- 2：Gift voucher
TicketNo String(16)
Ticket serial number.
TicketPrice Int
Denomination of the ticket.
ChangeType String(1)
Ticket status change type.
- 1：Redemption Complete
- 2：Refund Complete
ChangeMID String(10)
Merchant ID for executing this ticket redemption or refund.
ChangeStoreID String(20)
The branch for executing this ticket redemption or refund.
ChangeDate String(14)
The date of executing this ticket redemption or refund, formatted as: yyyymmdd.
CompleteDate String(14)
Date of completion of upload for redemption or refund data, formatted as: yyyymmdd.
Data Example (JSON format)
{
"MerchantID": "2000132",
"MerchantTradeNo":"CBX20220302153064851",
"FreeTradeNo":"",
"TicketList":[
{
"TicketType":"1",
"TicketNo":"CB2SY20220302153",
"TicketPrice":250,
"ChangeType":"1",
"ChangeMID":"2000132",
"ChangeStoreID":"",
"ChangeDate":"20231212",
"CompleteDate":"20231213"
},
{
"TicketType":"1",
"TicketNo":"CB2SY20220302154",
"TicketPrice":250,
"ChangeType":"1",
"ChangeMID":"2000132",
"ChangeStoreID":"",
"ChangeDate":"20231212",
"CompleteDate":"20231213"
},
{
"TicketType":"2",
"TicketNo":"CB2SY20220302155",
"TicketPrice":250,
"ChangeType":"1",
"ChangeMID":"2000132",
"ChangeStoreID":"",
"ChangeDate":"20231212",
"CompleteDate":"20231213"
},
{
"TicketType":"2",
"TicketNo":"CB2SY20220302156",
"TicketPrice":250,
"ChangeType":"1",
"ChangeMID":"2000132",
"ChangeStoreID":"",
"ChangeDate":"20231212",
"CompleteDate":"20231213"
},
]
}
Response (JSON format)
PlatformID String(10)
Platform ID
MerchantID String(10)
Merchant ID (provided by ECPay)
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 system will change the ticket status to “redeemed” or “refunded” at 01:00 a.m. on the day after the redemption or refund operation.
- Tickets with the status “redeemed” or “refunded” will begin receiving proactive notifications daily at 03:00 a.m.