Scenario
This API provides information about the product status, face value, etc. by querying the product number, in order to confirm whether the product can currently be issued as a ticket.
API URLs
- Stage: https://ecticket-stage.ecpay.com.tw/api/Ticket/QueryItemInfo
- Production: https://ecticket.ecpay.com.tw/api/Ticket/QueryItemInfo
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
RqHeader Object
Required
Request header
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
ItemNo String(8)
Required
Product Number
Data Example (JSON format)
{
"MerchantID": "2000132",
"ItemNo": "CHF80957"
}
Response (JSON format)
PlatformID String(10)
Platform ID
MerchantID String(10)
Merchant ID
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.
MerchantID String(10)
Merchant ID
ItemNo String(8)
Product Number
ItemName String(20)
Product Name
TicketType String(1)
Ticket Type
- 1: Pickup Voucher
- 2: Gift Voucher
ItemAmount Int
The face value of a ticket.
ItemStatus String(1)
The status of a product listing
- 0: out of stock
- 1: on the shelf
ModifyDate String(14)
The last modification time of this item.The format is: yyyymmdd hh:mm.
InstructionsList Object
This is a JSON format string that includes multiple pieces of ticket usage instruction data.
IssueType String(1)
Ticket issuing type.
- 1: Convenience store ticket
- 2: Paper ticket
- 3: Electronic ticket
Description String(100)
Return the ticket usage instructions for the specified ticket type based on the [IssueType].
Data Example(JSON format)
{
"RtnCode": 1,
"RtnMsg": "success",
"MerchantID":"2000132",
"ItemNo":"VTMT5062",
"ItemName":"Holiday meal voucher",
"TicketType":"1",
"ItemAmount":1200,
"ItemStatus":"1",
"ModifyDate":"20220801 15:30",
"InstructionsList":[
{
"IssueType":"1",
"Description":"Convenience store ticket instruction1"
},
{
"IssueType":"1",
"Description":"Convenience store ticket instruction2"
},
{
"IssueType":"1",
"Description":"Convenience store ticket instruction3"
},
{
"IssueType":"2",
"Description":"Paper ticket instruction1"
},
{
"IssueType":"2",
"Description":"Paper ticket instruction2"
},
{
"IssueType":"3",
"Description":"Electronic ticket instruction1"
},
{
"IssueType":"3",
"Description":"Electronic ticket instruction2"
},
{
"IssueType":"3",
"Description":"Electronic ticket instruction3"
}
]
}