Getting Token / Getting Token by Trade

Scenario

Before using ECPay’s Embedded Checkout Page, merchant’s server should call ECPay’s API to get a Token. After receiving the token, merchants should set this token onto merchant’s webpage with the integration of ECPay’s JavaScript SDK to access the checkout page. ECPay will then validate this token to check merchant’s identity before displaying the checkout page.

API URLs

Stage: https://ecpg-stage.ecpay.com.tw/Merchant/GetTokenbyTrade
Production: https://ecpg.ecpay.com.tw/Merchant/GetTokenbyTrade

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

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

RememberCard Int
Required

Whether to use saving card function (autofill).
Values could be:

0 : Not to use the saving card function
1 : To use the saving card function

PaymentUIType Int
Required

UI type of payment–which UI of payment is goinf to be displayed. ECPay will display which UI to be displayed according to the value sent to ECPay’s API endpoint.
Values include:

0 : subscription plan only (credit card recurring/repeated payment)
2 : list of other payment methods

Special note:

UniPay does not support the function of repeated payment.
Foreign card support the function of repeated payment if the merchant apply with Green World.
The repeated payment supports only VISA/MasterCard/JCB.

ChoosePaymentList String(30)

Payment method.If PaymentUIType: 2 (listing of other payment methods), this parameter will be required.
Values include:

0 : all payment methods
1 : credit card payment all at once (a lump-sum payment)
2 : credit card installments
3 : ATM (pay by bank’s virtual account number)
4 : CVS code (pay by convenience store reference number)
5 : BARCODE (pay by convenience store barcode)
6 : UnionPay card payment
7 : Apple Pay
8 : Flexible Installment

Special note:

This is a multi-value parameter, which can be populated with more than one value. For example, ChoosePaymentList: 1,2,3
For those who want to integrate Apple Pay into webpage, it is no need to apply for an Apple Developer account.
If your membership type is ECTicket member, the payment methods available to you can be confirm in the ECPay’s merchant’s dashboard > Contracts & Rates > Payment.

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

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.

TradeDesc String(200)
Required

Description of order

ItemName String(400)
Required

Name of products

Each product should be separated by a hash (#).

CardInfo Object

Credit card information.Required if the following 2 conditions:

PaymentUIType: 0 or 1
PaymentUIType: 2, and ChoosePaymentList: 0, 1 or 2

Redeem String(1)

Whether to use credit card bonus.

0: Not to use (default)
1: To use

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).

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.

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.

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

FlexibleInstallment String(20)

Periods (cycles) of credit card installment plan.

Required if ChoosePaymentList: 0 or 8.
The period of installments set to this parameter is different from CreditInstallment. The value set could be found on ECPay’s dashboard.
Possible values: 30

Special note: The transaction amount must be greater than the minimum amount of flexible installment, which is set and can be found on ECPay’s dashboard.

UnionPayInfo Object

UnionPay information. Required if ChoosePaymentList: 0 or 6.

OrderResultURL String(200)

A URL of merchant’s webpage on client-side to receive UnionPay payment result.

When consumer completes UnionPay 3DS authentication, ECPay will redirect the payment result to this URL.
Details about the data returned please see the chapter of Notifications.

ATMInfo Object

ATM information.

ExpireDate Int

Required if ChoosePaymentList: 0 or 3 (ATM).
If not set the default value is 3 (i.e. payment should be made in 3 days). The maximum is 60 days, while the minimum is 1 day.
The unit is in day.

Special note: The unit is in days.

ATMBankCode String(10)

Bank code

If not set, the value will be the system default.
Please see bank code list.

CVSInfo Object

CVS payment information

StoreExpireDate Int

Required if ChoosePaymentList: 0 or 4 (CVS payment).
The unit is in minute.
If not set, the default value is 10080 minutes (7 days). The value should not exceed 43200 minutes (30 days). If over 43200, the maximum will still be 43200 minutes.

Special note: For example, if a consumer place an order at 20:15 on Aug 1^st, the StoreExpireDate=7 (7 days), this consumer must pay at the convenience store before 20:15 on Aug 8^th.

CVSCode String(10)

A serial number that for consumer to pay at convenience store.

CVS : to pay at any convenience store (default)
OK : to pay at OK mart.
FAMILY: to pay at FamilyMart.
HILIFE : to pay at Hi-Life
IBON : to pay by ibon (7-11’s kiosk)

Desc_1 String(20)

Transaction description 1. If CVSCode= FAMILY or IBON (which is to be paid at 7-11), this value will be displayed on the kiosk.

Desc_2 String(20)

Transaction description 2. If CVSCode= FAMILY or IBON (which is to be paid at 7-11), this value will be displayed on the kiosk.

Desc_3 String(20)

Transaction description 3. If CVSCode= FAMILY or IBON (which is to be paid at 7-11), this value will be displayed on the kiosk.

Desc_4 String(20)

Transaction description 4. If CVSCode= FAMILY or IBON (which is to be paid at 7-11), this value will be displayed on the kiosk.

BarcodeInfo Object

BARCODE payment information.

StoreExpireDate Int

Convenience store payment deadline.

Required if ChoosePaymentList=0 or 5
The unit is in day. The default value is 7 days.
Setting maximum 30 days, minimum 1 day.
If you want to set more than 30 days, you can only apply for it with your business.

ConsumerInfo Object

Consumer information

MerchantMemberID String(60)

Consumer’s ID (if merchant has a member system).

Required if RememberCard: 1 (using the saving card function)

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)

				
					{
    "MerchantID": "3002607",
    "RememberCard": 1,
    "PaymentUIType": 2,
    "ChoosePaymentList": "1,2,3",
    "OrderInfo": {
        "MerchantTradeNo": "20180914001",
        "MerchantTradeDate": "2020/09/26 14:49:12",
        "TotalAmount": 100,
        "ReturnURL": "https://yourReturnURL.com"
   },
    "CardInfo": {
        "OrderResultURL": "https://yourOrderResultURL.com",
        "CreditInstallment": "3,6,12"
    },
    "ATMInfo": {
        "ExpireDate": 3
    },
    "ConsumerInfo": {
        "MerchantMemberID": "test123456",
        "Email": "customer@email.com",
        "Phone": "0912345678",
        "Name": "Test",
        "CountryCode": "158"
    }
}

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)

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

Data Example(Json format)

				
					{
    "RtnCode": 1,
    "RtnMsg": "Success",
    "PlatformID": "1234567890",
    "MerchantID": "1234567890",
    "Token": "m12dae4846446sq",
    "TokenExpireDate": "2020/09/18 15:39:10"
}

Green World