Scenario
Merchants can use the issue date to call this API and download order details and ticket details data.
Special Note:
- This API has a call frequency limit. The restriction is that each [MerchantID] can download only one CSV file per minute.
API URLs
- Stage: https://ecticket-stage.ecpay.com.tw/api/Ticket/OrderDetail
- Production: https://ecticket.ecpay.com.tw/api/Ticket/OrderDetail
Message format
- 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": "",
"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
ReportType Int
Required
The downloaded file types are:
- 1: Order details file
- 2: Ticket details file
BeginDate String(8)
Required
Start date for querying by issue date.
The maximum query period is 3 months, in the format: yyyymmdd.
EndDate String(8)
Required
End date for querying by issue date.
The maximum query period is 3 months, in the format: yyyymmdd.
Data Example (JSON format)
{
"MerchantID": "2000132",
"ReportType": 1,
"BeginDate": "20230601",
"EndDate": "20230630"
}
Special Note: When the parameter [ReportType] is set to 1, the CSV file downloaded contains “Order Details“.
Response CSV File Format Details (Chinese Only):
特店訂單編號 String
The Transaction Number provided by the merchant.
贈品單號 String
Gift Vouchers Transaction Number.
ECT訂單編號 String
The Transaction Number provided by the ECTicket system.
金流服務商 String
- 綠界金流: ECPay Payment Services
付款方式 String
The payment method for this order transaction
- 信用卡: Credit Card
Special Note:
- The field will return a value only when the order includes pickup vouchers among the issued tickets.
信用卡授權單號 Int
Credit card authorization number
發行狀態 String
Ticket issuance result
- 發行成功: Issuance successful
- 發行失敗: Issuance failed
- 發行作業處理中: Issuance processing
發行結果備註 String
Remarks on the issuance result.
When the issuance result is a failure, this field will provide an explanation of the reason for the issuance failure.
發行日期 String
Issuance date, format: yyyy/mm/dd hh:mm:ss
出券類型 String
Ticket issuing type.
- 超商票券: Convenience store ticket
- 紙本票券: Paper ticket
- 電子票券: Electronic ticket
- 純序號: Serial number-only ticket
列印方式 String
Printing method for paper tickets:
- 綠界列印: Print by ECPay
- 廠商列印: Print by merchant
- An empty string indicates it is not a paper ticket.
購買人姓名 String
Customer’s name.
購買人手機 String
Customer’s phone.
購買人Email String
Customer’s Email address.
履約保障到期日 String
Escrow expiration date, format: yyyy/mm/dd
訂單序號總數量 String
Total count of tickets or serial numbers.
訂單金額 String
Transaction amount
已核銷序號數量 String
Number of redeemed tickets or serial numbers.
已核銷總金額 String
Total amount of redeemed tickets or serial numbers.
已退貨序號數量 String
Number of refunded tickets or serial numbers.
已退貨總金額 String
Total amount of refunded tickets or serial numbers.
退貨手續費總金額 String
Total refund handling fees collected from consumers.
未使用序號數量 String
Total number of unused tickets or serial numbers.
未使用序號總金額 String
Total amount of unused tickets or serial numbers.
已失效票券數量 String
Number of expired tickets or serial numbers.
Special Note: When the parameter [ReportType] is set to 2, the CSV file downloaded contains “Tickets Details“.
Response CSV File Format Details:
特店訂單編號 String
The Transaction Number provided by the merchant.
贈品單號 String
Gift Vouchers Transaction Number.
ECT訂單編號 String
The Transaction Number provided by the ECTicket system.
信用卡授權單號 Int
Credit card authorization number
發行日期 String
Issuance date, format: yyyy/mm/dd hh:mm:ss
出券類型 String
Ticket issuing type.
- 超商票券: Convenience store ticket
- 紙本票券: Paper ticket
- 電子票券: Electronic ticket
- 純序號: Serial number-only ticket
列印方式 String
Printing method for paper tickets:
- 綠界列印: Print by ECPay
- 廠商列印: Print by merchant
- An empty string indicates it is not a paper ticket.
票券類型 String
Ticket Type
- 提貨券: Pickup Voucher
- 贈品券: Gift Voucher
購買人姓名 String
Customer’s name.
購買人手機 String
Customer’s phone.
購買人Email String
Customer’s Email address.
履約保障到期日 String
Escrow expiration date, format: yyyy/mm/dd
票券序號 String
Ticket serial numbers
票券使用狀態 String
Status of ticket serial numbers.
- 未使用: indicates tickets that have not been used after issuance.
- 已核銷: tickets that have been used and redeemed.
- 已退貨: tickets that have been refunded.
- 已失效: expired gift vouchers.
商品編號 String
Item Number
商品名稱 String
Item Name
票券面額 String
Ticket face value
票券生效日 String
Ticket start date for usability, format: yyyy/mm/dd
核銷日期 String
Ticket redemption time, format: yyyy/mm/dd hh:mm
退貨日期 String
Ticket refund time, format: yyyy/mm/dd hh:mm
退貨手續費 String
Refund handling fees
贈品券到期日期 String
Expiration date of the gift voucher, format: yyyy/mm/dd
核銷代碼 String
Redemption code
- The response will be returned only when the issuance type is Serial number-only.