Query Operation / Query Ticket Issuance Results

Scenario

The return result of electronic tickets and convenience store tickets in the [Ticket Issuance API] only represents the successful reception of ticket issuance data. ECPay will process ticket order creation and issuance in a scheduled job. After ticket issuance, you can call this API again to query the latest ticket issuance result.

API URLs

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

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

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

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)

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

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.

MerchantTradeNo String(25)

Transaction ID (provided by the merchant).

FreeTradeNo String(20)

Gift Vouchers Transaction ID.

Status Int

The issuance result.

1: Success
2: Failure
3: In Progress

Remark String(100)

Explanation of Issuance Result.

When [Status]=2 (Failure), the reason for the issuance failure will be explained in this field.

Data Example(JSON format)

				
					{
    "RtnCode": 1,
    "RtnMsg": "成功",
    "MerchantTradeNo":"CBX20220302153064851",
    "FreeTradeNo":"",
    "Status": 2,
    "Remark": "Error, please ensure that the transaction amount for this order matches the total amount of the products."
}

Green World