🔓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

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

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

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

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

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

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

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

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

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

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

PreviousEnvironments NextPulling a card - Asynchronous call

Last updated 2 years ago