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：

Barcode payment results will be returned 2 days after payment completion.
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.
Common errors of not receiving callbacks please see the FAQ.
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：

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].
If this parameter [OrderResultURL] is set with [ClientBackURL], ECPay will accept this parameter but ignore [ClientBackURL].
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.
This parameter does not support UnionPay cards or non-real-time transactions (ATM, CVS, BARCODE).
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.
If this parameter is set, displaying the successful/failed payment page can only be displayed on the transaction status returned.
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
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：

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

CustomField2 String(50)

Merchant notes field

CustomField3 String(50)

Merchant notes field

CustomField4 String(50)

Merchant notes field

CheckMacValue String

Checksum.

The merchant must check the check [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.
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.
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).
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 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.
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

YAML

The provided YAML file is used to define information such as the configuration, structure, operations, and infrastructure management of the API, making it easier for developers to understand and use the API.

				
					openapi: 3.1.0
info:
  title: ECPay Payment Result Notification API
  version: 1.0.0
servers:
  - url: ReturnUrl
    description: Production Environment
  - url: ReturnUrl
    description: Testing Environment
paths:
  /payment/Result:
    post:
      summary: Payment Result Notification
      description: Notify the merchant of the payment result.
      requestBody:
        required: true
        content:
          html/text:
            schema:
              type: object
              required:
                - MerchantID
                - MerchantTradeNo
                - RtnCode
              properties:
                  MerchantID:
                    type: string
                    maxLength: 10
                    description: Merchant ID
                  MerchantTradeNo:
                    type: string
                    maxLength: 20
                    description: Merchant trade number, sent to ECPay when the order is created
                  StoreID:
                    type: string
                    maxLength: 20
                    description: Store ID under the merchant
                  RtnCode:
                    type: integer
                    description: Transaction status. If the return value is 1, it indicates successful payment. Other codes indicate transaction abnormalities. Please check in the merchant management backend before shipping.
                  RtnMsg:
                    type: string
                    maxLength: 200
                    description: Transaction message
                  TradeNo:
                    type: string
                    maxLength: 20
                    description: ECPay's transaction number. Please keep the relationship between ECPay's transaction number and the merchant trade number
                  TradeAmt:
                    type: integer
                    description: Transaction amount
                  PaymentDate:
                    type: string
                    maxLength: 20
                    format: date-time
                    description: Payment time
                  PaymentType:
                    type: string
                    maxLength: 20
                    description: Payment method selected by the merchant. Please refer to the list of payment methods returned
                  PaymentTypeChargeFee:
                    type: number
                    description: Transaction handling fee amount
                  TradeDate:
                    type: string
                    maxLength: 20
                    format: date-time
                    description: Order creation time
                  SimulatePaid:
                    type: integer
                    enum: [0, 1]
                    description: Whether it is a simulated payment.
                  CustomField1:
                    type: string
                    maxLength: 50
                    description: Custom field 1, provided for cooperative partners for custom use
                  CustomField2:
                    type: string
                    maxLength: 50
                    description: Custom field 2, provided for cooperative partners for custom use
                  CustomField3:
                    type: string
                    maxLength: 50
                    description: Custom field 3, provided for cooperative partners for custom use
                  CustomField4:
                    type: string
                    maxLength: 50
                    description: Custom field 4, provided for cooperative partners for custom use
                  CheckMacValue:
                    type: string
                    description: Check code. Merchants must check the check code to verify

      responses:
        '200':
          description: Success
          content:
            text/plain:
              schema:
                type: string
                example: 1|OK
        '400':
          description: Invalid request
        '500':
          description: Server error

Green World