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:

  • Authorization = Basic encAPIkey 

where encAPIkey is the apikey encoded with the Base64 method

  • Content-Type = application/x-www-form-urlencoded


TicketNumber

A voucher ticket number (aka voucher 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 or to give provide a discounted offer) 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, by default, the actual id of the ticket category of the voucher in the portal so all vouchers produced with a given ticket category will get the same TicketCategory. Merchant could also set a specific code or name instead of using the implicit id.


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.


Voucher Value


The value of a voucher is expressed in a specific currency and represent the amount paid for the voucher. The value is required beause a voucher may be subject to different regulations in different countries. Depending on how a voucher is redeemed, it may incur some extra fees or provide a refund of its value.


If a voucher is expired then the api call will return an explicit error.


The value of a voucher may be garantied for a specific period of time or not - it depends on the vendor. The concept of garantied value is often used when using vouchers to tell the bearer that the service or good he will get when redeeming a voucher is garantied until a specific date. After that period, if the good or service to redeem has increased in price then the bearer must pay the difference. The garantied value period is controlled by the provider of this API and therefore a field will indicate whether that date is past or not. It's up to the caller to decide how to handle that situation if the redemption should incur an extra fee or not.


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, ...
garantiedValue: true, false
true means that the redemption should not incur any extra fees to get the service of product the voucher is intended for

false means that extra fees could be charged if the good or service is more expansive than the value of the voucher.
value : "value"The value of the voucher



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

    }

]