Ticketing Operations / Ticket Issuance

Scenario

Scenario 1: Issuing paper, electronic, or convenience store tickets

Before issuing tickets, the merchant must first complete the product listing on the Vendor Management System.After obtaining the product number, the merchant should then connect to the ECPay payment service via API to complete the order payment and issue the ticket using the order number from the merchant system.

Scenario 2: Issuing serial number-only tickets

In this scenario, only a serial number is obtained after the ticket issuance is complete, and the consumer does not receive any form of ticket.
There’s no need to list the product first; you can directly specify the product name and denomination for ticket issuance.
If using ECPay payment services, please first integrate the ECPay payment API to complete the order payment, then issue the ticket using the merchant order number corresponding to the payment order.

Special Note：

For paper tickets, issuing them through the “Ticket Issuance API” will execute the issuance immediately upon calling the API.
For electronic tickets, convenience store tickets and serial number-only tickets, the “Ticket Issuance API” only receives data, and the issuance process is subsequently handled through a scheduled job. The scheduled job is expected to be completed within 5 minutes.
The RtnCode parameter in the API response only represents the result of receiving the issuance data. Please call the “Query Ticket Issuance Results API” again to confirm whether the issuance was successful.

API URLs

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

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：

If the order includes a pick-up voucher, this field is required; if all the items in the order are gift vouchers, please do not fill in this field.
Merchant Transaction IDs are unique and can not be reused.
The value of this parameter is a combination of upper and lower case alphanumeric characters.

FreeTradeNo String(20)

Gift Vouchers Transaction ID.

Special Note：

If all the items in the order are gift vouchers, this field is required; if the order includes a pick-up voucher, please do not fill in this field.
Gift Vouchers Transaction IDs are unique and can not be reused.
The value of this parameter is a combination of upper and lower case alphanumeric characters.

IssueType String(1)
Required

Ticket issuing type.

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

PrintType String(1)

Printing method

1: Print by ECPay
2: Print by merchant

Special Note：

When IssueType=2 (paper ticket), this field is required.

IsImmediate String(1)

Is it available for immediate use

1: Immediate.It can be used immediately after issuance without setting an effective date [StartDate].
2: Non-immediate.The electronic ticket start date [StartDate] needs to be set, and the earliest start date can be set one day after the issue date. This is commonly used in pre-sale ticket scenarios.

Special Note：

When [IssueType]=3 (electronic ticket), this field is required.
Other types of ticket issuance do not require filling out this field, and the system is fixed to set it as immediate issuance.

RefundNotifyURL String(200)

URL for receiving refunded notifications.

When a pickup voucher order is refunded, the ECTicket Server will actively notify the platform merchant or store of the refund-related information via Server POST method.

Special Note：

This URL domain needs to apply for firewall access with ECPay in advance.
When pickup vouchers are included in the order, vendors must fill in this parameter to receive notifications for refunded orders.

UseStatusNotifyURL String(200)

URL for receiving redeemed or refunded notifications.

When the order is redeemed or refunded, the ECTicket Server will actively notify the platform merchant or store of the refund-related information via Server POST method.

Special Note：

This URL domain needs to apply for firewall access with ECPay in advance.
When pickup vouchers are included in the order, vendors must fill in this parameter to receive notifications for redeemed or refunded orders.

StoreID String(20)

The branch that issued this ticket. When this parameter is provided, the system will validate if the branch exists and is in an active state.

Special Note：

Please create the branch information in the 【ECPay Vendor’s Management System】 first and then provide us with the branch number.
※How to create branch data? Please refer to the Ticket Issuance Management Platform Operation Manual.
Limited to English letters and numbers only, and full-width characters are not allowed.
The length is restricted to 2 to 20 characters.
When the field is empty, it indicates that this record is issued by the main branch.

Operator String(10)
Required

The personnel who executed the issuance of this ticket, this field is 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.

CustomerName String(20)

Customer’s name.

Special Note：

When [IssueType]=3 (electronic ticket), this field is required.
When [IssueType]=2 (paper ticket), if paper tickets need to be sent to the customer, this field must be filled in.
Please only fill in pure Chinese or pure English, do not mix Chinese and English.
When the field contains data, at least two characters must be entered.

CustomerPhone String(10)

Customer’s phone.

Special Note：

When [IssueType]=3 (electronic ticket), this field is required.
Only numeric characters are allowed, and it must start with ’09’.
Only domestic mobile phone numbers are accepted.

CustomerEmail String(80)

Customer’s Email address.

Special Note：

When [IssueType]=1 (convenience store ticket) or [IssueType]=3 (electronic ticket), this field is required.

CustomerAddress String(100)

Customer’s address.

Special Note：

When [IssueType]=2 (paper ticket), if the merchant needs to send the paper ticket to the consumer, this field must be filled in.

TicketInfo Array[Object]

Ticket Information

ItemNo String(8)
Required

Product Number

Special Note：

When the ticket issuance type is not Serial number-only (Parameter [IssueType] is not equal to 4), this field is required.
The value of this parameter is a combination of upper and lower case alphanumeric characters.
The product number in the order cannot be reused.

ItemName String(20)

Product Name

Special Note：

When the ticket issuance type is serial number-only (Parameter [IssueType] equals 4), this field is required.
Length restriction: 4-20 characters.
Text is limited to Chinese, English, numbers, and special characters ()_/,.$%-
Full-width characters are not allowed.

TicketPrice Int

Ticket denomination.

Special Note：

When the ticket issuance type is serial number-only (Parameter [IssueType] equals 4), this field is required.
Denomination limit: NT$0 to NT$999,999,999.

TicketAmount Int
Required

The number of tickets issued.

Special Note：

When [IssueType]=1 (convenience store ticket), the total number of tickets issued per order is limited to a maximum of 8.
When the ticket issuance type is not a convenience store ticket ([IssueType] is not equal to 1), the total number of tickets issued per order is limited to a maximum of 100.

StartDate String(8)

The effective date of the ticket.

Refers to the date from which the ticket can be used.

Format: yyyymmdd

Special Note：

When [IsImmediate]=1 (immediate), this field is fixed as the date of ticket issuance.
When [IsImmediate]=2 (non-immediate), this field is required and must be greater than the date of ticket issuance.

ExpireDate String(8)

Expiration date of gift voucher.

format: yyyymmdd

Special Note：

This field is required and must be filled in only when the product is a gift voucher.
The date cannot be earlier than the ticket’s start date[StartDate].

Data Example (JSON format)

Copy

{
    "MerchantID": "2000132",
    "MerchantTradeNo": "CBX20220302153064851",
    "IssueType": "1",
    "UseStatusNotifyURL": "http://www.happybuy123.com.tw/notifyurl",
    "Operator": "AngelaChan",
    "CustomerEmail": "abc@gmail.com",
    "TicketInfo": [
         {
            "ItemNo": "VQT04959",  
            "TicketAmount": 4           
         },
         {
            "ItemNo": "VNS21400",  
            "TicketAmount": 4           
         }
    ]
}

Copy

{
    "MerchantID": "2000132",
    "MerchantTradeNo": "CBX20220302153064851",
    "IssueType": "2",
    "PrintType": "2",
    "UseStatusNotifyURL": "http://www.happybuy123.com.tw/notifyurl",
    "Operator": "AngelaChan",
    "CustomerName": "王珊珊",
    "TicketInfo": [
         {
            "ItemNo": "VQT04959",  
            "TicketAmount": 10           
         },
         {
            "ItemNo": "VNS21400",  
            "TicketAmount": 10           
         }
    ]
}

Copy

{
    "MerchantID": "2000132",
    "MerchantTradeNo": "CBX20220302153064851",
    "IssueType": "3",
    "IsImmediate": "2",
    "Operator": "AngelaChan",
    "CustomerName": "王珊珊",
    "CustomerPhone": "0912345678",
    "CustomerEmail": "abc@gmail.com",
    "TicketInfo": [
         {
            "ItemNo": "VQT04959",  
            "TicketAmount": 8,
            "StartDate": "20240101"           
         },
         {
            "ItemNo": "VNS21400",  
            "TicketAmount": 6,
            "StartDate": "20240101"           
         }
    ]
}

Copy

{
    "MerchantID": "2000132",
    "MerchantTradeNo": "CBX20220302153064851",
    "IssueType": "4",
    "UseStatusNotifyURL": "http://www.happybuy123.com.tw/notifyurl",
    "Operator": "AngelaChan",    
    "TicketInfo": [
         {
            "ItemName": "五星渡假飯店假日住宿券",  
            "TicketPrice": 6600,
            "TicketAmount": 2           
         },
         {
            "ItemName": "SPA課程體驗券",  
            "TicketPrice": 3200,
            "TicketAmount": 4           
         }
    ]
}

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.

Special Note：

This response code only represents the result of data reception. The ticket issuance process will be scheduled later, and the actual ticket issuance result can be confirmed by calling the [Query Ticket Issuance Results API].

RtnMsg String(200)

Response messages.

MerchantTradeNo String(25)

Transaction ID (provided by the merchant).

FreeTradeNo String(20)

Gift voucher order number

TicketTradeNo String(16)

Transaction ID (provided by ECTicket Management System).

TicketData Array[Object]

Ticket Information

ItemNo String(8)

Product Number

This parameter will only be returned when the ticket issuance type is not Serial number-only (Parameter [IssueType] is not equal to 4).

TicketAmount Int

The number of tickets issued.

ItemName String(20)

Product Name

This parameter will only be returned when the ticket issuance type is Serial number-only (Parameter [IssueType] equals 4).

TicketPrice Int

Ticket denomination.

This parameter will only be returned when the ticket issuance type is Serial number-only (Parameter [IssueType] equals 4).

TicketData Example (JSON format)

				
					{
    "RtnCode": 1,
    "RtnMsg": "success",
    "MerchantTradeNo":"CBX20220302153064851",
    "FreeTradeNo": "",
    "TicketTradeNo":"2022030215301234",
    "TicketData":[
        {
            "ItemNo":"BR103218",
            "TicketAmount":3
        },
        {
            "ItemNo":"CK851236",
            "TicketAmount":5
        }  
    ]
}

Green World