# Authentication

## 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 } }'
```