Skip to main content
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.
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.

​
Access levels (self vs merchant)

Cards on file are available at two access levels, mirroring transactions:
ContextBase 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

MethodPathPermissionDescription
POST/v1/cardscard.createStore a card
GET/v1/cardscard.listList stored cards
GET/v1/cards/{cardId}card.viewGet a stored card
DELETE/v1/cards/{cardId}card.deleteDelete a stored card
POST/v1/merchants/{merchantId}/cardsmerchant.card.createStore a card for a merchant
GET/v1/merchants/{merchantId}/cardsmerchant.card.listList a merchant’s stored cards
GET/v1/merchants/{merchantId}/cards/{cardId}merchant.card.viewGet a merchant’s stored card
DELETE/v1/merchants/{merchantId}/cards/{cardId}merchant.card.deleteDelete 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. 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, which encrypts the card number in the customer’s browser so raw card data never touches your servers.
Never collect or forward a raw card number from your own inputs. Use encrypted values from the Card Element.

​
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 returns brand and last_digits for you. For the complete request and response schema — every field, type, and constraint — see the Cards API reference.
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.

​
Store a card

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"
    }
  }'

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"
    }
  }'
201 Created
{
  "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.
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.

​
List stored cards

Returns the company’s stored cards, newest first, paginated.
cURL
curl 'https://api-sandbox.rinne.com.br/core/v1/cards?page=1&limit=20' \
  -H 'x-api-key: YOUR_API_KEY'
200 OK
{
  "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

cURL
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

cURL
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 for the standard error envelope and the full set of status codes.

​
Next steps

Card transactions

Process credit and debit card payments with 3DS.

Card Element

Capture encrypted card data in the browser with rinne-js.

Authentication

Authenticate API requests with your API key.

Error handling

Handle validation and API errors consistently.