TABLE OF CONTENTS

• API documentation
  • API Key
  • API Base URI
  • API headers 
  • TicketNumber
  • TicketCategory
  • TransactionId
• API References
  • lock
  • unlock
  • status
  • cancel
  • cancel (for beacon api)
  • commit
  • transactionStatus

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:

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.

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.

status

To get the status of a voucher.

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.

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

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.

transactionStatus

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