# Pulling a card - Synchronous call

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

### 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 afterward. 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 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.

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

Creates a new card.

#### Header

`X-RequestId`

#### Request Body

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

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

#### Response

{% tabs %}
{% tab title="200: OK Card created" %}

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

{% 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 %}
{% endtabs %}

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.

###


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.walleo.io/partners-api/pulling-a-card-synchronous-call.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.