🔓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

422: Unprocessable Entity Out of stock

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

422: Unprocessable Entity Invalid amount (invalid range)

401: Unauthorized Unauthorized

401: Unauthorized Invalid signature

200: OK Card created

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

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