ECTicket API Document

Query Operation / Query Order Information

Scenario

The merchant can use either the merchant order number [MerchantTradeNo] or the Gift Voucher order number [FreeTradeNo] to call this API to query order details.

API URLs

  • Stage: https://ecticket-stage.ecpay.com.tw/api/Ticket/QueryOrderInfo
  • Production: https://ecticket.ecpay.com.tw/api/Ticket/QueryOrderInfo

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

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

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)

MerchantTradeNo String(25)

❗ Special Note: 

  • Either this field or [FreeTradeNo] must be filled in,and only one of them can be filled.
  • The value of this parameter is a combination of upper and lower case alphanumeric characters.

FreeTradeNo String(20)

❗ Special Note:

  • Either this field or [MerchantTradeNo] must be filled in,and only one of them can be filled.
  • The value of this parameter is a combination of upper and lower case alphanumeric characters.

Data Example (JSON format)

				
					{
    "MerchantID": "2000132",
    "MerchantTradeNo":"CBX20220302153064851",
    "FreeTradeNo": ""
}

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

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 (provided by ECPay)

MerchantTradeNo String(25)

The Transaction Number provided by the merchant.

FreeTradeNo String(20)

Gift Vouchers Transaction Number.

TicketTradeNo String(16)

The Transaction Number provided by the ECTicket system.

PaymentProvider String(1)

The payment gateway service provider used for this order transaction.

  • 1：ECPay Payment Services

PaymentType String(1)

The payment method for this order transaction

  • 1：Credit Card

CreditTradeID Int

Credit card authorization number

Status Int

Ticket issuance result

  • 1: Issuance successful
  • 2: Issuance failed
  • 3: Issuance processing

Remark String(100)

Remarks on the issuance result.

When the issuance result is a failure (i.e., the parameter [Status] equals 2), this field will provide an explanation of the reason for the issuance failure.

IssueDate String(20)

Issuance date, format: yyyy/mm/dd hh:mm

IssueType String(1)

Ticket issuing type.

  • 1: Convenience store ticket
  • 2: Paper ticket
  • 3: Electronic ticket
  • 4: Serial number-only ticket

PrintType String(1)

Printing method for paper tickets:

  • 1: Print by ECPay
  • 2: Print by merchant
  • An empty string indicates it is not a paper ticket.

CustomerName String(20)

Customer’s name.

CustomerPhone String(10)

Customer’s phone.

CustomerEmail String(80)

Customer’s Email address.

EscrowExpiredDate String(8)

Escrow expiration date, format: yyyymmdd

TotalCount Int

Total count of tickets or serial numbers.

TradeAmount Int

Transaction amount

RedeemCount Int

Number of redeemed tickets or serial numbers.

RedeemAmount Int

Total amount of redeemed tickets or serial numbers.

RefundCount Int

Number of refunded tickets or serial numbers.

RefundAmount Int

Total amount of refunded tickets or serial numbers.

TotalRefundFee Int

Total return handling fees collected from consumers.

UnUsedCount Int

Total number of unused tickets or serial numbers.

UnUsedAmount Int

Total amount of unused tickets or serial numbers.

ExpiredCount Int

Number of expired tickets or serial numbers.

TicketList Array[Object]

List of tickets or serial numbers

Data Example(JSON format)

				
					{
    "RtnCode": 1,
    "RtnMsg": "Success"
    "MerchantID": "2000132",
    "MerchantTradeNo":"CBX20230302153064851",
    "FreeTradeNo":"",
    "TicketTradeNo":"2023061012345678",
    "CreditTradeID":12456789,
    "Status":1,
    "Remark":"",
    "IssueDate":"2023/06/10 10:35:21",
    "IssueType":"3",
    "PrintType":"",
    "CustomerName":"",
    "CustomerPhone":"",
    "CustomerEmail":"ABC123@gmail.com",
    "EscrowExpiredDate":"20231210",
    "TotalCount":3,
    "TradeAmount":9000,
    "RedeemCount":1,
    "RedeemAmount":3000,
    "RefundCount":2,
    "RefundAmount":600,
    "TotalRefundFee":80,
    "UnUsedCount":0,
    "UnUsedAmount":0,
    "ExpiredCount":0,
    "TicketList":[…]
}

Message payload of TicketList (JSON format)

TicketNo String(16)

Ticket serial numbers

UseStatus Int

Status of ticket serial numbers.

  • 1: Unused – indicates tickets that have not been used after issuance.
  • 2: Redeemed – tickets that have been used and redeemed.
  • 3: Refunded – tickets that have been refunded.
  • 4: Invalid – expired gift vouchers.

ItemNo String(8)

Item Number

  • The response will be returned only when the issuance type is Serial number-only (i.e., the parameter [IssueType] is not equal to 4).

ItemName String(20)

Item Name

TicketType String(1)

Ticket Type

  • 1: Pickup vouchers
  • 2: Gift vouchers

TicketAmount Int

Ticket face value

StartDate String(8)

Ticket start date for usability, format: yyyymmdd

WriteOffDate String(8)

Ticket redemption time, format: yyyymmdd hh:mm

RefundDate String(8)

Ticket refund time, format: yyyymmdd hh:mm

ExpiredDate String(8)

Expiration date of the gift voucher, format: yyyymmdd

WriteOffNo String(18)

Redemption code

  • The response will be returned only when the issuance type is Serial number-only (i.e., the parameter [IssueType] is not equal to 4).

TicketList Example(JSON format)

				
					[
    {
        "TicketNo": "CX12345600001",
        "UseStatus": 2,
        "ItemNo": "T00358",
        "ItemName": "Weekday accommodation voucher",
        "TicketType": "1",
        "TicketAmount": 1200,
        "StartDate": "20230501",
        "WriteOffDate": "20230601",
        "RefundDate": "",
        "ExpiredDate": "",
        "WriteOffNo": ""
    },
    {
        "TicketNo": "CX12345600002",
        "UseStatus": 2,
        "ItemNo": "T00358",
        "ItemName": "Weekday accommodation voucher",
        "TicketType": "1",
        "TicketAmount": 1200,
        "StartDate": "20230501",
        "WriteOffDate": "20230622",
        "RefundDate": "",
        "ExpiredDate": "",
        "WriteOffNo": ""
    },
    {
        "TicketNo": "CX12345600003",
        "UseStatus": 1,
        "ItemNo": "T00358",
        "ItemName":"Weekday accommodation voucher",
        "TicketType":"1",        
        "TicketAmount": 1200,
        "StartDate":"20230501",
        "WriteOffDate":"",
        "RefundDate":"",
        "ExpiredDate":"",
        "WriteOffNo":""
    },
    {
        "TicketNo": "CX12345600004",
        "UseStatus": 1,
        "ItemNo": "T00358",
        "ItemName": "Weekday accommodation voucher",
        "TicketType": "1",
        "TicketAmount": 1200,
        "StartDate": "20230501",
        "WriteOffDate": "",
        "RefundDate": "",
        "ExpiredDate": "",
        "WriteOffNo": ""
    }
]

Copyright © Green World FinTech Service Co., Ltd. All rights reserved.

Green World