Query Operation / Get Paper Ticket Information

Scenario

※Paper ticket issuance is currently not available.

  • This API allows POS vendors to retrieve the necessary data for printing paper tickets using the merchant order number. However, please note that only unused tickets will be provided for printing. After obtaining the ticket information, POS vendors can format the tickets using the ticket template provided by ECPay and send them to the ticket printer for printing.

API URLs

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

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)

Transaction ID (provided by the merchant).

❗ 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)

Gift Vouchers Transaction ID.

❗ 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.

Operator String(10)
Required

The personnel who operate this query data are only used for historical records.

❗ Special Note:

  • The value of this parameter is a combination of upper and lower case alphanumeric characters,and do not use full-width fonts.

Data Example (JSON format)

				
					{
    "MerchantID": "2000132",
    "MerchantTradeNo": "CBX20220302153064851",
    "Operator":"LeoWang"
}

				
			

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

TicketData Object

This is a JSON format string that includes multiple pieces of ticket information.

TicketNo String(16)

Ticket serial number.

ItemName String(20)

Product Name

TicketType String(1)

Ticket Type

  • 1: Pickup voucher
  • 2: Gift voucher

TicketAmount String(9)

The face value of a ticket.

Instructions1 String(50)

Ticket usage instruction.

Instructions2 String(50)

Ticket usage instruction.

Instructions3 String(50)

Ticket usage instruction.

Instructions4 String(50)

Ticket usage instruction.

Instructions5 String(50)

Ticket usage instruction.

Instructions6 String(50)

Ticket usage instruction.

Instructions7 String(50)

Ticket usage instruction.

Instructions8 String(50)

Ticket usage instruction.

Instructions9 String(50)

Ticket usage instruction.

Instructions10 String(50)

Ticket usage instruction.

Instructions11 String(50)

Ticket usage instruction

  • Applicable only for gift vouchers.

ReturnPolicy String(34)

Refund policy explanation

  • Applicable only for pickup vouchers.

Notice String(144)

Important Notes

IssuingUnit String(20)
 

Issuing Unit

❗ Special Note:

  • Due to the layout constraints of physical paper vouchers, if the issuing unit string set by the merchant exceeds a certain length, only the first 20 characters will be automatically extracted and returned.

PersonInCharge String(10)

Person In Charge

TaxIDNumber String(8)

Unified Business Number

CSHotline String(12)

Customer Service Phone

Address String(40)

Company Address

❗ Special Note:

  • Due to the layout limitations of physical vouchers, if the address string set by the merchant exceeds a certain length, only the first 40 characters will be captured and returned.

EscrowAgent String(12)

Custodian Institution

  • Applicable only for pickup vouchers.

EscrowDate String(21)

Period of fund custody

  • Applicable only for pickup vouchers.
  • Format: YYYY/MM/DD-YYYY/MM/DD

EffectiveDate String(21)

Ticket Effective Date

  • Applicable only for gift vouchers.
  • Format: YYYY/MM/DD-YYYY/MM/DD

TicketQRCode String(30)

The QRCode URI contains the shortened URL of the redemption page.

TicketBarcode String(18)

The barcode content is the redemption code generated using the Code 128 encoding scheme.

IssuingUnitLogo String(200)

The URL of the logo image file of the issuing unit.

Data Example(JSON format)

				
					{
    "RtnCode": 1,
    "RtnMsg": "success",
    "MerchantID":"2000132",
    "TicketData":[
        {
            "TicketNo":"CB2SY20220302153",
            "ItemName":"Spa Massage Voucher",
            "TicketType":"1",
            "TicketAmount":"999",
            "Instructions1":"nstructions1…",
            "Instructions2":"nstructions2…",
            "Instructions3":"nstructions3…",
            "Instructions4":"nstructions4…",
            "Instructions5":"nstructions5…",
            "Instructions6":"",
            "ReturnPolicy":"ReturnPolicy…",
            "Notice":"Notice…",
            "IssuingUnit":"Hot Springs Resort Hotel",
            "PersonInCharge":"David Lin",
            "TaxIDNumber":"12345678",
            "CSHotline":"0800000000",
            "Address":"No.35,Houtong Rd.,Ruifang Dist.,New Taipei City",
            "EscrowAgent":"TaipeiFunbon",
            "EscrowDate":"2022/01/01-2022/12/31",
            "EffectiveDate":"",
            "TicketQRCode":"CB2SY20220302153",
            "TicketBarcode":"AAAA12345678912345",
            "IssuingUnitLogo":"https://www.ecpay.com.tw/image123.jpg"
        }
  ]
}

				
			

❗ Special Note:

  • We recommend using the 【Aclas Printer】and setting the paper size to 7cm x 17.78cm.

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

Green World