> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rinne.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Cards on file

> Store encrypted card credentials on file and manage them with a stable card reference, without your systems handling raw card numbers.

Use this guide to store cards on file and manage them with the Rinne Core API. Storing a card saves its encrypted number and card metadata, and returns a stable `id` you use to retrieve or delete the card later.

<Info>
  Rinne stores card credentials as ciphertext only — it never receives or persists a raw card number, and never stores a CVC. Supply the card number as an encrypted value, the same way you do for card transactions.
</Info>

## Access levels (self vs merchant)

Cards on file are available at two access levels, mirroring transactions:

| Context                                | Base path                          |
| -------------------------------------- | ---------------------------------- |
| Self (company acting on its own cards) | `/v1/cards`                        |
| Organization on behalf of a merchant   | `/v1/merchants/{merchantId}/cards` |

On merchant routes, the authenticated organization must own `{merchantId}`; otherwise the request returns `404`.

Every operation exists at both levels. The merchant routes take the same request and response shapes as the self routes, under `/v1/merchants/{merchantId}/cards`.

## Endpoints

| Method   | Path                                        | Permission             | Description                     |
| -------- | ------------------------------------------- | ---------------------- | ------------------------------- |
| `POST`   | `/v1/cards`                                 | `card.create`          | Store a card                    |
| `GET`    | `/v1/cards`                                 | `card.list`            | List stored cards               |
| `GET`    | `/v1/cards/{cardId}`                        | `card.view`            | Get a stored card               |
| `DELETE` | `/v1/cards/{cardId}`                        | `card.delete`          | Delete a stored card            |
| `POST`   | `/v1/merchants/{merchantId}/cards`          | `merchant.card.create` | Store a card for a merchant     |
| `GET`    | `/v1/merchants/{merchantId}/cards`          | `merchant.card.list`   | List a merchant's stored cards  |
| `GET`    | `/v1/merchants/{merchantId}/cards/{cardId}` | `merchant.card.view`   | Get a merchant's stored card    |
| `DELETE` | `/v1/merchants/{merchantId}/cards/{cardId}` | `merchant.card.delete` | Delete a merchant's stored card |

## Supplying the card number

Rinne's API only accepts card numbers in encrypted form. Send `card.number` as an encrypted value — you can recognize encrypted values by their `ev:` prefix — exactly as you do for [card transactions](/guides/card-transactions#sending-card-data). A request where `number` arrives in plain text is rejected with `400 VALIDATION_ERROR` before any processing happens.

These encrypted values come from the rinne-js [Card Element](/rinne-js/card-element), which encrypts the card number in the customer's browser so raw card data never touches your servers.

<Warning>
  Never collect or forward a raw card number from your own inputs. Use encrypted values from the [Card Element](/rinne-js/card-element).
</Warning>

## What to send

A stored card needs the encrypted `number`, its `expiry_month` and `expiry_year`, and the card's `last_digits`. You can optionally include display metadata such as the card `brand`. The [Card Element](/rinne-js/card-element) returns `brand` and `last_digits` for you.

For the complete request and response schema — every field, type, and constraint — see the [Cards API reference](/api-reference/cards/store-a-card).

<Note>
  No CVC is sent or stored when you store a card, and expiry is validated for format only — a card with a past expiry date can still be stored.
</Note>

## Store a card

<CodeGroup>
  ```bash Self theme={null}
  curl -X POST 'https://api-sandbox.rinne.com.br/core/v1/cards' \
    -H 'x-api-key: YOUR_API_KEY' \
    -H 'Content-Type: application/json' \
    -d '{
      "card": {
        "number": "ev:RFVC:jNQ8kR2mvZ9pXwLb7tYc1aVdGhFsK4o:aB3cD4eF5gH6iJ7kL8mN9oP0qR1sT2uV:$",
        "expiry_month": "12",
        "expiry_year": "2030",
        "last_digits": "4242",
        "brand": "VISA"
      }
    }'
  ```

  ```bash Merchant theme={null}
  curl -X POST 'https://api-sandbox.rinne.com.br/core/v1/merchants/f47ac10b-58cc-4372-a567-0e02b2c3d479/cards' \
    -H 'x-api-key: YOUR_API_KEY' \
    -H 'Content-Type: application/json' \
    -d '{
      "card": {
        "number": "ev:RFVC:jNQ8kR2mvZ9pXwLb7tYc1aVdGhFsK4o:aB3cD4eF5gH6iJ7kL8mN9oP0qR1sT2uV:$",
        "expiry_month": "12",
        "expiry_year": "2030",
        "last_digits": "4242",
        "brand": "VISA"
      }
    }'
  ```
</CodeGroup>

```json 201 Created theme={null}
{
  "id": "9c1f2e3a-4b5c-4d6e-8f90-a1b2c3d4e5f6",
  "status": "ACTIVE",
  "brand": "VISA",
  "last_digits": "4242",
  "expiry_month": "12",
  "expiry_year": "2030",
  "created_at": "2026-07-02T12:00:00.000Z",
  "updated_at": "2026-07-02T12:00:00.000Z"
}
```

The response returns the card's `id` — the reference you use to retrieve or delete it — along with its stored metadata and timestamps. The encrypted number is never returned by any endpoint.

<Note>
  Keep the `id` you get back — it's how you reference the stored card later. To change a stored card's details, delete it and store it again.
</Note>

## List stored cards

Returns the company's stored cards, newest first, paginated.

```bash cURL theme={null}
curl 'https://api-sandbox.rinne.com.br/core/v1/cards?page=1&limit=20' \
  -H 'x-api-key: YOUR_API_KEY'
```

```json 200 OK theme={null}
{
  "data": [
    {
      "id": "9c1f2e3a-4b5c-4d6e-8f90-a1b2c3d4e5f6",
      "status": "ACTIVE",
      "brand": "VISA",
      "last_digits": "4242",
      "expiry_month": "12",
      "expiry_year": "2030",
      "created_at": "2026-07-02T12:00:00.000Z",
      "updated_at": "2026-07-02T12:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "totalPages": 1,
    "hasNext": false,
    "hasPrev": false
  }
}
```

Use `page` (default `1`) and `limit` (default `20`, max `100`) to page through results.

## Get a stored card

```bash cURL theme={null}
curl 'https://api-sandbox.rinne.com.br/core/v1/cards/9c1f2e3a-4b5c-4d6e-8f90-a1b2c3d4e5f6' \
  -H 'x-api-key: YOUR_API_KEY'
```

Returns the same card object as the store response. A card that doesn't exist within the caller's scope returns `404`.

## Delete a stored card

```bash cURL theme={null}
curl -X DELETE 'https://api-sandbox.rinne.com.br/core/v1/cards/9c1f2e3a-4b5c-4d6e-8f90-a1b2c3d4e5f6' \
  -H 'x-api-key: YOUR_API_KEY'
```

A successful delete returns `204 No Content`. Deletion is permanent: a deleted card is excluded from all subsequent reads and cannot be restored.

## Scope and isolation

* A stored card is only visible to the company that owns it. A request for a card outside the caller's scope — another company, or a sibling merchant — returns `404`.
* On merchant routes, the authenticated organization must own `{merchantId}`; otherwise the request returns `404`.

## Errors

* `400 VALIDATION_ERROR` — the request failed validation, most commonly a plain-text `number` (send it encrypted) or `last_digits` that isn't exactly 4 digits.
* `404` — the card, or the merchant on a merchant route, isn't found within the caller's scope.

See [Error handling](/guides/error-handling) for the standard error envelope and the full set of status codes.

## Next steps

<CardGroup cols={2}>
  <Card title="Card transactions" icon="credit-card" href="/guides/card-transactions">
    Process credit and debit card payments with 3DS.
  </Card>

  <Card title="Card Element" icon="js" href="/rinne-js/card-element">
    Capture encrypted card data in the browser with rinne-js.
  </Card>

  <Card title="Authentication" icon="key" href="/guides/authentication">
    Authenticate API requests with your API key.
  </Card>

  <Card title="Error handling" icon="triangle-exclamation" href="/guides/error-handling">
    Handle validation and API errors consistently.
  </Card>
</CardGroup>