# Welcome!

## Welcome to Walleo API

Here you'll find all the documentation you need to get up and running with the Walleo API.

## First, choose the correct environment

Remember to use staging environment for your integration tests:

| Staging                         | Production              |
| ------------------------------- | ----------------------- |
| <https://api.staging.walleo.io> | <https://api.walleo.io> |

More about environments here:

{% content-ref url="/pages/MYCIYl8YBWOR28i15ui8" %}
[Environments](/environments)
{% endcontent-ref %}

## Want to jump right in?

Feeling like an eager beaver? Jump in to the quick start docs and get making your first request:

{% content-ref url="/pages/HUtjyTs7ybXoTiry8Iw3" %}
[Quick Start](/quick-start)
{% endcontent-ref %}

## Want to deep dive?

Dive a little deeper and start exploring our API reference to get an idea of everything that's possible with the API:

{% content-ref url="/pages/4jQXYgKZlGSfh9yLJP2a" %}
[API Reference](/partners-api/api-reference)
{% endcontent-ref %}


# Quick Start

Démarrez au plus vite !

To interact with our API, you must first authenticate yourself by following the steps outlined on this page:

{% content-ref url="/pages/KMicn8XP2cI2J2br55cg" %}
[Authentication](/partners-api/authentication)
{% endcontent-ref %}

After authenticating yourself with our API, try pulling your first gift card by following the steps outlined on this page:

{% content-ref url="/pages/TLZPlFFrGK9kg52NptMY" %}
[Pulling a card - Asynchronous call](/partners-api/pulling-a-card-asynchronous-call)
{% endcontent-ref %}

And there you have it, easy, right? You can now offer our gift card catalog to your customers.


# Environments

Our API offers two environments:

| Staging                         | Production              |
| ------------------------------- | ----------------------- |
| <https://api.staging.walleo.io> | <https://api.walleo.io> |

Most of the time, you will use our staging environment to perform your tests. The data present in the staging environment is for testing purposes only, all of it is fake. Rest assured, you cannot affect production through this environment, and all notions of money and prepaid accounts are fake.

Some features may only be available in staging while we test them on our side. Therefore, the staging environment may be affected by bugs introduced by these new features; please do not take them into account.

Finally, some store data may not be fully populated, and some card pulling APIs may not work in staging. Please disregard this, as it is due to the nature of the environment; everything should works fine in production.


# Authentication

Here we describe how to authenticate with our partners API.

## Authentication <a href="#toc_3" id="toc_3"></a>

To works with us you will be given:

* an API\_KEY
* an IDENTIFIER
* a SHARED\_KEY

The `Authorization` header contains, your API\_KEY, your IDENTIFIER and a Signature of the request you made with your SHARED\_KEY.

```none
Authorization: Bearer $API_KEY, Id=$IDENTIFIER, Signature=56161615151515, Timestamp=1643464283
```

The timestamp is UTC, in seconds.

#### Request ID <a href="#toc_4" id="toc_4"></a>

With POST requests, you can give a request id alongside your request. If you post a request two times with the same request id, the second time it will the return the response of the first request instead of recreating the resource.

It is useful when the connection broke and you did not receive the response, but your request has been proceed.

The header is named `X-RequestId`

{% hint style="danger" %}
The request ID is mandatory to retrieve a card afterwards. We strongly advise you to implement it, otherwise we will not be held responsible for any lost cards.
{% endhint %}

## Request Signature <a href="#toc_5" id="toc_5"></a>

To ensure your are the caller of our APIs, we need you to sign your request.

**1. Build the token**

```none
TOKEN=HTTP_VERB+URL+STRING_PAYLOAD+TIMESTAMP
```

| Variables       | Value                                                                                                           |
| --------------- | --------------------------------------------------------------------------------------------------------------- |
| HTTP\_VERB      | GET \| POST                                                                                                     |
| URL             | {DOMAIN}/path                                                                                                   |
| STRING\_PAYLOAD | Is optional if your request is a GET. This is your JSON payload, sorted by keys, and with lowercase characters. |
| TIMESTAMP       | UTC timestamp in seconds                                                                                        |

{% hint style="warning" %}
Don't forget to sort the keys in your payload in alphabetical order !
{% endhint %}

**2. Sign your token**

```bash
echo -ne $TOKEN | openssl dgst -sha256 -mac HMAC -macopt hexkey:$SHARED_KEY
```

This command will give you, your signature. It must be in your `Authorization` header.

## Example <a href="#toc_8" id="toc_8"></a>

> IDENTIFIER: `b5245bbc-8ee7-4e55-92e0-b97e81085154`&#x20;
>
> API*KEY: `rKc1oJFfEzf0HRbNzLjcvEKijkAFfSL5BYhI-Usidd5PARuHZaSRAL_2eSPOZrT-`SHARED*KEY: `6F2CE47010CF4F79B9767042BAFB1EB4`

## Create card.

<mark style="color:green;">`POST`</mark> `https://api.walleo.io/partners/v1/cards`

Creates a new card.

#### Request Body

| Name                                               | Type    | Description                 |
| -------------------------------------------------- | ------- | --------------------------- |
| gift\_card\_code<mark style="color:red;">\*</mark> | string  | The code of the gift card   |
| amount<mark style="color:red;">\*</mark>           | integer | The amount of the gift card |

{% tabs %}
{% tab title="404: Not Found Gift card not found" %}

```json
{
  "errors": [
    {
      "code": "gift_card_not_found",
      "message": "Gift card not found with code 'IKEA-FR'"
    }
  ],
  "status": "not_found"
}
```

{% endtab %}

{% tab title="422: Unprocessable Entity Not enough funds" %}

```json
{
  "errors": [                       
    {
      "code": "not_enough_funds",            
      "message": "Your balance account is not high enough" 
    }                                            
  ],                                             
  "status": "unprocessable_entity"               
}
```

{% endtab %}

{% tab title="422: Unprocessable Entity Out of stock" %}

```json
{
  "errors": [                       
    {
      "code": "out_of_stock",            
      "message": "Out of stock gift card 'IKEA-FR'" 
    }                                            
  ],                                             
  "status": "unprocessable_entity"               
}
```

{% endtab %}

{% tab title="422: Unprocessable Entity Invalid amount (sku doesn't exist)" %}

```json
{
  "errors": [                       
    {
      "code": "invalid_amount",            
      "message": "Amount must be one of 15, 30 or 100." 
    }                                            
  ],                                             
  "status": "unprocessable_entity"               
}
```

{% endtab %}

{% tab title="422: Unprocessable Entity Invalid amount (invalid range)" %}

```json
{
  "errors": [                       
    {
      "code": "invalid_amount",            
      "message": "Amount must be within range from 20 to 500 with steps of 10." 
    }                                            
  ],                                             
  "status": "unprocessable_entity"               
}
```

{% endtab %}

{% tab title="401: Unauthorized Unauthorized" %}

```json
{
  "errors": [
    {
      "code": "unauthorized",
      "message": "Not authorized"
    }
  ],
  "status": "unauthorized"
}
```

{% endtab %}

{% tab title="401: Unauthorized Invalid signature" %}

```json
{
  "errors": [
    {
      "code": "invalid_signature",
      "message": "Your request does not match your signature"
    }
  ],
  "status": "unauthorized"
}
```

{% endtab %}

{% tab title="200: OK Card created" %}

```json
{
  "card": {
    "id": "4fe88e46-eb22-436c-91ec-6bf874fcf2ae",
    "code": "345454545451154154",
    "expire_at": "2022-06-24T00:00:00.000+02:00",
    "pin_code": "1234",
    "amount": 50,
    "gift_card_code": "IKEAFR",
    "pdf_url": "https://url.pdf"
  }
}
```

{% endtab %}
{% endtabs %}

**1. Build your token**

```bash
#!/bin/bash

TOKEN='POST+http://www.example.com/partners/v1/cards+{"card":{"amount":50,"gift_card_code":"E-ca"}}+b5245bbc-8ee7-4e55-92e0-b97e81085154+1648559273'
```

**2. Sign your token**

```bash
#!/bin/bash

echo -ne $TOKEN | openssl dgst -sha256 -mac HMAC -macopt hexkey:6F2CE47010CF4F79B9767042BAFB1EB4
# > 434f3dd367edbe5c82a68f5b5a771a50d602c2868e10a4b132ae807df6982867
```

{% hint style="info" %}
When `openssl` is processing your key, the `hexkey` tells it that your key must be converted in hexadecimal. In your code there wont be such option so you must convert your key before giving it to the hash function. Here are two examples:
{% endhint %}

{% tabs %}
{% tab title="Ruby" %}

```ruby
OpenSSL::HMAC.hexdigest("SHA256", [key.to_s].pack('H*'), token)
```

{% endtab %}

{% tab title="PHP" %}

```php
hash_hmac("sha256", $token, pack("H*", $key))
```

{% endtab %}
{% endtabs %}

**3. Build your request**

```bash
#!/bin/bash

curl -X POST http://www.example.com/partners/v1/cards
     -H 'Content-Type: application/json'
     -H 'Accept: application/json'
     -H 'Authorization: Bearer rKc1oJFfEzf0HRbNzLjcvEKijkAFfSL5BYhI-Usidd5PARuHZaSRAL_2eSPOZrT-, Id=b5245bbc-8ee7-4e55-92e0-b97e81085154, Timestamp=1648559273'
     -d '{ "card": { "gift_card_code": "IKEAFR", "amount": 50 } }'
```


# Pulling a card - Asynchronous call

This page aims to assist you in pulling your first gift card through our asynchronous API.

\
The process of pulling a card from our API occurs in two steps:

1. Pull request creation.&#x20;
2. Pull request consultation.

Pretty straightforward, isn't it? We will now describe these two steps in more detail.

### Request ID

{% hint style="warning" %}
The request ID is essential for the proper functioning of our API. It enables you to trace and retrieve a card. Make sure you understand its mechanism and have implemented it correctly.
{% endhint %}

For each card pulled, a request ID will be associated with it. You MUST provide the request ID yourself; the only rule to follow **is that it must be unique.**

**To put it simply:** you generate a unique request ID during the creation of your pull request (step 1), and then you use this request ID to consult your pull request and retrieve the card (step 2).

### Create pull request

To create a pull request, you must use the following endpoint:

## Create a pull request.

<mark style="color:green;">`POST`</mark> `https://api.walleo.io/partners/v1/pull_requests`

Creates a new pull request.

#### Request Body

{% code fullWidth="false" %}

```json
{ 
    "pull_request": { 
        "amount": amount,
        "gift_card_code": code,
        "request_id": request_id
    } 
}
```

{% endcode %}

| Name                                               | Type    | Description                 |
| -------------------------------------------------- | ------- | --------------------------- |
| amount<mark style="color:red;">\*</mark>           | Integer | The amount of the gift card |
| gift\_card\_code<mark style="color:red;">\*</mark> | String  | The code of the gift card   |
| request\_id<mark style="color:red;">\*</mark>      | String  | Request ID of pull request  |

#### Response

{% tabs %}
{% tab title="200: OK Pull\_request created" %}

```json
{
  "pull_request": {
    "id": "3db15189-ef10-49b4-8265-58e3fe946ffb",
    "status": "waiting",
    "request_id": "your_request_id",
    "amount_cents": 5000,
    "created_at": "2024-02-05T11:33:39.999+01:00",
    "updated_at": "2024-02-05T11:33:39.999+01:00",
    "card": null
  }
}
```

{% endtab %}
{% endtabs %}

#### Errors

{% tabs %}
{% tab title="404: Not Found Gift card not found" %}

```json
{
  "errors": [
    {
      "code": "gift_card_not_found",
      "message": "Gift card not found with code 'IKEA-FR'"
    }
  ],
  "status": "not_found"
}
```

{% endtab %}

{% tab title="422: Unprocessable Entity Not enough funds" %}

```json
{
  "errors": [                       
    {
      "code": "not_enough_funds",            
      "message": "Your balance account is not high enough" 
    }                                            
  ],                                             
  "status": "unprocessable_entity"               
}
```

{% endtab %}

{% tab title="422: Unprocessable Entity Out of stock" %}

```json
{
  "errors": [                       
    {
      "code": "out_of_stock",            
      "message": "Out of stock gift card 'IKEA-FR'" 
    }                                            
  ],                                             
  "status": "unprocessable_entity"               
}
```

{% endtab %}

{% tab title="422: Unprocessable Entity Invalid amount (sku doesn't exist)" %}

```json
{
  "errors": [                       
    {
      "code": "invalid_amount",            
      "message": "Amount must be one of 15, 30 or 100." 
    }                                            
  ],                                             
  "status": "unprocessable_entity"               
}
```

{% endtab %}

{% tab title="422: Unprocessable Entity Invalid amount (invalid range)" %}

```json
{
  "errors": [                       
    {
      "code": "invalid_amount",            
      "message": "Amount must be within range from 20 to 500 with steps of 10." 
    }                                            
  ],                                             
  "status": "unprocessable_entity"               
}
```

{% endtab %}

{% tab title="401: Unauthorized Unauthorized" %}

```json
{
  "errors": [
    {
      "code": "unauthorized",
      "message": "Not authorized"
    }
  ],
  "status": "unauthorized"
}
```

{% endtab %}

{% tab title="401: Unauthorized Invalid signature" %}

```json
{
  "errors": [
    {
      "code": "invalid_signature",
      "message": "Your request does not match your signature"
    }
  ],
  "status": "unauthorized"
}
```

{% endtab %}

{% tab title="422: Unprocessable Entity Request ID already used" %}

```json
{
  "errors": [                       
    {
      "code": "unprocessable_entity",            
      "message": "Request id is already used" 
    }                                            
  ],                                             
  "status": "unprocessable_entity"               
}
```

{% endtab %}
{% endtabs %}

After sending this request, a new pull request will be created, marked with a status of 'waiting.'

Initially, there won't be any card associated with the pull request.

At this point, our API will initiate the process of pulling your card in the background. This process usually completes within a few seconds. The delivery process duration is brand dependent.

### Get pull request

Now that you have requested your card, it's time to obtain it. This involves checking your pull request until its status is 'success', indicating that your card has been successfully pulled.&#x20;

To do this, consult the following endpoint using the request ID generated in step 1:

## Show pull request.

<mark style="color:blue;">`GET`</mark> `https://api.walleo.io/partners/v1/pull_requests/:request_id`

Show pull request details.

#### Path Parameters

| Name                                          | Type   | Description                |
| --------------------------------------------- | ------ | -------------------------- |
| request\_id<mark style="color:red;">\*</mark> | String | Request ID of pull request |

#### Response

{% tabs %}
{% tab title="200: OK Pull request successfully found" %}

```json
{
  "pull_request": {
    "id": "3db15189-ef10-49b4-8265-58e3fe946ffb",
    "status": "success",
    "request_id": "your_request_id",
    "created_at": "2024-02-05T11:33:39.999+01:00",
    "updated_at": "2024-02-05T11:33:41.488+01:00",
    "card": {
      "id": "4fe88e46-eb22-436c-91ec-6bf874fcf2ae",
      "code": "345454545451154154",
      "expire_at": "2022-06-24T00:00:00.000+02:00",
      "pin_code": "1234",
      "amount": 50,
      "gift_card_code": "IKEA",
      "pdf_url": "https://url.pdf"
    }
  }
}
```

{% endtab %}
{% endtabs %}

#### Errors

{% tabs %}
{% tab title="404: Not Found Pull request not found" %}

```json
{
  "errors": [
    {
      "code": "card_not_found",
      "message": "Card not found with id '4fe88e46-eb22-436c-91ec-6bf874fcf2ae'"
    }
  ],
  "status": "not_found"
}
```

{% endtab %}
{% endtabs %}

* If your card is still being processed, the status of your pull request will be '**processing**' or **'waiting'.** In such cases, we recommend calling the endpoint again after an initial attempt with a 2-second interval. Subsequent attempts should observe a 5 to 10-second interval between each call.
* Upon successful pulling of your card, the status of your pull request will change to '**success**,' and **your card will be associated with the response under the key 'card'.**
* In the event of an error during the pulling process, the status of your pull request will be '**error**.' In such cases, it's necessary to create a new pull request. Please refer the API reference for the complete list of status values.

{% hint style="warning" %}
As explained earlier, the retrieval time for your card can vary depending on the requested brand. Therefore, if you attempt to retrieve your card too soon, there's a high chance that we haven't finished pulling your card.

We recommend making the second call at least 2 seconds after the first one.
{% endhint %}


# Pulling a card - Synchronous call

This page aims to assist you in pulling your first gift card through our synchronous API.

### Request ID

{% hint style="warning" %}
The request ID is essential for the proper functioning of our API. It enables you to trace and retrieve a card afterward. Make sure you understand its mechanism and have implemented it correctly.
{% endhint %}

For each card pulled, a request ID will be associated with it. You can provide the request ID yourself; the only rule to follow **is that it must be unique.** If you don't provide a request ID, we will generate one for you, which will be communicated in the pull response.

What is the purpose of this request ID? A concrete example:

* You make a card pull call with the request ID: 'REQ-ID-1'
* For some reason, you fail to retrieve the response to this call (timeout, loss of internet connection, bugs, ...).
* If you want to retrieve this card afterward, you just need to make another call with the request ID 'REQ-ID-1' to retrieve the same card.

**To summarize simply:** a pull call for card A is associated with a request ID 'A.' All calls made with this request ID 'A' will return the response from the call for card A. To make a new pull, you need to make a call with a request ID 'B.'

### Pulling a card

To pull a card, you must use the following endpoint:

## Create card.

<mark style="color:green;">`POST`</mark> `https://api.walleo.io/partners/v1/cards`

Creates a new card.

#### Header

`X-RequestId`

#### Request Body

```json
{ 
  "card": { 
    "amount": amount,
    "gift_card_code": code
  } 
}
```

| Name                                               | Type    | Description                 |
| -------------------------------------------------- | ------- | --------------------------- |
| amount<mark style="color:red;">\*</mark>           | integer | The amount of the gift card |
| gift\_card\_code<mark style="color:red;">\*</mark> | string  | The code of the gift card   |

#### Response

{% tabs %}
{% tab title="200: OK Card created" %}

```json
{
  "card": {
    "id": "4fe88e46-eb22-436c-91ec-6bf874fcf2ae",
    "code": "345454545451154154",
    "expire_at": "2022-06-24T00:00:00.000+02:00",
    "pin_code": "1234",
    "amount": 50,
    "gift_card_code": "IKEAFR",
    "pdf_url": "https://url.pdf"
  }
}
```

{% endtab %}
{% endtabs %}

#### Errors

{% tabs %}
{% tab title="404: Not Found Gift card not found" %}

```json
{
  "errors": [
    {
      "code": "gift_card_not_found",
      "message": "Gift card not found with code 'IKEA-FR'"
    }
  ],
  "status": "not_found"
}
```

{% endtab %}

{% tab title="422: Unprocessable Entity Not enough funds" %}

```json
{
  "errors": [                       
    {
      "code": "not_enough_funds",            
      "message": "Your balance account is not high enough" 
    }                                            
  ],                                             
  "status": "unprocessable_entity"               
}
```

{% endtab %}

{% tab title="422: Unprocessable Entity Out of stock" %}

```json
{
  "errors": [                       
    {
      "code": "out_of_stock",            
      "message": "Out of stock gift card 'IKEA-FR'" 
    }                                            
  ],                                             
  "status": "unprocessable_entity"               
}
```

{% endtab %}

{% tab title="422: Unprocessable Entity Invalid amount (sku doesn't exist)" %}

```json
{
  "errors": [                       
    {
      "code": "invalid_amount",            
      "message": "Amount must be one of 15, 30 or 100." 
    }                                            
  ],                                             
  "status": "unprocessable_entity"               
}
```

{% endtab %}

{% tab title="422: Unprocessable Entity Invalid amount (invalid range)" %}

```json
{
  "errors": [                       
    {
      "code": "invalid_amount",            
      "message": "Amount must be within range from 20 to 500 with steps of 10." 
    }                                            
  ],                                             
  "status": "unprocessable_entity"               
}
```

{% endtab %}

{% tab title="401: Unauthorized Unauthorized" %}

```json
{
  "errors": [
    {
      "code": "unauthorized",
      "message": "Not authorized"
    }
  ],
  "status": "unauthorized"
}
```

{% endtab %}

{% tab title="401: Unauthorized Invalid signature" %}

```json
{
  "errors": [
    {
      "code": "invalid_signature",
      "message": "Your request does not match your signature"
    }
  ],
  "status": "unauthorized"
}
```

{% endtab %}
{% endtabs %}

The pull time for a card may vary depending on the brand. The response to this request is dependent on the card's pull time. Therefore, we recommend setting a timeout of 10 seconds and attempting to retrieve the card again one minute later using your request ID:

* If your card is still in the process of being pulled, the response to your call will be: 'come back later.' Call the endpoint again in a few moments (a recommended 10-second interval between each call)
* If your card has been successfully pulled, the response will contain that same card.
* If an error occurs during the pull, that error will be returned to you.

###


# API Reference

Dive into the specifics of each API endpoint by checking out our complete documentation.

## Gift Cards

Everything related to gift cards:

{% content-ref url="/pages/UhOwKOU0VPyL324c1eKk" %}
[Gift Cards](/partners-api/api-reference/gift-cards)
{% endcontent-ref %}

## Cards

Everything related to cards:

{% content-ref url="/pages/WPjHxntAFJb1ZDWTlmyD" %}
[Cards](/partners-api/api-reference/cards)
{% endcontent-ref %}

## Inventories

Everything related to inventories:

{% content-ref url="/pages/zvvzwna0y34HPYOlYq7L" %}
[Inventories](/partners-api/api-reference/inventories)
{% endcontent-ref %}

## Balance

Everything related to balance:

{% content-ref url="/pages/KODplB7EsjJAZ3OIdpAv" %}
[Balance](/partners-api/api-reference/balance)
{% endcontent-ref %}


# Gift Cards

## Get all gift cards

## Get all gift cards

<mark style="color:blue;">`GET`</mark> `https://api.walleo.io/partners/v1/gift_cards`

Get all the gift cards accessible by the user.

{% tabs %}
{% tab title="200: OK Return all gift cards" %}

```json
[
  {
  "name"=>"GetYourGuide",
  "code"=>"GYGEU",
  "brand"=>"GetYourGuide",
  "barcode_symbology"=>"code128",
  "online_usable"=>true,
  "offline_usable"=>false,
  "validity_period"=>1095,
  "cumulative_online"=>true,
  "cumulative_online_limit"=>-1,
  "cumulative_offline"=>false,
  "cumulative_offline_limit"=>0,
  "splittable_online"=>true,
  "splittable_offline"=>false,
  "code_pin"=>false,
  "how_to_use_online"=>"<div>To redeem, click \"Enter gift code or promo code\" in the checkout and type in the code.&nbsp;<br>&nbsp;If the total differs from the amount of your gift card, you can pay the difference or use the remainder on a future booking. Bon voyage!</div>",
  "how_to_use_offline"=>nil,
  "term_of_use"=>"<div><strong>Gift Card Terms and Conditions</strong><br>The Gift Card Terms and Conditions (“Terms”) are entered into between GetYourGuide Deutschland GmbH, located at Sonnenburger Str. 73, 10437 Berlin, Germany (“GetYourGuide”, “we”) and you. By purchasing or using your GetYourGuide Gift Card you agree to be bound by these Terms.&nbsp;<br>1. Gift Card Redemption : You can use your GetYourGuide Gift Card to book tours and activities offered by a variety of activity providers on the GetYourGuide Platform. To use your GetYourGuide Gift Card go to www.getyourguide.com, choose an activity and enter the e-voucher code for the gift card in the booking process. GetYourGuide Gift Cards are not redeemable for cash. Gift cards cannot be combined with any other promotional codes.<br>2. Gift Card Value : You can check the balance and validity of your Gift Card by using the self help page on the GetYourGuide website: https://www.getyourguide.com/contact#payment-and-refunds_gift-cart-value-and-validity&nbsp;<br>3. Validity : The validity period of the Gift Card is three years starting at the end of the year of the purchase. The validity of the Gift Card cannot be extended. You must use the balance of the Gift Card before the expiration date. Any unused balance will be forfeited upon expiration.<br>4. Lost or Stolen Gift Cards : GetYourGuide is not responsible for lost, stolen, or the unauthorized use of your Gift Card if you or someone you have given the card to loses it or has it stolen. In such cases, the Gift Card will not be replaced or refunded.<br>5. Cancellation or Refund : Once a Gift Card has been purchased, it cannot be cancelled or refunded.<br>6. Questions : For questions or assistance regarding the use or terms of your GetYourGuide Gift Card, please contact our customer service team through the contact details provided on the GetYourGuide website.</div>",
  "discount"=>7.0,
  "next_discounts"=>[
    {
      "value"=>6.5,
      "date"=>"2026-03-22T23:59:00.000+01:00"
    }
  ],
  "facial_values"=>{
    "type"=>"fixed",
    "amounts"=>[
      25.0,
      50.0,
      75.0,
      100.0,
      150.0
    ]
  },
  "logo_url"=>"https://assets.walleo.io/y4d27a9b4w2b0831ou3vfbbifbbv",
  "logo_square_url"=>"https://assets.walleo.io/lgm2f4838jgfruwtrhggbktngd5k",
  "country_name"=>"Europe",
  "country_code"=>"EU",
  "countries"=>[
    {
      "country_name"=>"France",
      "country_code"=>"FR"
    },
    {
      "country_name"=>"Spain",
      "country_code"=>"ES"
    },
    {
      "country_name"=>"Germany",
      "country_code"=>"DE"
    },
    {
      "country_name"=>"Netherlands",
      "country_code"=>"NL"
    }
  ]
},
{
  "name"=>"Amazon fr",
  "code"=>"AMAZFR",
  "brand"=>"Amazon",
  "barcode_symbology"=>"code128",
  "online_usable"=>true,
  "offline_usable"=>false,
  "validity_period"=>366,
  "cumulative_online"=>true,
  "cumulative_online_limit"=>-1,
  "cumulative_offline"=>false,
  "cumulative_offline_limit"=>0,
  "splittable_online"=>false,
  "splittable_offline"=>false,
  "code_pin"=>false,
  "how_to_use_online"=>"<ol><li>Accédez au site web d'Amazon France.</li><li>Connectez-vous à votre compte Amazon ou créez-en un nouveau si vous n'en avez pas.</li><li>Ajoutez les articles que vous souhaitez acheter à votre panier d'achat.</li><li>Cliquez sur \"Passer à la caisse\" pour finaliser votre commande.</li><li>Sélectionnez \"Utiliser une carte-cadeau ou un bon de réduction\" comme mode de paiement.</li><li>Entrez le code de la carte-cadeau Amazon dans le champ \"Code de la carte-cadeau\".</li><li>Cliquez sur \"Appliquer\" pour déduire la valeur de la carte-cadeau du montant total de l'achat.</li><li>Si la valeur de la carte-cadeau est inférieure au montant de l'achat, vous devrez sélectionner un autre mode de paiement pour couvrir le solde.</li><li>Cliquez sur \"Passer à la commande\" pour finaliser l'achat.</li></ol>",
  "how_to_use_offline"=>nil,
  "term_of_use"=>"<div>Les Cartes Cadeaux Amazon.fr* peuvent être utilisées pour des millions d’articles sur www.amazon.fr. Amazon.fr propose une immense sélection de livres, produits électroniques, musique, téléchargements MP3, films et TV, vêtements, jeux vidéo, logiciels, sports et activités de plein air, jouets, articles de puériculture, ordinateurs et bureautique, maison et jardin, bijoux, beauté, bricolage et décoration d’intérieur, produits de bureau, vidéo et photo, accessoires pour animaux et bien d’autres choses encore. Amazon.fr est le site où trouver et acheter en ligne à un excellent prix quasiment tout ce que vous voulez.\"</div>",
  "discount"=>2.0,
  "next_discounts"=>[],
  "facial_values"=>{
    "type"=>"fixed",
    "amounts"=>[
      10.0,
      25.0,
      50.0,
      100.0
    ]
  },
  "logo_url"=>"https://assets.walleo.io/t931c5bq6czeggpxx2ez8wouimlz",
  "logo_square_url"=>"https://assets.walleo.io/gdyqpqeog94jn0ccr0ri3acyoryv",
  "country_name"=>"France",
  "country_code"=>"FR"
},
{
  "name"=>"Leroy Merlin",
  "code"=>"Lero",
  "brand"=>"Leroy Merlin",
  "barcode_symbology"=>"code128",
  "online_usable"=>false,
  "offline_usable"=>true,
  "validity_period"=>366,
  "cumulative_online"=>false,
  "cumulative_online_limit"=>0,
  "cumulative_offline"=>true,
  "cumulative_offline_limit"=>-1,
  "splittable_online"=>false,
  "splittable_offline"=>true,
  "code_pin"=>true,
  "how_to_use_online"=>"<div>Utilisez vos remises sur les produits vendus et expédiés par Leroy Merlin.</div><div>Vous pouvez retrouver, simuler et activer vos remises fidélité sur notre site directement en plaçant les produits de votre commande dans le panier.</div><div>Ces avantages ne sont pas applicables aux produits vendus et expédiés par les vendeurs de la Marketplace.</div>",
  "how_to_use_offline"=>"Sur mobile : Pour utiliser vos e-Bons/e-Cartes cadeaux, rendez vous dans le menu Portefeuille de votre application, sélectionnez votre enseigne et le e-Bon à utiliser et présentez l’écran de votre smartphone lors de votre passage en caisse.\n\nSur ordinateur : vous avez la possibilité de générer un pdf de votre e-Bon.",
  "term_of_use"=>"Carte cadeau émise par la société Leroy Merlin France SA, située rue Chanzy, 59260 LEZENNES, RCS Lille 384 560 942.\nCarte cadeau valable 1 an à compter de son activation et utilisable exclusivement dans le réseau Leroy Merlin (en magasin), en une ou plusieurs fois.\nL'utilisation de la carte est cumulable avec d'autres promotions en cours\nCarte cadeau ne pouvant être ni échangée, ni revendue, ni remboursée ou portée au crédit d'un compte bancaire.\nUne carte cadeau ne peut pas être utilisée pour acheter une autres carte cadeau.\nL'achat de la carte cadeau Leroy Merlin ne permet pas de bénéficier de points de fidélité (l'acquisition des points se fera lors de l'utilisation de la carte).\nLa carte cadeau n'est ni remplacée, ni remboursée en cas de perte ou de péremption.\nL’achat de produits à l’aide de cartes cadeaux Leroy Merlin peut être réalisé en cumulant plusieurs cartes cadeaux Leroy Merlin dans la limite de 3000€.\nConditions d'utilisation, solde et durée de validité consultables sur https://www.leroymerlin.fr/cartes-cadeaux \n\nService client : \nTel : 03.59.57.46.04\nhttps://www.leroymerlin.fr/contact/",
  "discount"=>3.8,
  "next_discounts"=>[],
  "facial_values"=>{
    "type"=>"free",
    "min_amount"=>10.0,
    "max_amount"=>150.0,
    "step_amount"=>1.0
  },
  "logo_url"=>"https://assets.walleo.io/yuu3cibj86y77mpcgohrzu2vuwm1",
  "logo_square_url"=>"https://assets.walleo.io/7n0utgo7trrh5n8sclrvp3st2jqi",
  "country_name"=>nil,
  "country_code"=>nil
}
]
```

{% endtab %}
{% endtabs %}

Country and Region Availability

* `country_name`\
  Indicates the geographical scope where the gift card can be used.
  * If the gift card is usable in a **single country**, this field contains the **country name**.
  * If the gift card is usable in a **region**, this field contains the **region name** (e.g. *Europe*).
* `country_code`\
  Represents the code associated with the geographical scope.
  * For a **single country**, this is the[ **ISO 3166-1 alpha-2 country code** ](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements)(e.g. `FR`, `DE`).
  * For a **region**, this is a **region code** defined by the system (e.g. `EU`).
* `countries`\
  This field is **only present when the gift card is usable in a region**.\
  It contains the list of countries included in that region, each defined by:

  * `country_name`: the country name
  * `country_code`: the ISO 3166-1 alpha-2 country code

  If the gift card is usable in a **single country**, the field `countries` is omitted or empty.

Note

* **`country_name`** and **`country_code`** are expected to be configured by default.
* If they are not configured, their values will be returned as **`null`**.

## Get gift card

## Show a gift card

<mark style="color:blue;">`GET`</mark> `https://api.walleo.io/partners/v1/gift_cards/:id`

Show a specific gift card.<br>

#### Path Parameters

{% tabs %}
{% tab title="200: OK Return gift card" %}

```json
{
  "name" => "GetYourGuide",
  "code" => "GYGEU",
  "brand" => "GetYourGuide",
  "barcode_symbology" => "code128",
  "online_usable" => true,
  "offline_usable" => false,
  "validity_period" => 1095,
  "cumulative_online" => true,
  "cumulative_online_limit" => -1,
  "cumulative_offline" => false,
  "cumulative_offline_limit" => 0,
  "splittable_online" => true,
  "splittable_offline" => false,
  "code_pin" => false,
  "how_to_use_online" => "<div>To redeem, click \"Enter gift code or promo code\" in the checkout and type in the code.&nbsp;<br>&nbsp;If the total differs from the amount of your gift card, you can pay the difference or use the remainder on a future booking. Bon voyage!</div>",
  "how_to_use_offline" => nil,
  "term_of_use" => "<div><strong>Gift Card Terms and Conditions</strong><br>The Gift Card Terms and Conditions (“Terms”) are entered into between GetYourGuide Deutschland GmbH, located at Sonnenburger Str. 73, 10437 Berlin, Germany (“GetYourGuide”, “we”) and you. By purchasing or using your GetYourGuide Gift Card you agree to be bound by these Terms.&nbsp;<br>1. Gift Card Redemption : You can use your GetYourGuide Gift Card to book tours and activities offered by a variety of activity providers on the GetYourGuide Platform. To use your GetYourGuide Gift Card go to www.getyourguide.com, choose an activity and enter the e-voucher code for the gift card in the booking process. GetYourGuide Gift Cards are not redeemable for cash. Gift cards cannot be combined with any other promotional codes.<br>2. Gift Card Value : You can check the balance and validity of your Gift Card by using the self help page on the GetYourGuide website: https://www.getyourguide.com/contact#payment-and-refunds_gift-cart-value-and-validity&nbsp;<br>3. Validity : The validity period of the Gift Card is three years starting at the end of the year of the purchase. The validity of the Gift Card cannot be extended. You must use the balance of the Gift Card before the expiration date. Any unused balance will be forfeited upon expiration.<br>4. Lost or Stolen Gift Cards : GetYourGuide is not responsible for lost, stolen, or the unauthorized use of your Gift Card if you or someone you have given the card to loses it or has it stolen. In such cases, the Gift Card will not be replaced or refunded.<br>5. Cancellation or Refund : Once a Gift Card has been purchased, it cannot be cancelled or refunded.<br>6. Questions : For questions or assistance regarding the use or terms of your GetYourGuide Gift Card, please contact our customer service team through the contact details provided on the GetYourGuide website.</div>",
  "discount" => 7.0,
  "next_discounts"=>[
    {
      "value"=>6.5,
      "date"=>"2026-03-22T23:59:00.000+01:00"
    }
  ],
  "facial_values" => {
    "type" => "fixed",
    "amounts" => [
      25.0,
      50.0,
      75.0,
      100.0,
      150.0
    ]
  },
  "logo_url" => "https://assets.walleo.io/y4d27a9b4w2b0831ou3vfbbifbbv",
  "logo_square_url" => "https://assets.walleo.io/lgm2f4838jgfruwtrhggbktngd5k",
  "country_name" => "Europe",
  "country_code" => "EU",
  "countries" => [
    {
      "country_name" => "France",
      "country_code" => "FR"
    },
    {
      "country_name" => "Spain",
      "country_code" => "ES"
    },
    {
      "country_name" => "Germany",
      "country_code" => "DE"
    },
    {
      "country_name" => "Netherlands",
      "country_code" => "NL"
    }
  ]
}
```

{% endtab %}
{% endtabs %}


# Cards

## Create new card synchronously

## Create card.

<mark style="color:green;">`POST`</mark> `https://api.walleo.io/partners/v1/cards`

Creates a new card synchronously.

#### Request Body

```json
{ 
  "card": { 
    "amount": amount,
    "gift_card_code": code
  } 
}
```

| Name                                               | Type    | Description                 |
| -------------------------------------------------- | ------- | --------------------------- |
| amount<mark style="color:red;">\*</mark>           | integer | The amount of the gift card |
| gift\_card\_code<mark style="color:red;">\*</mark> | string  | The code of the gift card   |

#### Response

{% tabs %}
{% tab title="200: OK Card created" %}

```json
{
  "card": {
    "id": "4fe88e46-eb22-436c-91ec-6bf874fcf2ae",
    "code": "345454545451154154",
    "expire_at": "2022-06-24T00:00:00.000+02:00",
    "pin_code": "1234",
    "amount": 50,
    "gift_card_code": "IKEAFR",
    "pdf_url": "https://url.pdf"
  }
}
```

{% endtab %}
{% endtabs %}

#### Errors

{% tabs %}
{% tab title="404: Not Found Gift card not found" %}

```json
{
  "errors": [
    {
      "code": "gift_card_not_found",
      "message": "Gift card not found with code 'IKEA-FR'"
    }
  ],
  "status": "not_found"
}
```

{% endtab %}

{% tab title="422: Unprocessable Entity Not enough funds" %}

```json
{
  "errors": [                       
    {
      "code": "not_enough_funds",            
      "message": "Your balance account is not high enough" 
    }                                            
  ],                                             
  "status": "unprocessable_entity"               
}
```

{% endtab %}

{% tab title="422: Unprocessable Entity Out of stock" %}

```json
{
  "errors": [                       
    {
      "code": "out_of_stock",            
      "message": "Out of stock gift card 'IKEA-FR'" 
    }                                            
  ],                                             
  "status": "unprocessable_entity"               
}
```

{% endtab %}

{% tab title="422: Unprocessable Entity Invalid amount (sku doesn't exist)" %}

```json
{
  "errors": [                       
    {
      "code": "invalid_amount",            
      "message": "Amount must be one of 15, 30 or 100." 
    }                                            
  ],                                             
  "status": "unprocessable_entity"               
}
```

{% endtab %}

{% tab title="422: Unprocessable Entity Invalid amount (invalid range)" %}

```json
{
  "errors": [                       
    {
      "code": "invalid_amount",            
      "message": "Amount must be within range from 20 to 500 with steps of 10." 
    }                                            
  ],                                             
  "status": "unprocessable_entity"               
}
```

{% endtab %}

{% tab title="401: Unauthorized Unauthorized" %}

```json
{
  "errors": [
    {
      "code": "unauthorized",
      "message": "Not authorized"
    }
  ],
  "status": "unauthorized"
}
```

{% endtab %}

{% tab title="401: Unauthorized Invalid signature" %}

```json
{
  "errors": [
    {
      "code": "invalid_signature",
      "message": "Your request does not match your signature"
    }
  ],
  "status": "unauthorized"
}
```

{% endtab %}
{% endtabs %}

## Show card

## Show card.

<mark style="color:blue;">`GET`</mark> `https://api.walleo.io/partners/v1/cards/:id`

Show card details.

#### Path Parameters

| Name                                 | Type   | Description    |
| ------------------------------------ | ------ | -------------- |
| id<mark style="color:red;">\*</mark> | String | ID of the card |

#### Response

{% tabs %}
{% tab title="200: OK Card successfully found" %}

```json
{
  "card": {
    "id": "4fe88e46-eb22-436c-91ec-6bf874fcf2ae",
    "code": "345454545451154154",
    "expire_at": "2022-06-24T00:00:00.000+02:00",
    "pin_code": "1234",
    "amount": 50,
    "gift_card_code": "IKEA",
    "pdf_url": "https://url.pdf"
  }
}
```

{% endtab %}
{% endtabs %}

#### Errors

{% tabs %}
{% tab title="404: Not Found Card not found" %}

```json
{
  "errors": [
    {
      "code": "card_not_found",
      "message": "Card not found with id '4fe88e46-eb22-436c-91ec-6bf874fcf2ae'"
    }
  ],
  "status": "not_found"
}
```

{% endtab %}
{% endtabs %}


# Pull Requests

## Create a card asynchronously

## Create a pull request.

<mark style="color:green;">`POST`</mark> `https://api.walleo.io/partners/v1/pull_requests`

Creates a new pull request.

#### Request Body

| Name                                               | Type    | Description                 |
| -------------------------------------------------- | ------- | --------------------------- |
| amount<mark style="color:red;">\*</mark>           | Integer | The amount of the gift card |
| gift\_card\_code<mark style="color:red;">\*</mark> | String  | The code of the gift card   |
| request\_id<mark style="color:red;">\*</mark>      | String  | Request ID of pull request  |

#### Response

{% tabs %}
{% tab title="200: OK Pull request created" %}

```json
{
  "pull_request": {
    "id": "3db15189-ef10-49b4-8265-58e3fe946ffb",
    "status": "waiting",
    "request_id": "your_request_id",
    "amount_cents": 5000,
    "created_at": "2024-02-05T11:33:39.999+01:00",
    "updated_at": "2024-02-05T11:33:39.999+01:00",
    "card": null
  }
}
```

{% endtab %}
{% endtabs %}

#### Errors

{% tabs %}
{% tab title="404: Not Found Gift card not found" %}

```json
{
  "errors": [
    {
      "code": "gift_card_not_found",
      "message": "Gift card not found with code 'IKEA-FR'"
    }
  ],
  "status": "not_found"
}
```

{% endtab %}

{% tab title="422: Unprocessable Entity Not enough funds" %}

```json
{
  "errors": [                       
    {
      "code": "not_enough_funds",            
      "message": "Your balance account is not high enough" 
    }                                            
  ],                                             
  "status": "unprocessable_entity"               
}
```

{% endtab %}

{% tab title="422: Unprocessable Entity Out of stock" %}

```json
{
  "errors": [                       
    {
      "code": "out_of_stock",            
      "message": "Out of stock gift card 'IKEA-FR'" 
    }                                            
  ],                                             
  "status": "unprocessable_entity"               
}
```

{% endtab %}

{% tab title="422: Unprocessable Entity Invalid amount (sku doesn't exist)" %}

```json
{
  "errors": [                       
    {
      "code": "invalid_amount",            
      "message": "Amount must be one of 15, 30 or 100." 
    }                                            
  ],                                             
  "status": "unprocessable_entity"               
}
```

{% endtab %}

{% tab title="422: Unprocessable Entity Invalid amount (invalid range)" %}

```json
{
  "errors": [                       
    {
      "code": "invalid_amount",            
      "message": "Amount must be within range from 20 to 500 with steps of 10." 
    }                                            
  ],                                             
  "status": "unprocessable_entity"               
}
```

{% endtab %}

{% tab title="401: Unauthorized Unauthorized" %}

```json
{
  "errors": [
    {
      "code": "unauthorized",
      "message": "Not authorized"
    }
  ],
  "status": "unauthorized"
}
```

{% endtab %}

{% tab title="401: Unauthorized Invalid signature" %}

```json
{
  "errors": [
    {
      "code": "invalid_signature",
      "message": "Your request does not match your signature"
    }
  ],
  "status": "unauthorized"
}
```

{% endtab %}

{% tab title="422: Unprocessable Entity Request ID already used" %}

```json
{
  "errors": [                       
    {
      "code": "unprocessable_entity",            
      "message": "Request id is already used" 
    }                                            
  ],                                             
  "status": "unprocessable_entity"               
}
```

{% endtab %}
{% endtabs %}

## Show pull request

## Show pull request.

<mark style="color:blue;">`GET`</mark> `https://api.walleo.io/partners/v1/pull_requests/:request_id`

Show pull request details.

#### Path Parameters

| Name                                          | Type   | Description                |
| --------------------------------------------- | ------ | -------------------------- |
| request\_id<mark style="color:red;">\*</mark> | String | Request ID of pull request |

#### Response

{% tabs %}
{% tab title="200: OK Pull request successfully found" %}

```json
{
  "pull_request": {
    "id": "3db15189-ef10-49b4-8265-58e3fe946ffb",
    "status": "success",
    "request_id": "your_request_id",
    "created_at": "2024-02-05T11:33:39.999+01:00",
    "updated_at": "2024-02-05T11:33:41.488+01:00",
    "card": {
      "id": "4fe88e46-eb22-436c-91ec-6bf874fcf2ae",
      "code": "345454545451154154",
      "expire_at": "2022-06-24T00:00:00.000+02:00",
      "pin_code": "1234",
      "amount": 50,
      "gift_card_code": "IKEA",
      "pdf_url": "https://url.pdf"
    }
  }
}
```

{% endtab %}
{% endtabs %}

#### Errors

{% tabs %}
{% tab title="404: Not Found Pull request not found" %}

```json
{
  "errors": [
    {
      "code": "pull_request_not_found",
      "message": "Pull request not found with request_id: REQ-ID-TEST"
    }
  ],
  "status": "not_found"
}
```

{% endtab %}
{% endtabs %}


# Inventories

## Get inventory

## Get an inventory

<mark style="color:blue;">`GET`</mark> `https://api.walleo.io/partners/v1/inventories/:id`

Get an inventory for a specific gift card.

#### Path Parameters

| Name                                 | Type   | Description    |
| ------------------------------------ | ------ | -------------- |
| id<mark style="color:red;">\*</mark> | String | Gift card code |

{% tabs %}
{% tab title="200: OK Return inventory" %}

```json
{
  "inventories": {
    "gift_card": {
      "code": "IKEAFR",
      "name": "Ikea France"
    },
    "end_to_end_api": {
      "enabled": true,
      "available_amount": "unlimited"
    },
    "stocks": [
      {
        "facial_value": 50,
        "owned_quantity": 5,
        "shared_quantity": 0
      }
    ]
  }
}
```

{% endtab %}
{% endtabs %}


# Balance

## Get my balance

## Get balance

<mark style="color:blue;">`GET`</mark> `https://api.walleo.io/partners/v1/balance`

Get user balance.

#### Response

{% tabs %}
{% tab title="200: OK Return user balance" %}

```json
{
    "balance": {
        "amount": 25674.30
    }
}
```

{% endtab %}
{% endtabs %}