Scenario
After a product has been created, merchants can use this API to update an existing ticket product by its product number (ProductNo). The API allows merchants to update product information, including the product image, product name, denomination, product status (ItemStatus), and usage instructions (InstructionsList) that consumers should be aware of before using the ticket.
API URLs
- Stage：https://ecticket-stage.ecpay.com.tw/api/Ticket/Updateproducts
- Production：https://ecticket.ecpay.com.tw/api/Ticket/Updateproducts
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)
ProductNo String(8)
Required
The system-generated product number.
MerchantProductNo String(13)
Required
The merchant-defined product number.
- Must be 1–13 alphanumeric characters.
ItemStatus String(1)
Product Status
- 0：Inactive
- 1：Active
TicketType String(1)
Ticket Type
- 1: Pickup Voucher
- 2: Gift Voucher
ItemName String(20)
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
The face value of a ticket.
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.
InstructionsList Array[Object]
Usage Instructions List
Special Note：
- If InstructionsList is provided, both IssueType and Description are required fields within each object.
- If InstructionsList is provided, all existing usage instructions will be removed and replaced with the newly provided settings. For example, if three instructions are currently configured and only two are provided in the update request, the existing three instructions will be removed and replaced with the two newly provided instructions.
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",
"ProductNo":"20240001",
"MerchantProductNo":"A123456789012",
"ItemStatus":"1",
"TicketType":"1",
"ItemName":"商品名稱",
"ItemAmount":100,
"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.
The system-generated product number.
{
"RtnCode":1,
"RtnMsg":"成功"
}
Special Note:
Update Restrictions:Once a product has been created and an issuance record exists, the following fields can no longer be modified:
● Merchant Product Number [MerchantProductNo]
● Product Status [ItemStatus]
● Ticket Type [TicketType]
● Product Name [ItemName]
● Product Amount [ItemAmount]
● Product Image [ProductImg]
● Usage Instructions [InstructionsList]When using the Update API, omit any parameter that does not need to be updated, or pass null if supported by the API. The system only updates parameters that are provided and comply with the required format. If an empty string (“”) or any other valid value is provided, the system will treat it as an update instruction and overwrite the existing value accordingly. Please ensure that only the fields intended to be updated are included in the request.