Digital Gift Cards

Issue - Create a new digital gift card for a specific brand/value.
Cancel / reverse - Some retailers allow their gift cards to be cancelled via the API.
Balance Check - Some retailers provide real-time balance enquiries.
Check Stock - Used to check the current/live denomination availability of fixed-denomination brands.

Checking "stock"

While retailers do endeavour to ensure all denominations are always available there can be times when a specific denomination may not be available. We send out notifications when this occurs, but it can provide a more seamless experience for your customers if you implement this call and call periodically e.g. once per hour.

INFO

Not all Brands can be stock checked. If the gc_pool value in the Brand Information endpoint response is false, then you will not be able to check the stock of that Brand and will instead receive a validation error response.

Real-time or asynchronous?

When issuing digital gift cards you have two types of API call available to you - the one that you choose to use primarily depends on how you intend to deliver the gift card to the user.

Synchronous - this is the real-time API - the gift card (whether requested in the form of a Code or URL) will be returned in the API response.
Asynchronous - this is two-step process, first send your request, then send a second call to collect the gift card (typically available within seconds).

On the face of it the synchronous call may seem like the obvious choice - you get immediate access to the gift card requested after all, but there are benefits to using the asynchronous API if instant display of the gift card to the user isn't necessary.

Some brands only provide us with an asynchronous API - if you require the raw gift code (not a URL) this will only be available via the async endpoints.
If there is a short-lived issue with the brand's API, Tillo will retry on your behalf.
We will respond to your API request faster. Some brands' APIs are slower.

Identifying whether a brand is available synchronously

We have added an "async_only" flag on our brands call, which will return true if the brand is asynchronous, and false if the brand is synchronous. This flag allows you to determine whether or not you can request a code synchronously, and allows you the flexibility to implement both the asynchronous and synchronous endpoints.

Order Card async

The first request that you make will be to the order card endpoint. The request body for this is the same as our synchronous digital issuance endpoint. The response body, however is different. Instead of returning a code or URL, it will instead return a status, indicating whether or not we have received your order correctly. We will also return a reference to your order, which will be required when checking the status of your order.

Timeouts

You may not always have access to the reference from the response (such as when the request timed out). In which case you can replay the original transaction by putting through another order using the same client_request_id see Idempotency

Order Status

Order status is a GET request, which takes either the reference returned in the order card request or the original_client_request_id from your original order request. You can use either parameter, but not both together. This request will return a data.status of REQUESTED, PENDING, PROCESSING, SUCCESS or ERROR.

For asynchronous orders, this endpoint is a mandatory part of the process to retrieve the final gift card code or URL. For synchronous orders, this endpoint is typically not needed since the code/URL is returned immediately in the original response, but it can be useful if you experienced a timeout or network error during the original request.

Parameter Options

You can use either:

reference - The reference returned in the order card response (this is still supported and works as before)
original_client_request_id - The original client_request_id from your order request (useful when you don't have access to the reference)

Note: You cannot use both reference and original_client_request_id together in the same request.

Status	Description	Next Steps
`REQUESTED` `PENDING` `PROCESSING`	The order was submitted to Tillo successfully	Wait before making another order status check. See our throttling documentation.
`SUCCESS`	The order succeeded	The code or URL will be provided
`ERROR`	There was an unrecoverable issue with processing your order	We will have automatically refunded you for your transaction. In the majority of cases you will be able to order the code from us again.

Asynchronous brands via the Synchronous API

We understand that you may want to use the synchronous API endpoint for all brands, regardless of whether that brand only provides an asynchronous API - as long as you request 'URL' delivery you can do this. When you request a 'URL' we generate the unique URL before we've received the gift card, allowing you to provide this to your user while we work in the background to fetch the gift card and update.

The gift card is normally viewable on the URL within a few seconds but if there is any delay and the user views the URL before we've received the gift card a message is displayed asking them to check back later.

You cannot request the 'Code' delivery method of an asynchronous brand using the synchronous/real-time endpoint, you would have to use the asynchronous request.

Balance Check

We support balance check functionality for certain Brands via an API call to the check-balance endpoint.

INFO

Balance checking is not available on all Brands. You can determine whether a Brand supports the ability to balance check if the transaction_types field contains the balance_check value in the Brand Information endpoint response.

We offer balance check using a variety of identifiers; which identifier you use will be dependent on your use case but the reference or original_client_request_id from the issuance call are the most common. We provide examples for each case here Postman examples for Balance Check.

Displaying gift cards

It is very important that digital gift cards are displayed to the end user in the template that has been signed-off by the brand. The templates have been designed by or with the brand, and optimised to work well in email as well as being mobile-responsive to scale down to small screens, along with having specific redemption instructions or Terms & Conditions.

The simplest option is to either request the 'URL' from us or instruct us to email the digital gift card to your customer/user directly.

Alternatively you can use our Templates API to programmatically download every brand template and import in to your own system. This will ensure you are always using the latest version of the template. We strongly advise against manually maintaining the templates as they change on a regular basis (typically one per week receives an update).

TIP

If you are not using the URL delivery method or implementing the templates it is unlikely your API integration will be certified, unless you have a specific/unique use case or agreement from each brand you plan to issue.

Barcodes

Some retailers require a barcode or QR code and some of these retailers require manipulation of the gift code to produce the barcode 'number', such as having a prefix, dropping some digits, or adding the PIN. To remove this complexity from our clients we return the barcode information in our Issue response data.

json

"barcode": {
  "type": "CODE128",
  "string": "ABS1234567",
  "url": "https://revealyourgift.com/barcode?number=ABS1234567width=300&height=60"
}

"barcode": {
  "type": "CODE128",
  "string": "ABS1234567",
  "url": "https://revealyourgift.com/barcode?number=ABS1234567width=300&height=60"
}

You can choose to create the barcode within your own platform, based on the type and string (e.g. Code 128, "ABC1234567") or simply embed our returned Barcode URL in an img tag.

Fulfilment

You will need to tell us who should be delivering the digital gift card to the recipient.

To do this, set the fulfilment_by to'

rewardcloud if Tillo are sending the digital gift card to your recipient's email; or
partner if you are going to be delivering it (either via email or displayed in your application).

Email configuration

When using Tillo to send the email, you can specify the 'from' email address in your request. You can use our noreply@app.tillo.io address but most clients will want to use their own domain name to send the emails so that their users recognise the sender. Our mail service can make use of your domain by giving us authorisation to send on your behalf using DNS entries (DKIM & SPF records).

The steps to set this up are as follows;

Let Tillo know what domain you want to use.
Tillo will configure our mail service to be aware of your domain and supply you with DKIM and SPF records.
You add the DKIM record and update your SPF record.
Tillo send an authorisation email from the mail service - please forward that to onboarding@tillo.io.
Use the API to test the emails are received correctly.

TIP

Without following these steps, if you use your own domain in the 'from' address your emails will be rejected as they will appear to be spam.

Personalisation

Many of the brand templates support personalisation for the end recipient. This isn't appropriate for every use case, so the personalisation information is optional, but if you want to address the end recipient and add a personal message you can do so.

Available fields

To Name
From Name
Message

TIP

You can use a formal title & full name or just use part of their name e.g. Mr Bloggs, or Joe Bloggs or just Joe

Digital unwrapping

Tillo have a consumer-focussed digital unwrapping experience, Wrappr. Gift cards can be issued with a delivery method of 'wrapped' to return (or email) a URL that takes the user through this experience. The personalisation parameters are required in order to use this method - see the example available in the Postman documentation.

Signature