Ticketing Operations / Ticket Refund

Scenario

This API provides the functionality of ticket refund or cancellation of refund.

API URLs

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

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)

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.

Action String(1)
Required

Action type

1: Refund
2: Cancel refund

Special Note:

The gift voucher cannot be canceled once refund.

HandlingFeeRate Int

Rate of handling fee for product refund with pick-up voucher.

ECPay will calculate the handling fee for product refund based on this rate.

Special Note:

Gift vouchers and pick-up vouchers that have exceeded the fund custody period cannot be charged a handling fee for refunds. Therefore, this field can only be filled in with 0.
When [Action]=1, if a handling fee rate/amount needs to be specified, either this field or [HandlingFee] must be filled in, and only one can be selected to fill in. If not filled in, the default value is 0.
The last 2 digits represent decimal places, e.g., if the handling fee is 3.5%, please enter 350 in this field.
Because the handling fee cannot exceed or equal the face value of the ticket, the handling fee rate for refunds can only be entered as 0-9999 (representing 0%-99.99%).

HandlingFee Int

The handling fee amount for product refund.

Special Note:

Gift vouchers and pick-up vouchers that have exceeded the fund custody period cannot be charged a handling fee for refunds. Therefore, this field can only be filled in with 0.
When [Action]=1, if a handling fee rate/amount needs to be specified, either this field or [HandlingFeeRate] must be filled in, and only one can be selected to fill in. If not filled in, the default value is 0.
The refund handling fee amount must be less than the face value and cannot be a negative number.

Reason String(50)

Reason for cancellation of refund.

When the action is to cancel refund, the reason for cancellation can be provided.

StoreID String(20)

This is the branch responsible for processing ticket refunds or cancellations. When this parameter is provided, the system will check if the branch exists and is in an active state, and determine if it has the authority to handle ticket refunds or cancellations. If no authorization control is required, please do not fill in this field.

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

Execution personnel for ticket refund or cancellation, this field is for historical record only.

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",
    "TicketNo":"",
    "WriteOffNo":"LEU4loiSZ9TDTWAtxL",
    "Action":"1",
    "HandlingFeeRate":0,
    "HandlingFee":0,
    "Reason":"operational error",
    "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

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.

HandlingFee Int

Refund handling fee amount for pick-up voucher.

If the parameter for handling fee amount is specified, return the designated amount directly.
If the handling fee rate [HandlingFeeRate] is specified in the input parameter, it will be calculated by ECPay according to the following formula and returned. Calculation formula: face value of the pick-up voucher X specified rate (%) , rounded to the nearest integer after truncating the first decimal place.

Data Example(JSON format)

				
					{
    "RtnCode": 1,
    "RtnMsg": "success",
    "HandlingFee": 0
}

Special Note:

If the merchant needs to cancel a refund, it must be done before 23:59 on the day of the refund. The system will perform ticketing updates at 00:00 the day after the refund.
As the “pick-up voucher” that exceeds the fund custody period has been transferred to the merchant’s ECPay account balance upon expiration, in the event of a refund, the merchant should confirm the refund method with the consumer directly.

Green World