---
title: "Stored cards"
description: "Keep cards for later, charge them for subscriptions and add-ons, and remove them."
image: "https://docs.ordercard.io/og.png"
---

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

# Stored cards

A token from hosted fields starts **pending**: it is deleted after 24 hours unless you keep it. You keep it either by charging it successfully (`retain_on_success` is on by default) or by calling [retain](/api/payment-methods). A retained card stays in the vault until you redact it.

## Cards per customer

File each kept card under its [customer](/api/customers) from your server, with your own id for them. The first time OrderCard sees a reference it creates the customer:

```bash
curl -X POST https://api.ordercard.io/v1/payment_methods/tok_…/retain \
  -H "Authorization: Bearer $ORDERCARD_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "customer_reference": "user_1001" }'
```

Sending `customer_reference` with the first charge does the same once the charge succeeds. List a customer's cards with `GET /v1/payment_methods?customer_reference=user_1001` (or `?customer=cus_…`). Never take the customer from the browser: hosted fields refuse it.

## Who started the charge

Card networks treat a charge differently depending on whether the cardholder is present. Tell OrderCard with `initiator`:

| `initiator` | Use for | What OrderCard does |
| --- | --- | --- |
| `customer` (default) | Checkout, with the cardholder present. | Sends the security code if it is still on hand. |
| `merchant` | An unscheduled charge on a stored card, like an add-on or a no-show fee. | Never sends a security code. Marks the charge as a stored-credential charge and references the card's first customer-initiated transaction on the same gateway. |
| `recurring` | A scheduled subscription charge. | Like `merchant`, and also flags it as recurring. Surcharges only apply if the gateway allows them on recurring charges. |

```bash
curl -X POST https://api.ordercard.io/v1/gateways/gw_…/purchase \
  -H "Authorization: Bearer $ORDERCARD_SECRET_KEY" \
  -H "Idempotency-Key: sub-77-2026-11" \
  -H "Content-Type: application/json" \
  -d '{ "payment_method_token": "tok_…", "amount": 1900, "initiator": "recurring", "reference": "sub-77-2026-11" }'
```

Make the first charge on a card a customer-initiated one (or a `verify` at checkout) so later merchant-initiated charges have an original transaction to reference.

## The security code

The CVV is never stored. It is kept encrypted for 15 minutes after the card is tokenized, used once by the first customer-initiated charge or verification, and deleted. Later charges go without it, which issuers expect for stored cards.

## Expired and reissued cards

When the bank reissues a card with a new expiry, update the token rather than collecting the card again:

```bash
curl -X PATCH https://api.ordercard.io/v1/payment_methods/tok_… \
  -H "Authorization: Bearer $ORDERCARD_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "exp_month": 12, "exp_year": 2031 }'
```

The card number can never change: a new card number is a new token.

## Moving between gateways

A token is not tied to a gateway. Charge the same card through a different gateway by sending its id; nothing needs to be re-collected. Merchant-initiated charges reference the card's first customer-initiated transaction **on that gateway**, so make one customer-initiated charge or verification on the new gateway first if the processor requires it.

## Removing a card

Redact the token (`DELETE /v1/payment_methods/{token}`) or use **Delete** on the card's page in the dashboard. The card number, any cached security code, the fingerprint and the cardholder's name, email, phone, billing address and metadata are deleted for good. The token stays, with status `redacted`, and keeps its brand, first six and last four digits, expiry and your customer reference, so past transactions still make sense. Transactions keep the billing details that were sent with each charge.

Source: https://docs.ordercard.io/payments/stored-cards/index.mdx