Gifty API.

Welcome to the Gifty API documentation. This documentation provides you with all the necessary information to communicate with our API. If you want to use our API you must register your application via the Gifty dashboard.

If you have any questions, don't hesitate to reach out. You can contact us via our contact page.

Introduction

The following section describes generic usage information on the Gifty API.

Authentication

Send the provided token as a header with your requests. You can create an API token on the developer's page in your dashboard.

Authorization: Bearer REPLACE_WITH_YOUR_PRIVATE_TOKEN

Error Handling

If there are validation issues or other unexpected events, an error will be thrown in the format shown below. Along with the request, a corresponding HTTP header is sent.

Code Meaning
2XX Successful request
4XX The request is invalid. For example, because the requested resource does not exist. These errors are expected and should be gracefully processed.
5XX Ouch. Most likely, something went wrong on our end. We received a notification, but please get in touch with us with additional information about the issue.
Response
          {
  "message": "The transaction tr_kOWB2x0QVvE8GYn6GX7p1oL9 has been captured or released already.",
  "errors": [
    {
      "id": "9fb1f6880a844a72b7fbd9bb5ee10d87",
      "status": "422",
      "type": "giftcard_transaction_error",
      "title": "Giftcard transaction error",
      "detail": "The transaction tr_kOWB2x0QVvE8GYn6GX7p1oL9 has been captured or released already."
    }
  ]
}
              
      

Localization

The API's validation error messages are available in both English and Dutch. The default language used is English. If you want Dutch validation errors, send the header below with your request.

Accept-Language: nl

Rate Limiting

The API is limited to 120 requests per minute. If you exceed this limit, access to the API will be temporarily disabled. Please get in touch with us if you think this limit does not meet your requirements.

Pagination

For all responses that can return multiple objects, cursor pagination is available. You can send the cursor_before parameter to navigate through the pages on these requests. Use the limit parameter to set the number of results per page. You can use the ID of objects as the cursor.

If you need to become more familiar with cursor pagination, it might confuse you first. Cursor pagination is more efficient and predictable than offset pagination. Let's take a look at the example below. We paginate through the list of four locations, show two results per page and do not pass a cursor. So we see the two most recent results.

Now we want to navigate to the following result set to see location 2 and location 1. We pass the last known cursor lc_tOWRgGnbJs0pey3MfHPWjuge to parameter cursor_before.

Cursor pagination example

Currencies

While processing transactions on a gift card, you should provide the currency code of the gift card in the ISO 4217 format. The currencies listed in the table below are supported.

Code Currency
EUR Euro

Gift Cards

In most use cases, gift cards are the most important objects using the Gifty API. Gift cards represent a monetary value. You activate the card and add a balance by issuing a gift card (credit). Later, redeeming a gift card reduces the balance (debit).

The Gift Card object

Attribute Type Description
id string Unique identifier for the card.
balance integer The current balance of the card, in cents. A negative balance is not possible.
currency string ISO 4217 code of the currency. All transactions on this card are required to be made in the same currency.
promotional boolean True if the card is marked as promotional.
is_redeemable boolean Indicates if a new redeem transaction can be made on the card. This attribute is false if there is no balance left or if the card is expired.
is_issuable boolean Indicates if a new issue transaction can be made on the card. This attribute is false if there are transactions made on this card already.
is_extendable boolean Indicates if an expired gift card can be re-activated. This attribute is false if the gift card has not expired or if re-activation is not allowed.
expires_at string or null ISO 8601 time of expiration or null if the gift card won't expire.
created_at string ISO 8601 time of creation.
package string or null The corresponding package ID.
transactions All corresponding transactions made on the card.
images URLs to images that visualize the card.

GET Retrieve Gift Card

https://api.gifty.nl/v1/giftcards/:giftcard

The Gift Card object can be retrieved by providing the gift card code.

Request
          
                          GET /v1/giftcards/AAAABBBBCCCCDDDD HTTP/1.1
              Host: api.gifty.nl
              Accept: application/json
              
          
      
Response
          {
  "data": {
    "id": "gc_e7V83D5N6An7OgnPJgKlqoyz",
    "balance": 4000,
    "currency": "EUR",
    "promotional": false,
    "is_redeemable": true,
    "is_issuable": false,
    "is_extendable": false,
    "expires_at": "2027-09-15T12:42:42+00:00",
    "created_at": "2022-09-15T12:41:31+00:00",
    "transactions": [ ...TransactionObject ],
    "images": [
        {
            "type": "FRONT_SMALL",
            "url": "https://dashboard.gifty.nl/storage/images/preview/co_AywKZBJOaXn2oWvY47xk5LVp/small.png"
        }
    ]
  }
}
                
      
Path Parameters
  • giftcard
  • string
  • required
The code of the card, 16 characters long. Do not send hyphens (-), spaces or other special characters in the request.

POST Redeem Gift Card

https://api.gifty.nl/v1/giftcards/:giftcard/redeem

To debit a gift card, a redeem transaction should be made. The 'Transaction' object is returned after a successful transaction.

Request
          
            POST /v1/giftcards/AAAABBBBCCCCDDDD/redeem HTTP/1.1
Host: api.gifty.nl
Accept: application/json
Content-Type: application/json

{
    "amount": 1250,
    "currency": "EUR",
    "capture": false
}
              
          
      
Response
          {
  "data": {
    "id": "tr_kOWB2x0QVvE8GYn6GX7p1oL9",
    "amount": -1250,
    "currency": "EUR",
    "status": "pending",
    "type": "redeem",
    "description": "Redeem amount of '€ 12,50'",
    "is_capturable": true,
    "captured_at": null,
    "created_at": "2019-01-06T19:10:49+00:00",
    "giftcard": ...GiftCardObject
  }
}
                
      
Path Parameters
  • giftcard
  • string
  • required
The code of the card, 16 characters long. Do not send hyphens (-) in the request.
Request Body
  • amount
  • int
  • required
Amount of the transaction. Should be a positive integer in cents. For example, 1000 means a debit transaction of 10,00.

  • currency
  • string
  • required
ISO 4217 code of the currency.

  • capture
  • boolean
  • required
If true, the transaction will be captured immediately and can't be cancelled. When a separate payment needs to be made this should be false so the transaction can be captured or cancelled later.

POST Issue Gift Card

https://api.gifty.nl/v1/giftcards/:giftcard/issue

To credit a gift card, an issue transaction should be made. Issuing a gift card is only possible once, and issue transactions are always captured immediately. The 'Transaction' object is returned after a successful transaction.

Request
          
            POST /v1/giftcards/AAAABBBBCCCCDDDD/issue HTTP/1.1
Host: api.gifty.nl
Accept: application/json
Content-Type: application/json

{
    "amount": 1250,
    "currency": "EUR",
    "promotional": false
}
              
          
      
Response
          {
  "data": {
    "id": "tr_K5Op3zGP4dePxMmyVa9gkXL8",
    "amount": 1250,
    "currency": "EUR",
    "status": "success",
    "type": "issue",
    "description": "Issue amount of '€ 12,50'",
    "is_capturable": false,
    "captured_at": "2019-01-08T11:43:44+00:00",
    "created_at": "2019-01-08T11:43:44+00:00",
    "giftcard": ...GiftCardObject
  }
}
                
      
Path Parameters
  • giftcard
  • string
  • required
The code of the card, 16 characters long. Do not send hyphens (-) in the request.
Request Body
  • amount
  • int
  • required
Amount of the transaction. Should be a positive integer in cents. For example, 1000 means a credit transaction of 10,00.

  • currency
  • string
  • required
ISO 4217 code of the currency.

  • promotional
  • boolean
  • optional
Marks the card as promotional, so it can be excluded from financial reports. Defaults to false.

POST Extend Gift Card

https://api.gifty.nl/v1/giftcards/:giftcard/extend

To extend the validity of a gift card after it has expired, an extend transaction should be made. The 'Transaction' object is returned after a successful transaction.

Request
          
            POST /v1/giftcards/AAAABBBBCCCCDDDD/extend HTTP/1.1
Host: api.gifty.nl
Accept: application/json
Content-Type: application/json

{
    "expires_at": "2023-04-30T16:36:49+00:00"
}
              
          
      
Response
          {
  "data": {
    "id": "tr_kOWB2x0QVvE8GYn6GX7p1oL9",
    "amount": -1250,
    "currency": "EUR",
    "status": "success",
    "type": "reverse_expire",
    "description": "Reverse expire with amount of '€ 12,50'",
    "is_capturable": true,
    "captured_at": "2023-02-23T14:16:32+00:00",
    "created_at": "2023-02-23T14:16:32+00:00",
    "giftcard": ...GiftCardObject
  }
}
                
      
Path Parameters
  • giftcard
  • string
  • required
The code of the card, 16 characters long. Do not send hyphens (-) in the request.
Request Body
  • expires_at
  • string
  • required
ISO 8601 time of expiration. Should be in the future.

Transactions

By issuing a gift card (credit) or redeeming a gift card (debit), a Transaction object represents the change.

The Transaction object

Attribute Type Description
id string Unique identifier for the transaction.
amount integer The amount that has been applied on the gift card during this transaction. Negative values (-1000) indicate a debit transaction. Positive values (1000) indicate a credit transaction.
currency string ISO 4217 code of the currency. Should always be the same as the corresponding gift card.
status string The status of the transaction. Can be one of: success, pending or cancelled.
type string Indicates the reason for the transaction. Can be one of: issue, redeem, release, refund, block, expire, reverse_issue, reverse_redeem or reverse_expire.
description string Provides more information about the transaction.
is_capturable boolean Indicates if a capture can be made on the transaction. This attribute is false if the transaction is captured or cancelled already.
captured_at string or null ISO 8601 time of capturing. As long as this value is null the transaction can be cancelled.
created_at string ISO 8601 time of creation.
giftcard The corresponding gift card of the transaction.

GET List All Transactions

https://api.gifty.nl/v1/transactions

This call returns all Transaction objects. The most recent transactions are shown first.

Request
          
                            GET /v1/transactions?limit=10 HTTP/1.1
                Host: api.gifty.nl
                Accept: application/json
              
          
      
Response
          {
  "data": [
    {
      "id": "tr_W2pJPRYZO0njkQvMrN4zwKqy",
      "amount": 4000,
      "currency": "EUR",
      "status": "success",
      "type": "issue",
      "description": "Issue amount of '€ 40,00'",
      "is_capturable": false,
      "captured_at": "2021-11-10T23:32:12+00:00",
      "created_at": "2021-11-10T23:32:12+00:00",
      "giftcard": ...GiftCardObject
    },
    {...}
  ]
}
                
      
Query Parameters
  • giftcard
  • string
  • optional
Only return transactions for this gift card ID.

  • limit
  • integer
  • optional
The number of results to show. Defaults to 10 and should be between 1 and 100.

  • cursor_before
  • string
  • optional
Pagination cursor ID. See the pagination section for usage instructions.

GET Retrieve Transaction

https://api.gifty.nl/v1/transactions/:transaction

The Transaction object can be retrieved by providing the transaction identifier.

Request
          
                            GET /v1/transactions/tr_ABCDEFGHIJK HTTP/1.1
                Host: api.gifty.nl
                Accept: application/json
              
          
      
Response
          {
  "data": {
    "id": "tr_ABCDEFGHIJK",
    "amount": 4000,
    "currency": "EUR",
    "status": "success",
    "type": "issue",
    "description": "Issue amount of '€ 40,00'",
    "is_capturable": false,
    "captured_at": "2018-11-03T12:41:41+00:00",
    "created_at": "2018-11-03T12:41:41+00:00",
    "giftcard": ...GiftCardObject
  }
}
                
      
Path Parameters
  • transaction
  • string
  • required
The ID of the transaction.

POST Capture Transaction

https://api.gifty.nl/v1/transactions/:transaction/capture

After the entire payment process has been completed and verified, the gift card transaction should be 'captured'. That makes the transaction final.

Request
          
                            POST /v1/transactions/tr_ABCDEFGHIJK/capture HTTP/1.1
                Host: api.gifty.nl
                Accept: application/json
                Content-Type: application/json
              
          
      
Response
          {
  "data": {
    "id": "tr_ABCDEFGHIJK",
    "amount": -1250,
    "currency": "EUR",
    "status": "success",
    "type": "redeem",
    "description": "Redeem amount of '€ 12,50'",
    "is_capturable": false,
    "captured_at": "2019-01-06T19:41:31+00:00",
    "created_at": "2019-01-06T19:10:49+00:00",
    "giftcard": ...GiftCardObject
  }
}
                
      
Path Parameters
  • transaction
  • string
  • required
The ID of the transaction.

DELETE Release Transaction

https://api.gifty.nl/v1/transactions/:transaction

If the payment process ends unsuccessfully, for example, because the customer cancelled the payment, the transaction should be 'released'. The transaction is reverted and funds restored. The return is a 'release' transaction.

Request
          
                            DELETE /v1/transactions/tr_ABCDEFGHIJK HTTP/1.1
                Host: api.gifty.nl
                Accept: application/json
                Content-Type: application/json
              
          
      
Response
          {
  "data": {
    "id": "tr_ABCDEFGHIJK",
    "amount": 1250,
    "currency": "EUR",
    "status": "success",
    "type": "release",
    "description": "Release amount of '€ 12,50' for cancellation of 'tr_ABCDEFGHIJK'",
    "is_capturable": false,
    "captured_at": "2019-01-06T19:49:05+00:00",
    "created_at": "2019-01-06T19:49:05+00:00",
    "giftcard": ...GiftCardObject
  }
}
                
      
Path Parameters
  • transaction
  • string
  • required
The ID of the transaction.

Locations

Companies with multiple store locations can specify the employee's location when performing gift card actions. By doing this, preciser administration views are available in the dashboard. Set the location of the user by passing the ID with your API requests as header.

X-Gifty-Location: REPLACE_WITH_LOCATION_ID

The Location object

Attribute Type Description
id string Unique identifier for the transaction.
street string Address street.
house_number string Address house number.
addition string or null Address house number addition.
postal_code string Address postal code.
city string Address city.

GET List All Locations

https://api.gifty.nl/v1/locations

This call returns all Location objects.

Request
          
                            GET /v1/locations?limit=10 HTTP/1.1
                Host: api.gifty.nl
                Accept: application/json
              
          
      
Response
          {
  "data": [
    {
      "id": "lc_RVyje31w8pmKwwmqlZW096M7",
      "street": "Floridalaan",
      "house_number": "8 bis",
      "addition": null,
      "postal_code": "3404WV",
      "city": "IJsselstein"
    },
    {...}
  ]
}
                
      
Query Parameters
  • limit
  • integer
  • optional
The number of results to show. Defaults to 10 and should be between 1 and 100.

  • cursor_before
  • string
  • optional
Pagination cursor ID. See the pagination section for usage instructions.

Packages

It is possible to sell gift cards with a package value instead of a monetary amount. Each package still represents a monetary value, but it is up to the gift card brand to show this to the customer. Using this API endpoint, you can get the available packages to integrate with your booking platform or webshop.

The Package object

Attribute Type Description
id string Unique identifier for the package.
title string Title of the package.
description string Description of the package.
amount integer The amount this package represents in cents.
amount_visible boolean Indicates if the amount is displayed on the gift card.
currency string ISO 4217 code of the currency.
active boolean Indicates if the package is available for purchase.

GET List All Packages

https://api.gifty.nl/v1/packages

This call returns all Package objects.

Request
          
                            GET /v1/packages?limit=10 HTTP/1.1
                Host: api.gifty.nl
                Accept: application/json
              
          
      
Response
          {
  "data": [
    {
        "id": "gp_rB4kAgGwOzdaQ5dMxN09q62y",
        "title": "Tapasmenu voor 2",
        "description": "Geef een heerlijk verzorgde avond cadeau met ons tapasmenu voor 2.",
        "amount": 4250,
        "amount_visible": true,
        "currency": "EUR",
        "active": true
    },
    {...}
  ]
}
                
      
Query Parameters
  • limit
  • integer
  • optional
The number of results to show. Defaults to 10 and should be between 1 and 100.

  • cursor_before
  • string
  • optional
Pagination cursor ID. See the pagination section for usage instructions.

GET Retrieve Package

https://api.gifty.nl/v1/packages/:package

The Package object can be retrieved by providing the package ID.

Request
          
                          GET /v1/packages/gp_ABCDABCDABCD HTTP/1.1
              Host: api.gifty.nl
              Accept: application/json
              
          
      
Response
          {
  "data": {
      "id": "gp_rB4kAgGwOzdaQ5dMxN09q62y",
      "title": "Tapasmenu voor 2",
      "description": "Geef een heerlijk verzorgde avond cadeau met ons tapasmenu voor 2.",
      "amount": 4250,
      "amount_visible": true,
      "currency": "EUR",
      "active": true
  }
}
                
      
Path Parameters
  • package
  • string
  • required
The ID of the package.
language