# Card-on-file

<details>

<summary>Server2Server with additional card-on-file integration </summary>

PCI Compliant merchants willing to stored their client´s cards on PandaBlue´s vault,  have to generate a request to our API for storing cards.

> Visit the API Reference for more information on card-on-file API. <a href="/spaces/VNE8t2FopKfzgQzTjlBb/pages/aDsEtAKUsOPWZhXaQt9f" class="button primary">Saving card</a>\
> Card-on-file API allows merchants to create, retrieve and delete card tokens. form PandaBlue Vault.

<pre class="language-sh" data-title="Example request to card-on-file API"><code class="lang-sh"> curl -L \
  --request POST \
<strong>  --url 'https://cc-api-stg.pandablue.com/v3/tokenization' \
</strong>  --header 'Content-Type: application/json' \
  --header 'X-Date: 2025-07-22T19:04:34.730Z' \
  --header 'X-Login: text' \
  --header 'Authorization: text' \
  --data '{
<strong>    "credit_card": {
</strong><strong>      "holder_name": "Luis Perez",
</strong><strong>      "expiration_month": 10,
</strong><strong>      "expiration_year": 2028,
</strong><strong>      "number": "4111111111111111",
</strong><strong>      "cvv": "123"
</strong>    },
    "payer": {
      "country": "BR",
      "first_name": "John",
      "last_name": "Smith",
      "document_type": "CPF",
      "document": "84932568207"
    },
<strong>    "micro_deposit_enabled": false
</strong>  }'
</code></pre>

{% hint style="info" %}

#### `micro_deposit_enabled` parameter

This parameter allows you to create a small amount transaction on the card (which is immediately refunded) prior storing it. This can be a done as a mechanism for only storing valid cards.\
Note that if the microdeposit fails, the card won't be stored.

{% endhint %}

<pre class="language-json" data-title="Example response of card-on-file API"><code class="lang-json">{
  "holder_name": "Luis Perez",
  "expiration_month": 10,
  "expiration_year": 2028,
  "last_four_digits": "1111",
<strong>  "card_identifier": "CID-2210908e-6d8e-468d-9eb3-d551e8b541a0"
</strong>}
</code></pre>

In the response you will receive the **`card_identifier`** parameter, which later can be used for creating transactions on that client's card.

<pre class="language-sh" data-title="Example request of Server2Server with card_identifier"><code class="lang-sh">curl -L \
  --request POST \
<strong>  --url 'https://cc-api-stg.pandablue.com/v3/deposits' \
</strong>  --header 'Content-Type: application/json' \
  --header 'X-Date: 2025-07-15T12:57:14.936Z' \
  --header 'X-Login: text' \
  --header 'Authorization: text' \
  --data '{
    "invoice_id": "800000001",
    "amount": 1000,
    "country": "BR",
    "currency": "BRL",
    "payer": {
      "id": "11111",
      "document": "84932568207",
      "document_type": "CPF",
      "email": "johnSmith12@hotmail.com",
      "first_name": "John",
      "last_name": "Smith"
    },
<strong>    "card_identifier": "CID-2210908e-6d8e-468d-9eb3-d551e8b541a0",
</strong>    "client_ip": "123.123.123.123"
  }'
</code></pre>

</details>

<details>

<summary>Server2Server saving the card used in the deposit</summary>

Merchants using our Server2Server solution can opt to save the card used within the deposit request.

In order to do so, they can send the parameter **`tokenize_card`** with value **`true`** in the deposit request.

<pre class="language-sh" data-title="Server2Server example request with tokenize_card"><code class="lang-sh">curl -L \
  --request POST \
<strong>  --url 'https://cc-api-stg.pandablue.com/v3/deposits' \
</strong>  --header 'Content-Type: application/json' \
  --header 'X-Date: 2025-07-15T12:57:14.936Z' \
  --header 'X-Login: text' \
  --header 'Authorization: text' \
  --data '{
    "invoice_id": "800000001",
    "amount": 1000,
    "country": "BR",
    "currency": "BRL",
    "payer": {
      "id": "11111",
      "document": "84932568207",
      "document_type": "CPF",
      "email": "johnSmith12@hotmail.com",
      "first_name": "John",
      "last_name": "Smith"
    },
<strong>    "credit_card": {
</strong><strong>      "cvv": "123",
</strong><strong>      "number": "4111111111111111",
</strong><strong>      "expiration_month": "10",
</strong><strong>      "expiration_year": "25",
</strong><strong>      "holder_name": "JOHN SMITH"
</strong><strong>    },
</strong><strong>    "tokenize_card":true,
</strong>    "client_ip": "123.123.123.123"
  }'
</code></pre>

In the synchronous response you will receive the card\_identifier generated for that card.

<pre class="language-json" data-title="Example response with the card_identifier"><code class="lang-json">{
  "deposit_id": 300604089,
  "user_id": "80000001",
  "merchant_invoice_id": "800000001",
  "payment_info": {
    "type": "CREDIT_CARD",
    "result": "SUCCESS",
    "payment_method": "VI",
    "payment_method_name": "Visa",
    "amount": 1000,
    "currency": "BRL",
    "created_at": "2025-07-15T12:57:14.936Z"
  },
<strong>  "card_identifier": "d0d9207b-395e-4742-95bc-66d4caf1037a"
</strong>}
</code></pre>

<pre class="language-sh" data-title="Example request of Server2Server with card_identifier"><code class="lang-sh">curl -L \
  --request POST \
<strong>  --url 'https://cc-api-stg.pandablue.com/v3/deposits' \
</strong>  --header 'Content-Type: application/json' \
  --header 'X-Date: 2025-07-15T12:57:14.936Z' \
  --header 'X-Login: text' \
  --header 'Authorization: text' \
  --data '{
    "invoice_id": "800000001",
    "amount": 1000,
    "country": "BR",
    "currency": "BRL",
    "payer": {
      "id": "11111",
      "document": "84932568207",
      "document_type": "CPF",
      "email": "johnSmith12@hotmail.com",
      "first_name": "John",
      "last_name": "Smith"
    },
<strong>    "card_identifier": "CID-2210908e-6d8e-468d-9eb3-d551e8b541a0",
</strong>    "client_ip": "123.123.123.123"
  }'
</code></pre>

</details>

<details>

<summary>Fragments Lite</summary>

Merchants using our Fragments Lite solution can opt to save the card used within the deposit request.

In order to do so, they can send the parameter **`tokenize_card`** with value **`true`** in the deposit request.\
In the response they will receive the **`card_identifier`** which can be used for creating subsequent charges on that user's card.

<pre class="language-sh" data-title="Example request Fragments Lite with tokenize_card"><code class="lang-sh">curl -L \
  --request POST \
<strong>  --url 'https://cc-api-stg.pandablue.com/v3/deposits' \
</strong>  --header 'Content-Type: application/json' \
  --header 'X-Date: 2025-07-15T12:57:14.936Z' \
  --header 'X-Login: text' \
  --header 'Authorization: text' \
  --data '{
    "invoice_id": "800000001",
    "amount": 1000,
    "country": "BR",
    "currency": "BRL",
    "payer": {
      "id": "11111",
      "document": "84932568207",
      "document_type": "CPF",
      "email": "johnSmith12@hotmail.com",
      "first_name": "John",
      "last_name": "Smith"
    },
<strong>    "card_token": "C4RD_T0K3N_G3N3R4T3D_W1TH_FR4GM3N7S_L1T3",
</strong><strong>    "tokenize_card": true,
</strong>    "client_ip": "123.123.123.123"
  }'
</code></pre>

<pre class="language-json" data-title="Example response with the card_identifier"><code class="lang-json">{
  "deposit_id": 300604089,
  "user_id": "80000001",
  "merchant_invoice_id": "800000001",
  "payment_info": {
    "type": "CREDIT_CARD",
    "result": "SUCCESS",
    "payment_method": "VI",
    "payment_method_name": "Visa",
    "amount": 1000,
    "currency": "BRL",
    "created_at": "2025-07-15T12:57:14.936Z"
  },
<strong>  "card_identifier": "d0d9207b-395e-4742-95bc-66d4caf1037a"
</strong>}
</code></pre>

<pre class="language-sh" data-title="Example request of Fragments Lite with card_identifier"><code class="lang-sh">curl -L \
  --request POST \
<strong>  --url 'https://cc-api-stg.pandablue.com/v3/deposits' \
</strong>  --header 'Content-Type: application/json' \
  --header 'X-Date: 2025-07-15T12:57:14.936Z' \
  --header 'X-Login: text' \
  --header 'Authorization: text' \
  --data '{
    "invoice_id": "800000001",
    "amount": 1000,
    "country": "BR",
    "currency": "BRL",
    "payer": {
      "id": "11111",
      "document": "84932568207",
      "document_type": "CPF",
      "email": "johnSmith12@hotmail.com",
      "first_name": "John",
      "last_name": "Smith"
    },
<strong>    "card_identifier": "CID-2210908e-6d8e-468d-9eb3-d551e8b541a0",
</strong>    "client_ip": "123.123.123.123"
  }'
</code></pre>

</details>

<details>

<summary>Fragments all-in-one</summary>

To implement card-on-file with the Fragments all-in-one, follow the same client-side flow as described for the **OneShot solution below**. The distinction for card-on-file is handled on the backend.

</details>

<details>

<summary>OneShot</summary>

Merchants willing to use our OneShot solution can also make use of card-on-file for generating deposits on their clients' cards.

The parameter **`tokenize_card`** should be sent in the deposit request as **`true`**.

<pre class="language-sh" data-title="Example OneShot request"><code class="lang-sh">curl -L \
  --request POST \
<strong>  --url 'https://api-stg.pandablue.com/v3/deposits' \
</strong>  --header 'Content-Type: application/json' \
  --header 'X-Date: 2025-07-17T13:13:15.442Z' \
  --header 'X-Login: text' \
  --header 'Authorization: text' \
  --data '{
    "invoice_id" : "1000000001",
    "amount": "1000",
    "country": "MX",
    "currency": "MXN",
    "payer": {
        "id": "11",
        "document": "CURP4321TEST",
        "first_name": "Ricardo",
        "last_name": "Carlos",
        "email": "juanCarlos@hotmail.com"
    },
<strong>    "payment_method": "CC",
</strong><strong>    "tokenize_card":true,
</strong>    "client_ip": "123.123.123.123",
    "back_url": "https://www.mercahnt.com/deposit_cancelled",
    "success_url": "https://www.merchant.com/deposit_completed",
    "error_url": "https://www.merchant.com/deposit_error",
    "notification_url": "https://www.pandablue.com/pandablue/notify"
    "logo": "https://www.merchant.com/merchant-logo.png",
}'
</code></pre>

After the deposit is completed by the user you will receive a webhook notifying that the deposit status changed.\
When retrieving the deposit status you will obtain the **`card_identifier`**.&#x20;

<pre class="language-json" data-title="Response of the status retrieve endpoint"><code class="lang-json">{
  "user_id": "11",
  "deposit_id": 300004285,
  "invoice_id": "1000000001",
  "country": "MX",
  "currency": "MXN",
  "local_amount": 1000,
  "usd_amount": 53.22,
  "bonus_amount": 00.00,
  "bonus_relative": false,
  "payment_method": "VI",
  "payment_type": "CREDIT_CARD",
  "status": "COMPLETED",
  "payer": {
    "document": "CURP4321TEST",
    "document_type": "CPF",
    "email": "juanCarlos@hotmail.com",
    "first_name": "Ricardo",
    "last_name": "Carlos"
  },
  "fee_amount": 2.5,
  "fee_currency": "USD",
  "refunded": false,
  "current_payer_verification": "UNMATCHED",
  "card_detail": {
    "card_holder": "Ricardo Carlos",
    "brand": "Visa",
    "masked_card": "1234 56** **** 6789",
    "expiration": "2028-12",
    "card_type": "DEBIT",
    "transaction_result": "Transaction Approved",
    "authorization_code": "000000",
<strong>    "card_identifier": "d0d9207b-395e-4742-95bc-66d4caf1037a"
</strong>  }
}
</code></pre>

The **`card_identifier`** :

* is the token associated to the card that the user selected to pay.
* it can be used unlimited times, until the card expires.

For creating deposits with the **`card_identifier`**, you just need to include it in the deposit request.

<pre class="language-sh" data-title="Example request OneShot with card_identifier"><code class="lang-sh">curl -L \
  --request POST \
<strong>  --url 'https://api-stg.pandablue.com/v3/deposits' \
</strong>  --header 'Content-Type: application/json' \
  --header 'X-Date: 2025-07-17T13:13:15.442Z' \
  --header 'X-Login: text' \
  --header 'Authorization: text' \
  --data '{
    "invoice_id" : "1000000001",
    "amount": "1000",
    "country": "MX",
    "currency": "MXN",
    "payer": {
        "id": "11",
        "document": "CURP4321TEST",
        "first_name": "Ricardo",
        "last_name": "Carlos",
        "email": "juanCarlos@hotmail.com"
    },
    "payment_method": "CC",
<strong>    "card_identifier": "CID-2210908e-6d8e-468d-9eb3-d551e8b541a0",
</strong>    "client_ip": "123.123.123.123",
    "back_url": "https://www.mercahnt.com/deposit_cancelled",
    "success_url": "https://www.merchant.com/deposit_completed",
    "error_url": "https://www.merchant.com/deposit_error",
    "notification_url": "https://www.pandablue.com/pandablue/notify"
    "logo": "https://www.merchant.com/merchant-logo.png",
}'
</code></pre>

As a response you will directly receive the final status of the payment. You can also retrieve the additional details by using the deposit status endpoint.

{% code title="Example response OneShot with card\_identifier" %}

```json
{
  "deposit_id": 1324874939,
  "payment_status": "APPROVED",
  "success": true
}
```

{% endcode %}

</details>


---

# 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.pandablue.com/guides/deposits/create-deposits/credit-cards/card-on-file.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.