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.
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 Periodic Payment Result Notification API
version: 1.0.0
servers:
- url: PeriodReturnURL
description: Production Environment
- url: PeriodReturnURL
description: Testing Environment
paths:
/payment/periodic/Result:
post:
summary: Periodic Payment Result Notification
description: Notify the merchant of the periodic 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
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
AlipayID:
type: string
maxLength: 10
description: Payee's system number in Alipay
AlipayTradeNo:
type: string
maxLength: 20
description: Alipay transaction number
TenpayTradeNo:
type: string
maxLength: 20
description: Tenpay transaction number
TWQRTradeNo:
type: string
maxLength: 64
description: Mobile payment transaction number. Returned only when the payment method is TWQR.
WebATMAccBank:
type: string
maxLength: 3
description: Payer's bank code for WebATM
WebATMAccNo:
type: string
maxLength: 5
description: Last five digits of the payer's bank account for WebATM
WebATMBankName:
type: string
maxLength: 10
description: Bank name
ATMAccBank:
type: string
maxLength: 3
description: Payer's bank code for ATM
ATMAccNo:
type: string
maxLength: 5
description: Last five digits of the payer's bank account for ATM
PaymentNo:
type: string
maxLength: 14
description: Payment code
PayFrom:
type: string
maxLength: 10
description: Payment store
enum: [family, hilife, okmart, ibon]
gwsr:
type: integer
description: Authorization transaction number. This parameter value is the same as CreditRefundID in credit card details query.
process_date:
type: string
maxLength: 20
format: date-time
description: Processing time
auth_code:
type: string
maxLength: 6
description: Authorization code
amount:
type: integer
description: Amount
stage:
type: integer
description: Number of installments
stast:
type: integer
description: Initial payment amount
staed:
type: integer
description: Subsequent payment amount
eci:
type: integer
description: 3D (VBV) return value (eci=5,6,2,1 represents 3D transaction)
card4no:
type: string
maxLength: 4
description: Last 4 digits of the card
card6no:
type: string
maxLength: 6
description: First 6 digits of the card
red_dan:
type: integer
description: Bonus point deduction
red_de_amt:
type: integer
description: Bonus redemption amount
red_ok_amt:
type: integer
description: Actual deduction amount
red_yet:
type: integer
description: Remaining bonus points
PeriodType:
type: string
maxLength: 1
description: Period type set when the order is created
Frequency:
type: integer
description: Execution frequency set when the order is created
ExecTimes:
type: integer
description: Execution frequency set when the order is created
PeriodAmount:
type: integer
description: Authorization amount per time set when the order is created
TotalSuccessTimes:
type: integer
description: Total number of successful authorizations at present
TotalSuccessAmount:
type: integer
description: Total amount of successful authorizations at present
responses:
'200':
description: Success
content:
text/plain:
schema:
type: string
example: 1|OK
'400':
description: Invalid request
'500':
description: Server error