Scenario
Merchant’s server should send the PayToken (received from merchant’s web) to ECPay’s server to create a payment.
Special notes: As some of the APIs need to be connected to the bank, the response time may increase if the bank disconnects. If you must set an API timeout, we recommend 30 seconds minimum.
API URLs
- Stage: https://ecpg-stage.ecpay.com.tw/Merchant/CreatePayment
- Production: https://ecpg.ecpay.com.tw/Merchant/CreatePayment
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)
{
"MerchantID": "3002607",
"RqHeader": {
"Timestamp": 1234567890
},
"Data": "enter your data"
}
Message payload of Data (Json format)
Special note: Please urlencode the JSON string firstly and then do AES encryption.
PlatformID String(10)
Platform ID
MerchantID String(10)
Required
PayToken String(64)
Required
A token (a serial number) sent to ECPay’s server to create a transaction.
MerchantTradeNo String(20)
Required
Merchant’s order ID. The value should be the same as that sent to (/GetTokenByTrade.)
Data Example:(Json format)
{
"MerchantID": "3002607",
"PayToken": "enter your paytoken",
"MerchantTradeNo": "test123456789"
}
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)
{
"MerchantID": "3002607",
"RpHeader": {
"Timestamp": 1234564848
},
"TransCode": 1,
"TransMsg": "Success",
"Data": "…"
}
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)
OrderInfo Object
Order information
MerchantTradeNo String(20)
Merchant’s order ID
ThreeDInfo Object
3DS validation information
ThreeDURL String(200)
3DS validation URL
Special note: A URL used to do 3DS validation. Please do not use iframe to open the URL.
Message payload of Data (Json format) : UnionPay
If using UnionPay, following 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)
OrderInfo Object
Order information
MerchantTradeNo String(20)
Merchant’s order ID
UnionPayInfo Object
UnionPay validation information
UnionPayURL String(200)
UnionPay validation URL.
Special note:
- A URL to redirect the cardholder to do UnionPay 3DS validation. Please do not use iframe to open the URL.
- On ECPay’s Stage environment, ECPay has a mock payment page of this URL, which is not a real one. So please do not use real card numbers.
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
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
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. 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.
IssuingBank String(30)
Bank name
IssuingBankCode String(10)
Bank code
CustomField String(200)
A parameter for merchant to place customized value.
Message payload of Data (Json format): ATM
If using ATM, 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)
MerchantID String(10)
OrderInfo Object
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.
TradeStatus String(8)
Status of transaction
ATMInfo Object
ATM information
BankCode String(3)
Bank code
vAccount String(16)
Payment virtual account number
ExpireDate String(10)
Payment deadline. Format: yyyy/MM/dd
CustomField String(200)
A parameter for merchant to place customized value.
Message payload of Data (Json format): CVS code
If using CVS, 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)
PlatformID String(10)
MerchantID String(10)
OrderInfo Object
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
TradeStatus String(8)
Status of transaction
CVSInfo Object
CVS information
PaymentNo String(14)
Payment number
ExpireDate String(20)
Payment deadline. Format: yyyy/MM/dd HH:mm:ss
PaymentURL String(100)
Payment URL. A URL provided by ECPay for merchants to display 3-stripe CVS payment number on consumer’s mobile.
CustomField String(200)
A parameter for merchant to place customized value.
Message payload of Data (Json format): CVS barcode
If using CVS barcode, 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)
PlatformID String(10)
MerchantID String(10)
OrderInfo Object
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
TradeStatus String(8)
Status of transaction
BarcodeInfo Object
Barocde information. Only 3 barcode-numbers will be returned, while the barcode image will not be returned. Merchants need to convert the barcode number into a code 39 barcode label.
ExpireDate String(20)
Payment deadline. Format: yyyy/MM/dd HH:mm:ss
Barcode1 String(20)
First barcode. Possible value: A 9-digit serial number.
Barcode2 String(20)
Second barcode stripe number. Possible value: A 16-digit serial number.
Barcode3 String(20)
Third barcode stripe number. Possible value: A 15-digit serial number.
CustomField String(200)
A parameter for merchant to place customized value.
Data Example(Json format): ※The example is based on 3D verification results.
{
"RtnCode": 1,
"RtnMsg": "Success",
"PlatformID": "1234567890",
"MerchantID": "1234567890",
"OrderInfo": {
"MerchantTradeNo": "test123466"
},
"ThreeDInfo": {
"ThreeDURL": "https://3durl.com.tw"
}
}