# Saved Cards

Reference pages: [Save a card and charge it later](/accepting-payments/capture-and-saved-cards/save-a-card-and-charge-it-later), [Capture Buyer Token](/payments/tokenization/post-capture-buyer-token), [Generate Sale with Token](/payments/tokenization/post-generate-sale-tokenization), [Get Buyer Key](/payments/tokenization/post-get-buyer-key), [Create Marketplace Token](/payments/tokenization/post-sellers-mpl-tokens).

A token stands in for a card (TOK-01). Before you save one, you need a first [Checkout](/agents/steps/checkout) to capture the card.

## Getting one

| Way | Who | You get | Notes |
|---|---|---|---|
| `capture_buyer: "1"` on `generate-sale` | Both | `buyer_key` | Captured as part of the payment. Can't be combined with `buyer_key` on one request. A direct seller also sends `buyer_is_private: true`: see below |
| Hosted Fields `tokenize()` | Both | `token`, used as `buyer_key` | `tokenIsPermanent: false` makes it single-use |
| `sale_type: "token"` on `generate-sale` | Both | `buyer_key` | The buyer enters a card and nothing is charged |
| [`capture-buyer-token`](/payments/tokenization/post-capture-buyer-token) | PCI DSS certified only | `buyer_key` | Takes a raw card (TOK-03) |
| `sale_type: "seller-token"` on `generate-sale` | Partner | `uuid` | A hosted page that captures a marketplace token |
| [`POST /sellers/{mpl}/tokens`](/payments/tokenization/post-sellers-mpl-tokens) | Partner, PCI DSS certified | `uuid` | Takes a raw card |

### Getting it safely after a sale

- A direct seller can't verify a callback, so it never stores a token from one (TOK-02). Once the sale is confirmed, it calls `get-buyer-key` with its MPL.
- A partner treats a callback's `buyer_key` as unconfirmed too, until the sale is confirmed.

Which credential `get-buyer-key` takes depends on how the token was captured:

| Token | `get-buyer-key` with | Seen in the sandbox |
|---|---|---|
| Sale sent `buyer_is_private: true` | The seller's MPL | `status_code: 0` |
| Sale sent no `buyer_is_private`, or a marketplace token | `payme_client_key` and no `seller_payme_id` | `status_code: 0`. With the MPL, alone or with the partner key, it fails with [error 603](/payments/getting-started/errors) |

So a direct seller, which has no partner key, must send `buyer_is_private: true` on `generate-sale`, or it can't read the token back.

## Scope and lifetime

- **Reuse:** without `buyer_is_permanent: true`, a `capture-buyer-token` token was charged once and the next charge failed with [error 604](/agents/errors/error-604) in the sandbox. With it, the same token paid repeatedly. Subscriptions need a permanent token too.
- **A `capture_buyer` token:** in the sandbox one was charged three times and then started a subscription, with `buyer_is_private: true` on the sale. `buyer_is_permanent` isn't a `generate-sale` field, and PayMe publishes no lifetime for these tokens, so handle error 604 on any token anyway.
- **Seller or account level:** `buyer_is_private: true` ties a token to one seller. Without it, the token is account-level, and a charge sending `seller_payme_id` can fail: see [Errors](/payments/getting-started/errors).
- **Marketplace-wide:** a token from `POST /sellers/{mpl}/tokens` was charged on another seller of the same partner in the sandbox. Against a seller of a different partner, it failed with [error 605](/agents/errors/error-605).

## Charging one

| You hold | Send on `generate-sale` |
|---|---|
| A `buyer_key` | `buyer_key` |
| A marketplace `uuid` | `token`. Sent as `buyer_key`, it failed with error `600` in the sandbox |

- A token charge returned the final `sale_status` in one call in the sandbox, with no `sale_url`. Confirm it as usual before fulfilling.
- `pay-sale` with `buyer_key` is the other route. It is how a Hosted Fields sale finishes.
- Charge only for the buyer the card belongs to: tie every saved token to your own buyer record and check it.

## Removing one

These docs list no call to revoke a token. Delete it from your store, and that is what "remove this card" means. Let the buyer see the saved card (`buyer_card_mask`) and delete it.

## Test the failure

To test "the saved card stopped working", use `4000000000000036` ([Test Cards and Payment Methods](/payments/getting-started/test-cards-and-payment-methods)). It only reaches the charge if the token comes from Hosted Fields:

| Way in | What happened in the sandbox |
|---|---|
| Hosted Fields `tokenize()`, then `pay-sale` with the token | Token created, then the charge failed with `20004` and the sale became `failed`. Use this one |
| Hosted page, with `capture_buyer` or `sale_type: "token"` | Declined at once with `20004`, and no token exists |

If you didn't build Hosted Fields, there's no way to run this without raw card data (TOK-03). Test your handling of a refused charge with a fake PayMe, and report the real decline as not proven.