Scenario
When consumers present their tickets, the BarCode on the ticket can be scanned to obtain the ticket number or redemption code. By calling this API, the usage status, start date, and other information of the ticket can be retrieved to verify whether the ticket can be redeemed or refunded.
API URLs
- Stage: https://ecticket-stage.ecpay.com.tw/api/Ticket/QueryTicketStatus
- Production: https://ecticket.ecpay.com.tw/api/Ticket/QueryTicketStatus
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
TicketNo String(16)
Ticket serial number.
Special Note:
- Either this field or [WriteOffNo] must be filled in.
WriteOffNo String(18)
Each ticket will have a unique redemption code that can be obtained by scanning the barcode of the ticket presented by the consumer.
Special Note:
- Either this field or [TicketNo] must be filled in.
Data Example (JSON format)
{
"MerchantID": "2000132",
"TicketNo":"CB2SY20220302153",
"WriteOffNo":""
}
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.
UseStatus Int
Ticket Usage Status
- 1: Unused – Indicates that the ticket has not been used after issuance.
- 2: Redeemed – The ticket status is marked as “redeemed” after it has been used.
- 3: Refunded – The ticket status is marked as “refunded” after the ticket has been returned.
- 4: Invalid – Indicates that the gift voucher has expired.
ItemNo String(8)
Product Number
ItemName String(20)
Product Name
TicketAmount Int
The face value of a ticket.
StartDate String(8)
The effective date of the ticket.
Refers to the date from which the ticket can be used.
- Format: yyyymmdd
ExpireDate String(8)
Expiration date of gift voucher.
- Format: yyyymmdd
EscrowExpireDate String(8)
The expiration date for the custody of the pickup voucher funds.
- Format: yyyymmdd hh:mm
WriteOffDate String(14)
The time for ticket redemption.
- Format: yyyymmdd hh:mm
RefundDate String(14)
The time for ticket refund execution.
- Format: yyyymmdd hh:mm
IssueType String(1)
Ticket issuing type.
- 1: Convenience store ticket
- 2: Paper ticket
- 3: Electronic ticket
- 4: Serial number-only ticket
InstructionsList Array[Object]
This is a JSON format string that includes multiple pieces of ticket usage instruction data.
Description String(100)
Return the ticket usage instructions for the specified ticket type based on the [IssueType].
MerchantTradeNo String(25)
Transaction ID (provided by the merchant).
FreeTradeNo String(20)
Gift Vouchers Transaction ID.
IssueMID String(10)
The merchant ID that issued this ticket.
IssueStoreID String(20)
The store ID that issued this ticket.If left empty, it means it was issued by the main store.
RedeemMID String(10)
The merchant ID that redeemed this ticket.If left empty, it means the ticket has not been redeemed yet. Please refer to the ticket use status [UseStatus].
RedeemStoreID String(20)
The store ID that redeemed this ticket.If left empty, it means this transaction was redeemed by the main store, or the ticket has not been redeemed yet. Please refer to the ticket use status [UseStatus].
RefundMID String(10)
The merchant ID that processed the refund, if left empty, it means the ticket has not been refunded. Please refer to the ticket use status [UseStatus].
RefundStoreID String(20)
The store ID that processed the refund, if left empty, it means this transaction was refunded by the main store, or the ticket has not been refunded. Please refer to the ticket use status [UseStatus].
WriteOffNo String(18)
Redemption serial code.
- It will only be returned when the ticket issuance type is serial number-only (Parameter [IssueType] equals 4).
Data Example(JSON format)
{
"RtnCode": 1,
"RtnMsg": "Success",
"UseStatus":2,
"ItemNo":"VQT04959",
"TicketAmount":200,
"StartDate":"20220302",
"ExpireDate":"",
"EscrowExpireDate":"20221231",
"WriteOffDate":"20220305 16:30",
"RefundDate":"",
"IssueType":"2",
"InstructionsList":[
{"Description":"Description1"},
{"Description":"Description2"},
{"Description":"Description3"}
],
"MerchantTradeNo":"CBX20220302153064851",
"FreeTradeNo": "",
"IssueMID": "2000132",
"IssueStoreID": "TP1001",
"RedeemMID": "2000132",
"RedeemStoreID": "TP1001",
"RefundMID": "",
"RefundStoreID": ""
}