๐Ÿšš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
    } 
}
NameTypeDescription

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

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

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

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

NameTypeDescription

request_id*

String

Request ID of pull request

Response

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

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

Last updated