Scenario
Server-side notifications(ReturnURL)
When a consumer makes a payment, merchant’s server (i.e. ReturnURL) will receive a notification sent by ECPay’s. When your server receives ECPay’s notification, please respond a string 1|OK.
- Step1. ECPay’s server:send payment notification to ReturnURL.
- Step2. Merchant’s server: respond a string 1|OK.
Special note:
- Barcode payment notification will be sent 2 days later since the payment completes (D+2).
- For non-instant payment (i.e. ATM, CVS or BARCODE), merchants can test if ReturnURL can receive ECPay’s notification on ECPay’s dashboard. ECPay’s dashboard has a function of a mock payment button to test it.
- For common errors of not receiving notifications please see the FAQ.
- The string 1|OK is merely a message in response to tell ECPay’s server that the ReturnURL already successfully received the notification request; the 1|OK will not change the payment state.
Message format
- Accept ：text/html
- Content Type：application/json
- HTTP Method：POST
Request (Json format)
MerchantID String(10)
Required
For platform merchants, the value please populate with the Platform merchant’s MerchantID.
RqHeader Object
Required
Request header
Timestamp Number
Required
Unix timestamp
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 String
Required
Payload of JSON that has been encrypted.
Response Example (Json format)
{
"MerchantID": "3002607",
"RpHeader": {
"Timestamp": 1234564848
},
"TransCode": 1,
"TransMsg": "Success",
"Data": "…"
}
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.
PlatformID String(10)
Platform ID
MerchantID String(10)
SimulatePaid Int
Whether this is a mock payment. Possible value:
- 1: indicating the notification of this payment is a mocked payment (simulated), which is triggered from ECPay’s dashboard, not a real payment. Please do not ship the product.
Special note:
- Merchants can mock/simulate the payment by pressing the button on ECPay’s dashboard to test if the ReturnURL can receive the call sent by ECPay’s server.
- This parameter is to indicate that this is a test notification, to test whether merchant’s server could receive the request from ECPay’s server. It will not change payment state.
- For recurring payment (credit card repeated payment/subscription plan), ECPay will not send this parameter to merhcant’s PeriodReturnURL; instead, only when the mock payment button is pressed on ECPay’s dashboard, ECPay’s server will send this parameter to PeriodReturnURL.
OrderInfo Object
Order information
MerchantTradeNo String(20)
Merchant’s order ID
TradeNo String(20)
ECPay’s order ID. Please save this parameter in merchant’s system in order to keep the relation between ECPay’s order ID merchants’ order ID MerchantTradeNo.
TradeAmt Int
Transaction amount
TradeDate String(20)
Time at which the order was created. Format: yyyy/MM/dd HH:mm:ss
PaymentType String(20)
Payment method
PaymentDate String(20)
Date of payment. Format: yyyy/MM/dd HH:mm:ss
ChargeFee Number
ECPay’s service charge
TradeStatus String(8)
Status of transaction
CardInfo Object
Credit card information. If using credit card or Union Pay, the CardInfo will be returned.
AuthCode String(6)
Authorization code. Not returned if using Union Pay card.
Gwsr Int
ID of authorization
ProcessDate String(20)
Date of processing authorization. Format: yyyy/MM/dd HH:mm:ss
Amount Int
Transaction/authorization amount
Stage Int
Number of installments
Stast Int
Amount of down payment
Staed Int
Amount of each period (except for down payment)
Eci Int
Return value of 3D (VBV). This is a value returned from the Directory Server (Visa, MasterCard, and JCB) to indicate the authentication results of cardholder’s credit card payment on 3D Secure.
Possible values:
5, 6, 2, 1: The value returned (ECI) means that transaction was a 3D secure authentication.
Card6No String(6)
First 6 digits of credit card
Card4No String(4)
Last 4 digits of credit card
RedDan Int
Credit card bonus used. The value will be returned if using the credit card bonus.
RedDeAmt Int
Amount deduced from bonus points. The value will be returned if using the credit card bonus.
RedOkAmt Int
Actual amount charged. The value will be returned if using the credit card bonus.
RedYet Int
Credit card bonus remained. The value will be returned if using the credit card bonus.
PeriodType String(1)
Type of subscription.
Frequency Int
Execution frequency. The value will be returned if using subscription plan. The value indicates the frequency of authorization (i.e. how often the authorization is executed.)
ExecTimes Int
Number of executions. The value will be returned if using subscription plan. The value indicated how many times the authorization is executed.
PeriodAmount Int
Amount to be authorized of each period. The value will be returned if using subscription plan.
TotalSuccessTimes Int
Number of total successful authorizations. The value will be returned if using subscription plan. The value indicates how many times the authorization is successfully executed.
TotalSuccessAmount Int
Total amount of all successful authorizations. The value will be returned if using subscription plan.
IssuingBank String(30)
Bank name
IssuingBankCode String(10)
Bank code
CVSInfo Object
CVS information. If using CVS as payment method, the CVSInfo will be returned.
PayFrom String(10)
Payment made at which convenience store. Possible values:
- family: FamilyMart
- hilife: Hi-Life
- okmart: OK mart
- ibon: 7-ELEVEN
PaymentNo String(14)
Payment number.
PaymentURL String(100)
Payment URL
BarcodeInfo Object
Barcode information. If using BARCODE as payment method, the BarcodeInfo will be returned.
PayFrom String(10)
Payment made at which convenience store.
- family: FamilyMart
- hilife: Hi-Life
- okmart: OK mart
- ibon: 7-ELEVEN
ATMInfo Object
ATM information. If using ATM as payment method, the ATMInfo will be returned.
ATMAccBank String(3)
Payer’s bank code
ATMAccNo String(5)
Last 5 digits of the payer’s bank account.
CustomField String(200)
A parameter for merchant to place customized value.
Data Example(Json format):
{
"RtnCode": 1,
"RtnMsg": "Success",
"MerchantID": "3002607",
"OrderInfo": {
"MerchantTradeNo": "20180914001",
"TradeNo": "1809261503338172",
"TradeDate" :"2018/09/26 14:59:54"
},
"CardInfo": {
"Gwsr": 10735183,
"ProcessDate": "2018/09/26 14:59:54",
"AuthCode": "777777",
"Amount": 100,
"Eci": 2,
"Card4No": "2222",
"Card6No": "491122",
"RedDan": 0,
"RedOkAmt": 0,
"RedYet": 0
}
}
Special note:
- If not correctly responding the string 1|OK, ECPay’s server will have re-send the notification once every 5-15 minutes for 4 times on the payment date.
- If merchants keep receiving notifications from ECPay, please check if ReturnURL correctly responds the string 1|OK. Common errors may be due to incorrect values, such as “1|OK”, 1|ok, _OK, 1\OK or empty value, which will also cause ECPay’s scheduler to re-send the notifications.
- If consumers already paid but merchants did not receive the notifications from ECPay, please check the ReturnURL. Common errors of not receiving notifications can be referred to: FAQ.
- If RthCode is not 1, please do not ship the product to consumers. Instead, please record the RtnMsg and check the root cause.