Scenario
Allows merchants to use credit card numbers to call the ECPay API for backend transaction authorization.
Special Notes: This API needs to connect with banks. If bank connections are unstable, it may lead to increased response times. If merchants need to set an API connection timeout, it is recommended to set it to at least 30 seconds.
API URLs
- Stage: https://ecpayment-stage.ecpay.com.tw/1.0.0/Cashier/BackAuth
- Production: https://ecpayment.ecpay.com.tw/1.0.0/Cashier/BackAuth
Message format
- 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.
Request Example (Json format)
Message payload of Data (Json format)
Special note: Please urlencode the JSON string firstly and then do AES encryption.
MerchantID String(10)
Required
OrderInfo Object
Required
MerchantTradeNo String(20)
Required
Merchant’s order ID
- Created by the merchant, [MerchantTradeNo] should be a unique identifier combined with upper and lower case alphanumeric characters.
Special note: How can merchants avoid duplicated MerchantTradeNo? Please read the FAQ.
MerchantTradeDate String(20)
Required
Time at which the order was created. Format: yyyy/MM/dd HH:mm:ss
TotalAmount Int
Required
Amount of order
- Integer only; decimal is not accepted.
- New Taiwan Dollar only. The limit amount of each payment please refet to: https://www.ecpay.com.tw/Business/payment_fees
ItemName String(400)
Required
Name of products
- Each product should be separated by a hash (#).
TradeDesc String(200)
Required
Description of order
ReturnURL String(200)
Required
The URL of merchant’s server to receive ECPay’s payment notification (callback).
- When consumer completes payment, ECPay’s server will respond payment notification (callback) to ReturnURL (using POST). For more detail a please see Payment result notification (callback).
Special note:
- This is a server-side URL. Please do not set this URL same as OrderResultURL, which is a URL of client-side.
- Upon receiving the callback from ECPay, please respond a string “1|OK“.
- The string “1|OK” is merely a response, which is to tell ECPay’s server that this callback is successfully received. The 1|OK will not change the payment status.
ChoosePayment Object
Required
Fixed “Credit”
CardInfo Object
Required
CardNo String(19)
Required
Credit Card Number
CardValidMM String(2)
Required
Credit Card Valid Months
CardValidYY String(2)
Required
Credit Card Valid Years
CardCVV2 String(4)
Required
Credit Card Security Code
DirectCapture String(1)
Required
Provides merchants with automatic settlement and payment request after successful authorization.
- 0 : No (Default)
1 : Yes
Redeem String(1)
Whether to use credit card bonus.
- 0 : No (Default)
1 : Yes
CreditInstallment String(20)
Periods (cycles) of credit card installment plan.
- Required if ChoosePaymentList: 0 (all payment methods) or 2 (credit card installments).
- This parameter supports more than one period, and each value should be separated by comma (,). For example, CreditInstallment: 3,6,12,18,24
PeriodAmount Int
Amount to be authorized of each period. Required if PaymentUIType: 0 (credit card recurring payment).
PeriodType String(1)
Type of subscription. Required if PaymentUIType: 0
Values including:
- D：daily subscription
- M：monthly subscription
- Y：yearly subscritpion
Frequency Int
Execution frequency. The frequency of authorization (i.e. how often the authorization is executed.). Required if PaymentUIType: 0
Special note:
- Must be more than once.
- If PeriodType: D, Frequency: 365 (at most).
- If PeriodType: M, Frequency: 12 (at most).
- If PeriodType: Y, Frequency: 1 (at most).
ExecTimes Int
Number of executions. Required if PaymentUIType: 0
Special note:
- If PeriodType: D, Frequency: 999 (at most).
- If PeriodType: M, Frequency: 99 (at most).
- If PeriodType: Y, Frequency: 9 (at most).
PeriodReturnURL String(200)
A URL of merchant’s server to receive ECPay’s payment notification (callback) of recurring payment (subscription plan).
- Required if PaymentUIType: 0 (credit card recurring payment).
- If the transaction is a repeated/recurring payment (subscription plan), except for the first-time payment (the payment notification will be sent to ReturnURL), the second and the follow-up payment notifications will be sent to this parameter.
OrderResultURL String(200)
A URL of merchant’s webpage on client-side to receive 3DS payment result.
Special note: When consumer completes 3DS validation, ECPay will redirect the payment result to this URL. Details about the data returned please see the chapter of Notifications.
ConsumerInfo Object
Consumer information
Email String(30)
Credit card holder’s email
Phone String(60)
Credit card holder’s phone number.
Special notes: Mobile country code is accepted, but the prefix should not have plus symbol (+). E.g.: 886912345678
Name String(50)
Credit card holder’s name. Chinese, English and some special chacters are accepted. Special characters support: , . ( ) / –
CountryCode String(3)
Country code
- A 3-digit contry code of the credit card holder’s bill address, which should follow ISO 3166.
Address String(50)
Credit card holder’s bill address.
CustomField String(200)
A parameter for merchant to place customized value.
Data Example:(Json format)
Response (Json format)
MerchantID String(10)
Merchant ID
RpHeader Object
Timestamp Number
Unix timestamp
TransCode Int
Response codes to indicate whether the payload is successfully accepted.
- 1: Payload (i.e. MerchantID, RqHeader, and Data) is successfully accepted by ECPay.
- Others: failed.
TransMsg String(200)
Response message to indicate whether the payload is successfully accepted.
Data String
Payload of JSON that has been encrypted.
Response Example (Json format)
Message payload of Data (Json format) : 3DS validation
If using 3DS validation, following Parameters in Data will be returned.
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 merchant’s MerchantID.
MerchantID String(10)
MerchantTradeNo String(20)
Merchant’s order ID
ThreeDURL String(200)
3DS validation URL
Special note: A URL used to do 3DS validation. Please do not use iframe to open the URL.
Data Example(Json format): ※The example is based on 3D verification results.
Message payload of Data (Json format): If not using 3DS validation, following Parameters in Data will be returned
If not using 3DS validation, following Parameters in Data will be returned directly to merchant’s server (ReturnURL).
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)
OrderInfo Object
Order information
MerchantTradeNo String(20)
Merchant’s order ID
TradeNo String(20)
ECPay’s order ID
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
ProcessFee Number
ECPay’s transaction processing fee
TradeStatus String(8)
Status of transaction
CardInfo Object
Credit card information
AuthCode String(6)
Authorization code
Gwsr Int
ID of authorization
ProcessDate String(20)
Date of processing authorization. Format: yyyy/MM/dd HH:mm:ss
Amount Int
Transaction/authorization amount
Card6No String(6)
First 6 digits of credit card
Card4No String(4)
Last 4 digits of credit card
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.
IssuingBank String(30)
Bank name
IssuingBankCode String(10)
Bank code
Stage Int
Number of installments
Stast Int
Amount of down payment
Staed Int
Amount of each period (except for down payment)
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. Required if PaymentUIType: 0
Values including:
- D: daily subscription
- M: monthly subscription
- Y: yearly subscritpion
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.
CustomField String(200)
A parameter for merchant to place customized value.
Data Example(Json format): If not using 3DS validation, following Parameters in Data will be returned
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.