🚚Pulling a card - Asynchronous call

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

The process of pulling a card from our API occurs in two steps:

1. Pull request creation.

2. Pull request consultation.

Pretty straightforward, isn't it? We will now describe these two steps in more detail.

Request ID

The request ID is essential for the proper functioning of our API. It enables you to trace and retrieve a card. Make sure you understand its mechanism and have implemented it correctly.

For each card pulled, a request ID will be associated with it. You MUST provide the request ID yourself; the only rule to follow is that it must be unique.

To put it simply: you generate a unique request ID during the creation of your pull request (step 1), and then you use this request ID to consult your pull request and retrieve the card (step 2).

Create pull request

To create a pull request, you must use the following endpoint:

Create a pull request.

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

Creates a new pull request.

Request Body

{ 
    "pull_request": { 
        "amount": amount,
        "gift_card_code": code,
        "request_id": request_id
    } 
}

Name	Type	Description
amount*	Integer	The amount of the gift card
gift_card_code*	String	The code of the gift card
request_id*	String	Request ID of pull request

Response

200: OK Pull_request created

{
  "pull_request": {
    "id": "3db15189-ef10-49b4-8265-58e3fe946ffb",
    "status": "waiting",
    "request_id": "your_request_id",
    "amount_cents": 5000,
    "created_at": "2024-02-05T11:33:39.999+01:00",
    "updated_at": "2024-02-05T11:33:39.999+01:00",
    "card": null
  }
}

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

422: Unprocessable Entity Request ID already used

{
  "errors": [                       
    {
      "code": "unprocessable_entity",            
      "message": "Request id is already used" 
    }                                            
  ],                                             
  "status": "unprocessable_entity"               
}

After sending this request, a new pull request will be created, marked with a status of 'waiting.'

Initially, there won't be any card associated with the pull request.

At this point, our API will initiate the process of pulling your card in the background. This process usually completes within a few seconds. The delivery process duration is brand dependent.

Get pull request

Now that you have requested your card, it's time to obtain it. This involves checking your pull request until its status is 'success', indicating that your card has been successfully pulled.

To do this, consult the following endpoint using the request ID generated in step 1:

Show pull request.

GET https://api.walleo.io/partners/v1/pull_requests/:request_id

Show pull request details.

Path Parameters

Name	Type	Description
request_id*	String	Request ID of pull request

Response

200: OK Pull request successfully found

{
  "pull_request": {
    "id": "3db15189-ef10-49b4-8265-58e3fe946ffb",
    "status": "success",
    "request_id": "your_request_id",
    "created_at": "2024-02-05T11:33:39.999+01:00",
    "updated_at": "2024-02-05T11:33:41.488+01:00",
    "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": "IKEA",
      "pdf_url": "https://url.pdf"
    }
  }
}

Errors

404: Not Found Pull request not found

{
  "errors": [
    {
      "code": "card_not_found",
      "message": "Card not found with id '4fe88e46-eb22-436c-91ec-6bf874fcf2ae'"
    }
  ],
  "status": "not_found"
}

• If your card is still being processed, the status of your pull request will be 'processing' or 'waiting'. In such cases, we recommend calling the endpoint again after an initial attempt with a 2-second interval. Subsequent attempts should observe a 5 to 10-second interval between each call.

• Upon successful pulling of your card, the status of your pull request will change to 'success,' and your card will be associated with the response under the key 'card'.

• In the event of an error during the pulling process, the status of your pull request will be 'error.' In such cases, it's necessary to create a new pull request. Please refer the API reference for the complete list of status values.

As explained earlier, the retrieval time for your card can vary depending on the requested brand. Therefore, if you attempt to retrieve your card too soon, there's a high chance that we haven't finished pulling your card.

We recommend making the second call at least 2 seconds after the first one.