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}}"
}

{
  "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"
    }
  }
}

{
  "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"
    }
  }
}

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 and to download Postman collection, 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