🚚Pulling a card - Synchronous call

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

Request ID

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.

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.

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

Creates a new card.

Header

X-RequestId

Request Body

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

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

Response

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

Errors

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

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.