Scenario
When an order is a periodic fixed-amount purchase, ECPay will transmit payment results notification after every successful authorization.
- Step 1. ECPay : The second authorization is scheduled and processed by ECPay . Upon successful authorization, the payment notification will be transmitted to the payment complete notification return URL [PeriodReturnURL], transmitted by the merchant, via Server Site POST.
- Step 2. Merchant: Merchants are required to check and verify whether the checksum is correct upon receiving the payment notification message from ECPay .
- Step 3. Merchant: If the checksum is correct, respond 1|OK on the webpage end.
Special Note：
- If the first authorization is successful, the payment result parameter will be returned to the payment complete notification return URL [ReturnURL].
- The second authorization is scheduled and processed by ECPay . From the second authorization, the data will be returned to the payment complete notification return URL PeriodReturnURL] set.
HTTPS Transfer Protocol
- Accept ：text/html
- Content Type ：application/x-www-form-urlencoded
- HTTP Method ：POST
Return Parameters Description
MerchantID String(10)
MerchantTradeNo String(20)
Merchant transaction ID.
- Merchant Transaction ID transmitted to merchant when order was created.
StoreID String(20)
Merchant store ID.
- Allows merchants to enter specific store ID.
- This parameter only allows a combination of upper and lower case alphanumeric characters.
RtnCode Int
Transaction status.
- 1: authorization successful. Any other value is fail.
RtnMsg String(200)
Transaction message
PeriodType String(1)
Types of periods
Frequency Int
Execution frequency
ExecTimes Int
Number of executions
Amount Int
Authorization amount for this transaction
Gwsr Int
Authorization ID for this transaction
ProcessDate String(20)
Process time (yyyy/MM/dd HH:mm:ss)
AuthCode String(6)
Authorization code
FirstAuthAmount Int
First authorized amount for periodic fixed-amount purchase
TotalSuccessTimes Int
SimulatePaid Int
Is it a simulated payment?
Possible value:
- 0: this payment is a real payment, not simulated.
- 1: this payment is simulated, not a real payment, please do not ship the product.
Special note：
- Merchant can mock/simulate the payment by pressing the button on ECPay’s admin portal (dashboard) to test if the ReturnURL can receive the callback from ECPay’s server.
- This parameter is only a feature, a function to test if merchant’s server could receive the callback by ECPay’s server, which will not change payment status.
- In terms of the feature of searching an order of a recurring payment (server), only if users search an order of a recurring payment through ECPay’s admin (dashboard), will ECPay’s server respond this parameter.
- For payment’s notification (callback) of real recurring orders, ECPay’s server will not respond this parameter in the callback.
CustomField1 String(50)
Merchant notes field for customization
CustomField2 String(50)
Merchant notes field for customization
CustomField3 String(50)
Merchant notes field for customization
CustomField4 String(50)
Merchant notes field for customization
CheckMacValue String
Checksum.
- The merchant must check the [CheckMacValue] to verify.
Merchant parameter transmission details:
The value returned is a text string and does not have parameter names
- If the first digit returned is 1, it is success.
- If the first digit returned is 0, it is failure. 0|ErrorMessage refers (error code – error message).
- The value only means whether the merchant receives the return message from ECPay and parameters are correct.The value does not affect the status of order.
Special Note：
- The merchant must check if the checksum [CheckMacValue] is correct, whether a payment notice has been made for the order, and whether relevant actions have been taken to prevent losses due to unsynchronized transaction status.
- [PeriodReturnURL] will only receive one notification per issue. If you have not received notification, please use Order Search for Periodic Fixed-Amount Purchases on Credit Cards API.
- If the customer has paid but has not received payment completed information from ECPay , please check the server receiving return parameters is working properly.
- When the value of [SimulatePaid] is 1, it means that the order information received is a payment notification test message returned from a simulated payment from the ECPay merchant back-stage management system. Please do not ship the merchandise to avoid losses.
- The merchant must determine if the transaction status [RtnCode] is 1, if it is not 1, do not ship the merchandise and request transaction information [RtnMsg] to record reason of failure.