# 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="https://app.gitbook.com/s/VNE8t2FopKfzgQzTjlBb/deposits-api/saving-cards-card-on-file" 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>