Query Operation / Query Ticket Detailed Information

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

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

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

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 (※Not yet available)
  • 3: Electronic ticket

InstructionsList 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].

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": ""
}

				
			

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

Green World