Tillo API

https://tillo.tech/v2_docs/
Admin
The Tillo API allows businesses to issue and service digital and physical gift cards from a vast...
Tokens:1,976
Snippets:14
Trust Score:5.4
Update:3 months ago
Show doc for...
Tokens:
Raw
### Example Signature String

Source: https://tillo.tech/v2_docs

Construct the signature string before hashing. Replace placeholders with your actual API key, client request ID, and UTC timestamp. Use the correct brand identifier if not using Amazon.

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

--------------------------------

### Example Hashed Signature

Source: https://tillo.tech/v2_docs

This is the resulting hash of the signature string using your secret. This value is used in the 'Signature' request header.

```text
19694a0866b20938698e490d4ecd6f429e8e781d912451362e7a1ec174c6f59e
```

--------------------------------

### POST /api/v2/digital/issue

Source: https://tillo.tech/v2_docs

Initiates a digital issuance transaction to create a gift card URL.

```APIDOC
## POST /api/v2/digital/issue

### Description
This endpoint allows you to issue digital gift cards by making a POST request. It supports various parameters to customize the gift card, such as brand, face value, and delivery method.

### Method
POST

### Endpoint
`https://sandbox.tillo.dev/api/v2/digital/issue`

### Parameters
#### Request Body
- **client_request_id** (string) - Required - A unique identifier for the client's request, used for idempotency.
- **brand** (string) - Required - The slug or identifier of the brand for the gift card (e.g., "amazon").
- **face_value** (object) - Required - Specifies the amount and currency of the gift card.
  - **amount** (number) - Required - The value of the gift card.
  - **currency** (string) - Required - The ISO currency code (e.g., "GBP").
- **delivery_method** (string) - Required - The method for delivering the gift card (e.g., "url").
- **fulfilment_by** (string) - Required - Specifies whether Tillo should handle customer fulfillment (e.g., "partner").
- **sector** (string) - Required - The sector for this transaction.

### Request Example
```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}}"
}
```

### Response
#### Success Response (200)
- **code** (string) - The status code of the response (e.g., "000").
- **status** (string) - The status of the transaction (e.g., "success").
- **message** (string) - A message indicating the result of the transaction.
- **data** (object) - Contains details about the created gift card.
  - **brand** (string) - The brand of the gift card.
  - **url** (string) - The hosted gift card URL.
  - **face_value** (object) - The face value of the gift card.
    - **amount** (number) - The amount.
    - **currency** (string) - The currency.
  - **cost_value** (object) - The cost value of the gift card.
    - **amount** (number) - The amount.
    - **currency** (string) - The currency.
  - **discount** (number) - The discount applied.
  - **expiration_date** (string) - The expiration date of the gift card.
  - **reference** (string) - A reference identifier for the transaction.
  - **float_balance** (object) - The float balance.
    - **amount** (number) - The amount.
    - **currency** (string) - The currency.

#### Response Example
```json
{
  "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"
    }
  }
}
```
```

--------------------------------

### Successful Digital Issuance Response

Source: https://tillo.tech/v2_docs

This JSON response indicates a successful digital gift card creation. The key 'data.url' contains the hosted gift card URL to present to the customer. Note that 'cost_value' and 'float_balance' may show source currency for International Payments.

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

--------------------------------

### Request Headers for Digital Issue

Source: https://tillo.tech/v2_docs

These are the required headers for making a request to issue a digital gift card. Ensure you replace YOUR_API_KEY and YOUR_HASHED_SIGNATURE with your actual credentials and the generated hash.

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

--------------------------------

### Digital Issuance Request Body

Source: https://tillo.tech/v2_docs

This JSON object represents a minimal request to issue a £10.00 Amazon gift card URL. It includes essential parameters like client_request_id, brand, face_value, delivery_method, fulfilment_by, and sector.

```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}}"
}
```
Tokens:
Raw