🔓Authentication

Here we describe how to authenticate with our partners API.

Authentication

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.

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

The timestamp is UTC, in seconds.

Request ID

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

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.

Request Signature

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

1. Build the token

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

Don't forget to sort the keys in your payload in alphabetical order !

2. Sign your token

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

IDENTIFIER: b5245bbc-8ee7-4e55-92e0-b97e81085154

APIKEY: rKc1oJFfEzf0HRbNzLjcvEKijkAFfSL5BYhI-Usidd5PARuHZaSRAL_2eSPOZrT-SHAREDKEY: 6F2CE47010CF4F79B9767042BAFB1EB4

Create card.

POST https://api.walleo.io/partners/v1/cards

Creates a new card.

Request Body

Name	Type	Description
gift_card_code*	string	The code of the gift card
amount*	integer	The amount of the gift card

404: Not Found Gift card not found

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

422: Unprocessable Entity Not enough funds

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

422: Unprocessable Entity Out of stock

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

422: Unprocessable Entity Invalid amount (sku doesn't exist)

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

422: Unprocessable Entity Invalid amount (invalid range)

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

401: Unauthorized Unauthorized

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

401: Unauthorized Invalid signature

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

200: OK Card created

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

1. Build your token

#!/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

#!/bin/bash

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

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:

Ruby

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

PHP

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

3. Build your request

#!/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 } }'