TABLE OF CONTENTS



API documentation


The voucher API allows access to voucher tickets that are produced by Tixigo merchant account. A merchant can produce vouchers for its own use or he can produce them for other merchants that are Tixigo clients or not.


Tixigo clients get automatic support to redeem vouchers online in any of their activities. Other ticketing systems would have to support this API to do the same. A voucher ticket can also be scanned with the TixiScan mobile app at the merchant's premises but if the merchant targeted by the voucher wants to redeem vouchers online to produce a merchant specific ticket (free or not, this is specific to the goal of the voucher) then this API will provide the same end result as scanning the ticket with TixiScan.


For Tixigo merchants, a voucher behaves like a regular ticket except that the ticket number will be a unique random 8 to 12 hexadecimal character code instead of being the order number followed by up to 3 digits to represent the ticket sequence number within the order.


This API is meant to be used by third party ticketing systems only or merchants that have their own custom ticketing.


The voucher a RESTful API secured by an API key.


The current version of the API limits voucher to a single redemption.


All calls return a status code and a JSON or Text content:


If the API succeeds or fails but must return data then the JSON data is returned.


If the call has no specific data to return it returns a simple JSON object like this { "Message" :  "message here" }.


If the call produces a managed error then message can help get a bit more details about the error.


If the call produces an unmanaged error then an 400 (BadRequest) error with content being the error message.


API Key

You need an API key to access the API. There are two types of API keys in Tixigo: merchant and partner.


The merchant API key is shown in the Merchant Account page of the Tixigo portal and is meant to be used by a merchant that manages its own vouchers.


The partner API key is shown in the Partner page of the merchant account that manages the vouchers for one or many other merchants called partners. In this case, each voucher ticket category will be assigned to a specific partner which will ensure that only that partner can scan or use this API to consume a voucher tickets. If a Tixigo client is also a partner in some voucher program managed by another Tixigo client then he must also be a partner. He cannot manage vouchers produced by another merchant account with his merchant API key, he must use his partner key. This could change later on.


API Base URI


https://app.tixigo.com/api/voucher/v1


API headers 

All calls must have these two headers:

  1. Authorization = Basic encAPIkey 

where encAPIkey is the apikey encoded with the Base64 method

  1. Content-Type = application/x-www-form-urlencoded


TicketNumber

A voucher ticket number is a unique code to identify a voucher instance. Tixigo uses an 8 to 12 hexadecimal code for that. The number is required to redeem a voucher online.


TicketCategory

A voucher ticket number by itself does not tell the caller what it means. If there is only one type of voucher in use then it's obvious what it means but as soon as you have more than one type (voucher for an adult ticket and another one for a child one for instance) then the API must tell the caller what the voucher is redeemable for. The TicketCategory is how this API identifies a type or category of voucher.

For Tixigo merchants, the TicketCategory value is the actual number of the ticket category of the voucher so all vouchers produced with a given ticket category will get the same TicketCategory.


When a third party produces or sells vouchers for other merchants (partners), it must provide a list of TicketCategory to its partners and their ticketing system must provide a way to map such a code to a specific merchant ticket to redeem the voucher.


TransactionId

The API requires the caller to manage a transactionId that is a unique value used during a corresponding client transaction on his ticketing web site. It must be using across all Tixigo merchants so use a GUID for that otherwise you risk getting conflicted results.


Pricing Info


Some API calls return pricing information about the voucher. Since a voucher may be subject to different regulations in different countries, the pricing is required as merchants may have to refund part of the voucher or the redeemed ticket may be at a higher price than the voucher was meant for which would imply having to charge the customer an extra to match the new price. The pricing info is meant only for accounting purposes by the caller and not to show to the customer in any way.


The API handles two taxes named Tax1 and Tax2 which are generic names for local taxes. One, both or none of the taxes may be used, but they are available to support all use cases.


A voucher can have up to three pricing components: ticket, service and gratuity (tip). Each component can have taxes applied to them or not. The service component is the fee the customer paid to get the voucher and is normally non-refundable. The service fee must be explicit and not hidden in the ticket price to be returned by the API. Normally, vouchers should not have a service fee, but it's supported in case there is a need. The gratuity is used when it is mandatory and the voucher must cover the entire meal to redeem for instance. The service and gratuity components are included in the returned data only if they are not 0.


The total voucher price paid by the customer is the sum of all components and same goes for Tax1 and Tax2. Now whether some components were included or not in the ticket price presented to the customer is not important. This "official" price is available as the facePrice but it's only informative and cannot be used to compute anything as the facePrice could be the value of the good to redeem but the voucher is sold at a discount price!


Support for taxes per component is the most detailed way to calculate and handle taxes. This implies that taxes and other fees are calculated per voucher and not per order as it makes it more difficult to manage/redeem individual voucher.


Here are the JSON fields returned when the API refers to the pricingInfo:


currency : "value"The currency code for the amounts that follow following the ISO 4217 standard.
Ex. CAD for Canadian Dollar, USD for the US dollar, ...
facePrice : "value"The public price of the voucher as shown to the client on the ticket or displayed at the time of purchase. The price may include taxes and other fees.
ticketPrice : "value"The voucher price before any taxes or fees (service and gratuity).
ticketTax1 : "value"The amount of Tax1 taxes charged on the ticketPrice
ticketTax2 : "value"
The amount of Tax2 taxes charged on the ticketPrice
The following are included only if serviceFees is not 0
serviceFees : "value"
The service fees charged to the customer before taxes
serviceTax1 : "value"
The amount of Tax1 taxes charged on the service fees
serviceTax1 : "value"
The amount of Tax2 taxes charged on the service fees
The following are included only if gratuityFees is not 0
gratuityFees : "value"The amount of gratuity charged to the customer before taxes
gratuityTax1 : "value"
The amount of Tax1 taxes charged on the gratuity fees
gratuityTax1 : "value"The amount of Tax2 taxes charged on the gratuity fees



API References

lock

When a client enters a voucher number, you must ensure that it's valid and that it will not be used in another transaction or scanned with TixiScan. Locking a voucher lets you do just that. If you call the API but for some reason do not get the response (network or server glitch), you can call status to check whether the lock succeeded or not but you must also check that the transactionId is the same as it could be locked by another transaction.


HTTP methodPUT
Body parametersticketNumber : "value"Ticket number as indicated on the ticket. 8 to 12 hex characters.

lockDurationInMinutes : 3-30Lock the voucher ticket for that many minutes.
Must be between 3 and 30 minutes.

If you have more than one voucher in a transaction, then all vouchers locks are released only when the one with the latest unlock time must be released.

It may be an issue to lock a new voucher in a given transaction very close to the time that the last one locked and is about to been released. You should use a lock time that is at least 2 minutes longer than the time you give a client to complete a transaction on your web site.

transactionId: "value"Unique id associated with the ticket office current transaction. 
Status Codes200 - OKVoucher was locked

404 - Not FoundVoucher was not found or it belongs or the API key used cannot access it.

403 - ForbiddenVoucher is already locked or consumed

410 - GoneVoucher has been canceled

412 - PreconditionFailedInvalid parameters passed to the call
Returned data
For status codes 200 and 403 only

ticketNumber : "value"Same value as passed as argument

ticketCategory : "value"Identifier of the category or type of voucher

lockDate : "value"UTC date and time when voucher was locked

unlockDate : "value"UTC date and time when voucher will be auto released

transactionId : "value"Same as passed in parameters if 200 or actual value if 403. Calling voucher/status will provide a bit more info for 403.

pricingInfoCheck the pricing info section for details
Sample response

{

    "ticketNumber": "3E11AACF",

    "externalCode": "1773",

    "lockDate": "2020-08-29T22:29:57.2702521Z",

    "unlockDate": "2020-08-29T22:34:57.2702521Z",

    "transactionId": "8903d7770ea94c81a23f7a63247de644",

    pricingInfoHere

}


unlock

You can unlock a voucher with this API or use the cancel API instead to unlock all vouchers in a transaction. If you call this API and do not get a response for some reason then call the status API to get the status of the voucher and decide whether to call unlock again or not.


HTTP methodPUT
Body parametersticketNumber : "value"Ticket number as indicated on the ticket. 8 to 12 hex characters.

transactionId: "value"Unique is associated with the ticket office current transaction. 
Status Codes200 - OKVoucher was locked

404 - Not FoundVoucher was not found or it belongs or the API key used cannot access it.

412 - PreconditionFailedInvalid parameters passed to the call
Returned data
{ message : "message here" }
Sample response

{

    "message": "OK"

}


or 


{

    "message": "Forbidden"

}


status

To get the status of a voucher.


HTTP methodGEThttps://app.tixigo.com/api/voucher/status?ticketNumber=AE2C2F8
ParametersticketNumber="value"Ticket number as indicated on the ticket. 8 to 12 hex characters.
Status Codes200 - OKReturned data will contain the status

404 - Not FoundVoucher was not found or it belongs or the API key used cannot access it.

410 - GoneVoucher has been canceled

412 - PreconditionFailedInvalid parameters passed to the call
Returned data
For status codes 200 only

ticketNumber : "value"Same value as passed as argument

ticketCategory : "value"Identifier of the category or type of voucher

state : "value"One of "free", "locked" by this API or "scanned" by TixiScan or this API

lockDate : "value"UTC date and time when voucher was locked

unlockDate : "value"UTC date and time when voucher will be auto released

scanDate : "value"UTC date and time when the voucher was scanned. A voucher is in scanned state after being scanned by TixiScan or locked by this API and then the transaction is committed.

transactionId : "value"TransactionId that is currently locking the voucher or that redeemed it with a commit. null if TixiScan has consumed the voucher.

pricingInfoCheck the pricing info section for details
Sample response

{

    "ticketNumber": "3E11AACF",

    "ticketCategory": "1773",

    "state": "locked",

    "lockDate": "2020-08-29T22:29:57.27",

    "unlockDate": "2020-08-29T22:34:57.27",

    "scanDate": null,

    "transactionId": "8903d7770ea94c81a23f7a63247de644",

    pricingInfoHere...

}



cancel

To cancel all locked voucher tickets in a transaction. Same as unlocking every voucher one by one. If you call this API and do not get a response for some reason then call it again until you do.


HTTP methodPUT
Body parameterstransactionId="value"Unique id associated with the ticket office current transaction. 
Status Codes200 - OKVoucher was locked

404 - Not FoundVoucher was not found or it belongs or the API key used cannot access it.

412 - PreconditionFailedInvalid parameters passed to the call
Returned data
{ message : "message here" }
Sample response

{

    "message": "OK"

}


cancel (for beacon api)

Same as PUT version of cancel api but this one is required to work with the browser's beacon api that does not work with headers. If may be useful to cancel the current transaction upon closing the browser's tab although auto cancelation will be done after locks expire


HTTP methodPOSThttps://app.tixigo.com/api/voucher/cancel?transactionId=XXXXX&authorization=Basic...
Querystring parameterstransactionId: "value"Unique id associated with the ticket office current transaction. 

authorization="value"Value of the Authorization entry that would normally be in the header. "Basic encoded_apikey"
Status Codes200 - OKVoucher was locked

404 - Not FoundVoucher was not found or it belongs or the API key used cannot access it.

412 - PreconditionFailedInvalid parameters passed to the call
Returned data
{ message : "message here" }
Sample response

{

    "message": "OK"

}


commit

To commit all locked voucher tickets in a transaction. This makes the vouchers redeemed and it cannot be undone. If you call this API and do not get a response for some reason then call transactionStatus to decide whether the transaction was committed or not and possibly call commit again.


HTTP methodPUT
Body parameterstransactionId: "value"Unique is associated with the ticket office current transaction. 
Status Codes200 - OKVoucher was locked

404 - Not FoundVoucher was not found or it belongs or the API key used cannot access it.

412 - PreconditionFailedInvalid parameters passed to the call
Returned data
Array of vouchers that were redeemed
[   { ticketNumber : "value", ticketCategory : "value", pricingInfo }, ... ]
Sample response

[

    {

        "ticketNumber": "F5AC7C3F",

        "ticketCategory": "1773",

         pricingInfoHere...

    },

    {

        "ticketNumber": "D8954562",

        "ticketCategory": "1773",

         pricingInfoHere

    }

]


transactionStatus

To get the list of all vouchers redeemed by a transaction that was committed.


HTTP methodPUT
Body parameterstransactionId: "value"Unique is associated with the ticket office current transaction. 
Status Codes200 - OKVoucher was locked

404 - Not FoundVoucher was not found or it belongs or the API key used cannot access it.

412 - PreconditionFailedInvalid parameters passed to the call
Returned data
Array of vouchers that were redeemed
[   { ticketNumber : "value", ticketCategory : "value", pricingInfo }, ... ]
Sample response

[

    {

        "ticketNumber": "F5AC7C3F",

        "ticketCategory": "1773",

         pricingInfoHere

    },

    {

        "ticketNumber": "D8954562",

        "ticketCategory": "1773",

         pricingInfoHere

    }

]