Scenario
Once a merchant’s ticket product has been listed, the merchant can use this API to update the redemption and refund permissions for an existing product by its product number (ProductNo).
The API allows merchants to configure the authorization list based on their business needs, including Cross-Store Redemption (allowing all branch stores under the same Member ID to redeem tickets), Branch Store Redemption (restricting redemption to specified branch stores), and Branch Store Refund (granting refund permissions to designated branch stores).
This API is suitable for chain brands that need to dynamically adjust redemption and refund permissions for specific products in response to store expansion, franchise partnership changes, or promotional campaigns. Merchants can update the authorization scope of their branch stores without having to create a new product.
API URLs
- Stage：https://ecticket-stage.ecpay.com.tw/api/Ticket/SetproductsAuth
- Production：https://ecticket.ecpay.com.tw/api/Ticket/SetproductsAuth
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.
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
},
"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.
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.
Data Example (JSON format)
{
"MerchantID":"2000132",
"ProductNo":"20240001",
"AuthorizeList": [
{"Type":"1","StoreIDs":["2000132","2000133"]},
{"Type":"2","StoreIDs":["1234567","1234568"]},
{"Type":"3","StoreIDs":["1234567"]}
]
}
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:
API Restrictions: This API only allows updates to product redemption and refund permissions. Other product information cannot be modified through this API. To update other product fields, please use the Update Product Information API.
StoreIDs Overwrite Behavior: The provided StoreIDs will overwrite the existing settings.
● Ensure that the provided data is correct to avoid incorrect permission configurations.
● To clear the existing settings (no stores specified or authorized), provide an empty array (`[]`).