Scenario
Merchants can use this API to create new ticket products within the electronic ticketing service. The API allows merchants to configure basic product information, such as the product name and denomination, while also specifying which stores (merchants) are authorized to redeem the ticket product through the “AuthorizeList“. In addition, merchants can define usage instructions or important notices that consumers should be aware of before using the ticket through the “InstructionsList”.
This design is suitable for scenarios where a chain brand’s headquarters centrally creates ticket products and authorizes multiple affiliated stores to redeem them. Different usage instructions can also be provided based on the product type, supporting the issuance and management of ticket products across multiple stores and product categories.
API URLs
- Stage：https://ecticket-stage.ecpay.com.tw/api/Ticket/Addproducts
- Production：https://ecticket.ecpay.com.tw/api/Ticket/Addproducts
Message format
- Accept：text/html
- Content Type：application/json
- HTTP Method：POST
Request (JSON format)
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 (provided by ECPay)
RqHeader Object
Required
Timestamp Number
Required
Please convert the transmission time to a timestamp (GMT+8). ECPay will use this parameter to convert the current time to Unix Timestamp and verify the time interval of this API call.
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.
ProductImg String
A Base64-encoded string of the product image.
- Convert the product image to Base64 format before submitting it.
- Supported formats: JPEG / JPG / PNG; maximum file size: 5 MB. Recommended dimensions: 800 × 800 px.
Data Object
Required
Payload of JSON that has been encrypted.
CheckMacValue String
Required
Checksum
- Please refer to the Appendix Checksum Mechanism.
Request Example (JSON format)
{
"PlatformID": "3002599",
"MerchantID": "2000132",
"RqHeader": {
"Timestamp": 1525168923
},
"ProductImg":"Base64字串",
"Data": "…",
"CheckMacValue": "…"
}
Message payload of Data (JSON format)
Special Note: Please urlencode the JSON string firstly and then do AES encryption.
MerchantID String(10)
Required
Merchant ID (provided by ECPay)
MerchantProductNo String(13)
Required
The merchant-defined product number.
- Must be 1–13 alphanumeric characters.
TicketType String(1)
Required
Ticket Type
- 1: Pickup Voucher
- 2: Gift Voucher
ItemName String(20)
Required
Product Name
Length: 4–20 characters.
Only Chinese characters, half-width English letters, and half-width digits are allowed.
Use an underscore (
_) to separate English words if needed. Whitespace characters are not allowed.
ItemAmount Int
Required
The following rules apply based on the ticket type (TicketType):
- Pickup Ticket: Must be a positive integer with a maximum of 9 digits.
- Gift Ticket: Must be set to 0.
AuthorizeList Array[Object]
Authorization Settings List
Special Note：
- AuthorizeList is an optional parameter. If it is not provided, no redemption or refund authorization will be configured for the product. Only the merchant that created the product can perform redemption or refund operations.
- If AuthorizeList is provided, both [Type] and [StoreIDs] are required fields within each object.
Type String(1)
Required
Authorization Type
- 1: Cross-Store Redemption
- 2: Branch Store Redemption
- 3: Branch Store Refund
StoreIDs Array[String]
Required
Merchant/Store ID List
Provide the corresponding IDs based on the specified Type:
- Type = 1 (Cross-Store Redemption): Provide the Member ID (MID).
- Type = 2 (Branch Store Redemption): Provide the branch store IDs.
- Type = 3 (Branch Store Refund): Provide the branch store IDs.
InstructionsList Array[Object]
Required
Usage Instructions List
IssueType String(1)
Required
Ticket issuing type.
- 2: Paper ticket
- 3: Electronic ticket
Description String(100)
Required
Usage Instruction Content
- The following restrictions apply based on `IssueType`:
(1) IssueType = 2 (Paper Ticket): Each item can contain up to 50 characters. A maximum of 10 items is allowed, and at least 1 item is required.
(2) IssueType = 3 (Electronic Ticket): Each item can contain up to 100 characters. A maximum of 6 items is allowed, and at least 1 item is required. - General restriction: Full-width English letters and full-width digits are not allowed.
Data Example (JSON format)
{
"MerchantID":"2000132",
"MerchantProductNo": "A123456789012",
"TicketType":"1",
"ItemName":"商品名稱",
"ItemAmount":100,
"AuthorizeList":[
{"Type":"1","StoreIDs":[2000132,2000133]},
{"Type":"2","StoreIDs":[1234567,1234568]},
{"Type":"3","StoreIDs":[1234567]}
],
"InstructionsList":[
{"IssueType":"2","Description":"請於有效期限內使用"},
{"IssueType":"2","Description":"此票券僅限於指定門市使用"}
]
}
Response (JSON format)
PlatformID String(10)
The platform merchant’s member ID registered with ECPay.
MerchantID String(10)
The merchant ID assigned by ECPay.
RpHeader Object
Response header
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.
CheckMacValue String
Checksum
- Please refer to the Appendix Checksum Mechanism.
Response Example (JSON format)
{
"PlatformID": "3002599",
"MerchantID": "2000132",
"RpHeader": {
"Timestamp": 1525169058
},
"TransCode": 1,
"TransMsg": "",
"Data": "…",
"CheckMacValue": "…"
}
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.
ProductNo String(8)
The system-generated product number.
MerchantProductNo String(13)
The merchant-defined product number.
The system-generated product number.
{
"RtnCode":1,
"RtnMsg":"成功",
"ProductNo":"20240001",
"MerchantProductNo":"A123456789012"
}
Special Note:
- After a product is successfully created, its status is set to Active by default. The product status can be changed to Active or Inactive via the Update Product Information API.
- Upon successful creation, the API returns a ProductNo, which serves as the unique identifier for subsequent product updates and product status inquiries.