Scenarios
Vendors are required to send the BindCardPayToken to the ECPAY Server to set up the bind credit card transaction.
Special note: This API needs to connect with the bank, if the bank connection is unstable, the response time may increase. If you want to set the time for the API connection to overrun, it is recommended to set the time to overrun at least 30 seconds.
API URLs
- Stage: https://ecpg-stage.ecpay.com.tw/Merchant/CreateBindCard
- Production: https://ecpg.ecpay.com.tw/Merchant/CreateBindCard
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.
PlatformID String(10)
Platform ID
- This is used by platform merchants and will be provided by ECPay.
- For platform merchants, please populate with [MerchantID].
- For general merchants, please set as null.
MerchantID String(10)
Required
Merchant ID
BindCardPayToken String(64)
Required
MerchantMemberID String(60)
Required
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)
For 3D verification, return the following parameters.
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.
Special note: If the following code is received, it is recommended that the vendor confirm the credit card status with the consumer.
- RtnCode = 10100252 means the balance of the card is insufficient.
- RtnCode = 10100255 means the card is lost.
RtnMsg String(200)
Response messages.
PlatformID String(10)
Platform merchant’s MerchantID.
MerchantID String(10)
Merchant ID
OrderInfo Object
MerchantTradeNo String(20)
ThreeDInfo Object
ThreeDURL String(200)
Special note: Please do not use iframe to open the 3D verification link.
Response Example (Json format)
Response Example (Json format): When you don't go for 3D verification
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)
Merchant ID
MerchantMemberID String(30)
Merchant Member ID
BindCardID String(64)
If the value is null or an empty string, it indicates that the binding card information for the order no longer exists or has expired. This does not affect the result of the transaction authorization.
IsSameCard Bool
Has this credit card been repetitively bound
OrderInfo Object
MerchantTradeNo String(20)
Merchant Trade No
TradeNo String(20)
Transaction Number
TradeAmt Int
Merchant Trade Amount
TradeDate String(20)
Format yyyy/MM/dd HH:mm:ss
PaymentType String(20)
Payment method
- Credit: credit cards
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
- 0 : Order is confirmed without payment.
- 1 : Payment made on behalf of the trade order
CardInfo Object
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
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
CardValidYY String(2)
Credit Card Expiration year
Format : YY。
CardValidMM String(2)
Credit Card Expiration Months
Format : MM。
Stage Int
Number of installments
Stast Int
Amount of down payment
Staed Int
Amount of each period (except for down payment)
CustomField String(200)
A parameter for merchant to place customized value.