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 charge the card later, or to retrieve or delete it.
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: 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

​
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 metadata such as the card brand and cardholder_name. 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.
Include brand for any card you intend to charge. It’s optional to store, but Rinne’s providers currently require a brand to process a transaction, so a stored card without one is rejected at transaction time.

​
Store a card

201 Created
The response returns the card’s id — the reference you use to charge, retrieve, or delete the card — 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.

​
Charge a stored card

To charge a stored card, pass its id as card_data.card_id when you create a card transaction. Rinne resolves the encrypted number, expiry, last_digits, brand, and cardholder_name from the stored card, so card_data needs little more than the reference itself:
card_data
Include cvv for customer-present payments that re-collect it, and omit it for merchant-initiated payments such as recurring charges. A stored card can only be charged by the company that owns it — a transaction that references a card outside your scope (one that doesn’t exist, was deleted, or belongs to another company) is rejected with 400 VALIDATION_ERROR on card_data.card_id, not the 404 that reading or deleting a card on the cards API returns. See Card transactions for the complete request, the fields you must not send alongside card_id, and the cases where a card_id is rejected.

​
List stored cards

Returns the company’s stored cards, newest first, paginated.
cURL
200 OK
Use page (default 1) and limit (default 20, max 100) to page through results.

​
Get a stored card

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