This short guide's aim is to get you going with the least amount of work possible.

By the end of this guide, you should be able to successfully issue a digital gift card.

If you're looking for more detailed explanations or want to view advanced features of our API, please check out the main API Documentation page.

Before you begin

Make sure you can access the Tillo Sandbox environment.

📘
TIP
One of the engineers at Tillo should have already set this up, but you may need to contact another member of your team and ask them to create a user for you with the API Admin role enabled.

Once you've logged in, add your IP Address to the IP Whitelist
Make a note of your Sector, on the Sectors tab on the same page that you added your IP Address.
Create an API Key and Secret
Finally, go and find a brand you want to issue a giftcard for on the Brands page. You'll see a list of brands available to you right away on the Your brands tab. Note down the identifier/slug for the brand you choose — you'll need this later.

Authentication

Tillo's authentication system is based on the HMAC process, where a signature string is built up using information from the request body and hashed using your Secret from the previous step.

As we're going to be making a request for a digital gift card using the /digital/issue endpoint, the signature string should be made from the following elements:

API Key
HTTP Method
endpoint slug
client request ID
brand identifier
UTC Timestamp in milliseconds

Client Request ID

The Client Request ID should be unique for every request you make, so using something like a uuid or random hashed string can work well.

📘
TIP
The Client Request ID must contain only alphanumeric characters including hyphens and underscores and be between 5 and 50 characters in length.

Signature String

The signature string is made from the elements listed above concatenated into one string with dashes between each.

In this example, we'll make a request for an Amazon gift card. This means the signature string (before it is hashed), should look like this:

[api_key]-POST-digital-issue-[client_request_id]-amazon-[utc_timestamp]

Put your api_key, client_request_id, and the utc_timestamp into your string. If you're using a different brand, you will also need to replace the brand identifier.

Next, hash the signature string using your Secret:

19694a0866b20938698e490d4ecd6f429e8e781d912451362e7a1ec174c6f59e

🚧
WARNING
As the Client Request ID and timestamp will be different each time you make a request, you must re-calculate your signature string before each request.

📘
TIP
We built a tool to help you figure out what to include in your signature string, check it out:
Signature Builder

Request Headers

Your request headers should look like this:

Content-Type: "application/json"
Accept: "application/json"
API-Key: YOUR_API_KEY
Signature: YOUR_HASHED_SIGNATURE
Timestamp: CURRENT_UTC_TIMESTAMP_IN_MILLISECONDS

Make the request

Now it's time to make the request!

Endpoint and HTTP Method

You'll need to make POST request to the URL below in order to make your Digital Issuance transaction:

https://sandbox.tillo.dev/api/v2/digital/issue

Request body

In this example, we're keeping things as simple as possible, so our request will only contain the required parameters.

We want a £10.00 (GBP) Amazon gift card URL so we need to send the following JSON:

{
  "client_request_id": "{{CLIENT_REQUEST_ID}}",
  "brand": "amazon",
  "face_value": {
    "amount": 10.0,
    "currency": "GBP"
  },
  "delivery_method": "url",
  "fulfilment_by": "partner",
  "sector": "{{YOUR_SECTOR}}"
}

For a Digital Issuance request, you are required to provide:

Client Request ID (client_request_id)
Brand slug/identifier (brand)
Value (face_value.amount)
Currency ISO Code (face_value.currency)
Delivery method (delivery_method)
Whether you need Tillo to email your customer (fulfilment_by)
The sector for this transaction (sector)

Idempotency

Our API supports idempotency when issuing, and cancelling, digital and physical gift cards. We use your unique
client_request_id as an idempotency key, and replay back the original response when the same client_request_id is
re-used. This can be useful when there was a timeout, or networking issue, and you did not receive the
original response, allowing you to safely replay the original transaction without the risk of double orders.

Response

If everything worked correctly and you didn't receive an error in response, you should get a response that looks something like this:

{
  "code": "000",
  "status": "success",
  "message": "Card created successfully",
  "data": {
    "brand": "amazon",
    "url": "https://sandbox.revealyourgift.com/ef9b0117-4693-4904-8517-3bda29e9383c/d3fde268-b39a-4b4b-84b0-fbbccf0ead34",
    "face_value": {
      "amount": 10,
      "currency": "GBP"
    },
    "cost_value": {
      "amount": 7,
      "currency": "GBP"
    },
    "discount": 3,
    "expiration_date": "2030-10-12T22:59:59+00:00",
    "reference": "a491f1f0-0c75-11eb-af67-09b215648e5c",
    "float_balance": {
      "amount": 113148.57,
      "currency": "GBP"
    }
  }
}

The key field is data.url, which contains the hosted gift card URL you can present to your customer.

🚧
WARNING
If you are using International Payments, the values for cost_value amount will instead show the
source currency and source currency cost, and float_balance will instead show the source currency and source currency float balance.
This will be true for both Digital Issue (Sync) and Digital Order (Async).

What next?

Hopefully this short guide has served as a good starting point and you've managed to make a successful request for a brand of your choosing.

For more detailed explanations the subjects covered here and for other features of Tillo's API, check out the main API overview page here.

And to read more detailed examples, visit our API reference

If you get stuck, need more detail, or have any feedback regarding the documentation we provide, please let us know by emailing the onboarding team