# 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

{% hint style="warning" %}
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.
{% endhint %}

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.

<mark style="color:green;">`POST`</mark> `https://api.walleo.io/partners/v1/pull_requests`

Creates a new pull request.

#### Request Body

{% code fullWidth="false" %}

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

{% endcode %}

| Name                                               | Type    | Description                 |
| -------------------------------------------------- | ------- | --------------------------- |
| amount<mark style="color:red;">\*</mark>           | Integer | The amount of the gift card |
| gift\_card\_code<mark style="color:red;">\*</mark> | String  | The code of the gift card   |
| request\_id<mark style="color:red;">\*</mark>      | String  | Request ID of pull request  |

#### Response

{% tabs %}
{% tab title="200: OK Pull\_request created" %}

```json
{
  "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
  }
}
```

{% endtab %}
{% endtabs %}

#### Errors

{% tabs %}
{% tab title="404: Not Found Gift card not found" %}

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

{% endtab %}

{% tab title="422: Unprocessable Entity Not enough funds" %}

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

{% endtab %}

{% tab title="422: Unprocessable Entity Out of stock" %}

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

{% endtab %}

{% tab title="422: Unprocessable Entity Invalid amount (sku doesn't exist)" %}

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

{% endtab %}

{% tab title="422: Unprocessable Entity Invalid amount (invalid range)" %}

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

{% endtab %}

{% tab title="401: Unauthorized Unauthorized" %}

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

{% endtab %}

{% tab title="401: Unauthorized Invalid signature" %}

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

{% endtab %}

{% tab title="422: Unprocessable Entity Request ID already used" %}

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

{% endtab %}
{% endtabs %}

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.&#x20;

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

## Show pull request.

<mark style="color:blue;">`GET`</mark> `https://api.walleo.io/partners/v1/pull_requests/:request_id`

Show pull request details.

#### Path Parameters

| Name                                          | Type   | Description                |
| --------------------------------------------- | ------ | -------------------------- |
| request\_id<mark style="color:red;">\*</mark> | String | Request ID of pull request |

#### Response

{% tabs %}
{% tab title="200: OK Pull request successfully found" %}

```json
{
  "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"
    }
  }
}
```

{% endtab %}
{% endtabs %}

#### Errors

{% tabs %}
{% tab title="404: Not Found Pull request not found" %}

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

{% endtab %}
{% endtabs %}

* 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.

{% hint style="warning" %}
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.
{% endhint %}