All-In-One API Document

Results / Payment Results Notification

Scenario

Server Site POST (ReturnURL)
When the payment has been completed, the merchant will receive ECPay’s payment results notification and respond to it.

  • Step1. ECPay: Transmit payment results message to the merchant’s server URL [ReturnURL]
  • Step2. Merchant: Upon receiving the payment results message from ECPay, check and verify whether the checksum is correct.
  • Step3. Merchant: If the checksum is correct, respond 1|OK on the webpage end.
❗ Special note：
  1. Barcode payment results will be returned 2 days after payment completion.
  2. For ATM/CVS/BARCODE payments, merchants can test the payment notification (callback) on ECPay’s dashboard to test if the ReturnURL can successfully receive the callback from ECPay’s server.
  3. Common errors of not receiving callbacks please see the FAQ.
  4. The string “1|OK” is merely a response, which is to tell ECPay’s server that this callback is successfully received by merchant’s server. This response “1|OK” will not change the payment status.

Client Site Post (OrderResultURL)
When the payment has been completed, ECPay will return payment results message one-time and redirect to the merchant’s designated page.

  • Step1. ECPay: The payment results message will be transmitted to the merchant and redirect the page to the merchant’s designated page.
  • Step2. Merchant: Upon receiving the payment results message from ECPay, check and verify whether the checksum value is correct.

❗ Special note：

  1. If this parameter [OrderResultURL] is not set, it is the ECPay’s payment completed page that will be shown (instead of the merchant’s website).Therefore, if merchants wish to have the payment result displayed on merchants’ page, please set this parameter [OrderResultURL].
  2. If this parameter [OrderResultURL] is set with [ClientBackURL], ECPay will accept this parameter but ignore [ClientBackURL].
  3. For some specific banks, the transaction completed page will stay on the bank’s page after successful WebATM transactions instead of redirecting the page back to ECPay. In this case, ECPay will not direct the page to the [OrderResultURL] page.
  4. This parameter does not support UnionPay cards or non-real-time transactions (ATM, CVS, BARCODE).
  5. It is not recommended to set this parameter in Stage. The page will stay on ECPay so you can see the error messages sent by ECPay for debugging purposes.
  6. If this parameter is set, displaying the successful/failed payment page can only be displayed on the transaction status returned.
  7. If the authorization time is too long to receive the response message due to the different processing time by banks, please use the Order Search API before display the payment results
  8. Some browsers may display a warning if the return URL is not an https address.

HTTPS Transfer Protocol

  • Accept ：text/html
  • Content Type ：application/x-www-form-urlencoded
  • HTTP Method ：POST

Return Parameter Details

MerchantID String(10) 
MerchantTradeNo String(20)

Merchant transaction ID.

  • Merchant Transaction ID transmitted to ECPay when order was created. A combination of upper and lower case alphanumeric characters.
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.

  • If the value returned is 1, then payment was successful.
  • Other values indicate transaction exception and please check the function on Merchant’s Admin Website to determine whether to ship.
RtnMsg String(200)
Transaction message.
  • Server Site POST success message：交易成功(Transaction success)
  • Server Site POST resend the notification message：paid
  • Client Site Post success message：Succeeded
TradeNo String(20)

transaction ID.

  • Please save the link between the ECPay transaction ID and the merchant transaction ID [MerchantTradeNo].
TradeAmt Int
Transaction amount
PaymentDate String(20)

Payment time.

  • The format is yyyy/MM/dd HH:mm:ss
PaymentType String(20)
Merchant payment method
PaymentTypeChargeFee Number
Retail fee
TradeDate String(20)

Transaction time.

  • The format is yyyy/MM/dd HH:mm:ss
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：

  1. 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.
  2. 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.
  3. 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
CustomField2 String(50)
Merchant notes field
CustomField3 String(50)
Merchant notes field
CustomField4 String(50)
Merchant notes field
CheckMacValue String

Checksum.

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：

  1. 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.
  2. If a correct message has not been received, the system will re-send it to the merchant after 5–15 minutes. After 3 unsuccessful attempts, the system will try sending again the next day.
  3. If the merchant continues to receive returned payment information from ECPay, please check if ECPay is receiving the correct response 1|OK. A common wrong return value error is (“1|OK”, 1|ok, OK, 1\OK,blank).
  4. If the customer has paid but has not received payment completed information from ECPay, please check the server receiving return parameters is working properly.
  5. When the value of [SimulatePaid] is 1, it means that the order information received is a payment notification test message from a simulated payment from the merchant back-stage management system. It is not a customer’s order, so ECPay will not pay the merchant. Please do not ship the merchandise to avoid losses.
  6. 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.
The payment results notification will be returned to the page in parameters in chart as follows. It is displayed in “parameter=value” format. Parameters are separated by an ampersand (&). For example: 
				
					MerchantID=2000132&MerchantTradeNo=TEST8477&PayAmt=300&PaymentDate=2016/11/02&11:41:12&PaymentType=Credit_CreditCard&PaymentTypeChargeFee=3&RtnCode=1&RtnMsg=交易成功&SimulatePaid=0&TradeAmt=300&TradeDate=2016/11/02&11:40:33&TradeNo=1611021140332409&CheckMacValue=F5587E192EACB414A31127C1E370CD55

Copyright © Green World FinTech Service Co., Ltd. All rights reserved.

Green World