Scenarios
Before using ECPay’s merchant member credit card binding service, the merchant server must first obtain a vendor verification token from ECPay’s server. Once the merchant server receives the token, it must pass the token to the merchant’s website to generate the credit card binding interface.
Special note：
If a merchant has more than one MerchantID or if the ECPay member identity is a platform merchant, and the merchant’s member IDs must be shared, the merchant must apply to ECPay’s business unit to join the platform merchant’s binding whitelist (PlatformID). When integrating the API, any MerchantID should include the PlatformID parameter, and the integration mode should switch to platform merchant mode.
A merchant member can bind up to 5 credit cards.
API URLs
- Stage: https://ecpg-stage.ecpay.com.tw/Merchant/GetTokenbyBindingCard
- Production: https://ecpg.ecpay.com.tw/Merchant/GetTokenbyBindingCard
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
ConsumerInfo Object
Required
Consumer information
MerchantMemberID String(60)
Required
Consumer’s ID (if merchant has a member system).
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.
OrderInfo Object
Required
Order information
MerchantTradeDate String(20)
Required
Time at which the order was created. Format: yyyy/MM/dd HH:mm:ss
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.
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
TradeDesc String(200)
Required
Description of order
ItemName String(400)
Required
Name of products
- Each product should be separated by a hash (#).
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).
CreditInstallment String(20)
Periods (cycles) of credit card installment plan.
- This parameter supports more than one period, and each value should be separated by comma (,). For example, CreditInstallment: 3,6,12,18,24
OrderResultURL String(200)
Required
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.
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)
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
Token String(64)
Each checkout request to ECPay requires a token, which is used to validate merchant’s identity. The lifespan is 30 minutes.
TokenExpireDate String(20)
Token’s expiry date. Format: yyyy/MM/dd HH:mm:ss