# Saved payment methods

Read a Kustom customer token to find out which card or invoice method a customer has on file and whether it is still usable, understand how long a token stays active and disable one the customer no longer wants you to hold.

A customer token is what lets you charge a returning customer without sending them through
the checkout again — for a subscription renewal, a one-click reorder or a top-up. Once
Checkout has created one, the token lives in Kustom rather than in your database, and you
read it back to find out what it represents and whether it still works. This page covers
reading a token, showing it to the customer and disabling it.

## Before you start

- A customer token, created during a Checkout purchase flagged `recurring: true`. Creating
  one is part of the purchase flow, not something you can do on its own. See [Create a
  customer token](/checkout/recurring/minting-a-token/).
- Playground API credentials. See [Authentication and environments](/api/authentication/).
- The token id you stored against the customer's account in your own system. Kustom holds
  the payment details. You hold the mapping from customer to token.

## Step by step

### Read the token to find out what it represents

```http
GET /customer-token/v1/tokens/{customerToken}
Content-Type: application/json
```

A `200` returns the token's status, its payment method type and, for a card, the details
a customer would recognize:

```json
{
  "payment_method_type": "CARD",
  "status": "ACTIVE",
  "card": {
    "brand": "visa",
    "expiry_date": "11/2031",
    "masked_number": "************4242"
  }
}
```

`payment_method_type` is one of `CARD`, `INVOICE`, `DIRECT_DEBIT` or `WALLET`. A card
token carries a `card` block, and a SEPA direct debit token a `direct_debit` block holding only
`masked_number`. For the others the type is all there is, and the blocks that don't apply come
back `null`, so branch on `payment_method_type` rather than assuming a `card` object is present,
and allow for the type itself to be missing on a cancelled token. `status` is `ACTIVE` or
`CANCELLED`.

### Show the saved method to the customer without re-collecting it

`masked_number`, `brand` and `expiry_date` exist so you can render something a customer
recognizes — "Visa ending 4242" — on a reorder or subscription management screen.
`masked_number` carries only the last four digits, and `expiry_date` is month and year
without a leading zero, so `3/2030` rather than `03/2030`. That's
all the detail you get, and all you should need: the full payment credentials never leave
Kustom, and nothing private is shared onward.

Check `status` before you offer the token as a payment option. A token that isn't
`ACTIVE` should not be presented, and the customer should be sent through checkout again.

### Handle the error response

Most failed reads carry no body, so branch on the status code:

| Status | Body | Means |
|---|---|---|
| `404` | empty | The token doesn't exist or the id is wrong — usually a token that was never created because the purchase failed, or one your system stored against the wrong customer. |
| `400` | `BAD_VALUE`, `Token do not belong to merchant` | The token exists but was created under a different merchant ID. A token can only be read and charged by the MID that created it. |

Don't wait for an `error_code` on a `404`; there isn't one.
[Error handling conventions](/api/errors/) covers the error object where there is one.

### Disable a token the customer no longer wants you to hold

You disable a token by setting its status to `CANCELLED`:

```http
PATCH /customer-token/v1/tokens/{customerToken}/status
Content-Type: application/json
```

```json
{
  "status": "CANCELLED"
}
```

A success is `202` with an empty body. `CANCELLED` is the only status you can set, and it's
final: a cancelled token can't be made active again, and cancelling it a second time returns
`400`. A cancelled token stops working immediately for new orders. Orders already created against it are
unaffected and continue through capture and refund as normal.

Disable a token when the customer cancels a subscription, removes a saved card or asks you
to stop holding their details. Don't simply delete your own mapping row and leave the
token active in Kustom.

## Why a customer token outlives the order that created it

A token is not a copy of the order. It combines the customer's details, the payment method
they chose and a link to your merchant account, and it's stored inside Kustom's own
systems — which is exactly why you can charge against it later without ever handling the
card yourself.

Its lifetime is driven by use, not by a clock: a token stays active for as long as it
keeps being used to create orders. It doesn't expire on a fixed schedule, and it doesn't
lapse when the order that created it is captured or refunded. That's what makes
subscriptions work, and it's also what makes disabling an explicit action you have to
take rather than something that happens on its own.

The obligation that comes with that is disclosure. You must tell customers that a token is
being created and that you'll use it to place future orders. Storing a payment method
the customer didn't knowingly agree to leave with you is a compliance problem, not a
technical one, and Kustom can't fix it on your behalf.

## Check that it works

- Read a token you created in Playground and confirm `status` is `ACTIVE` and the masked
  number matches the test card you used.
- Read a token id that doesn't exist and confirm you handle an empty `404` without
  breaking the customer's page.
- Disable a token, read it again and confirm `status` is `CANCELLED` and your reorder screen
  no longer offers it.

## Related

- [Order lines and tax](/checkout/tax-and-order-lines/) — what Kustom validates on every
  order line.
- [Capture an order](/order-management/capture/) — settle an order you
  created against a token.
- [Error handling conventions](/api/errors/) — read the error object every
  Kustom API returns.
- [Test data](/basics/test-data/) — sample cards and customers for creating a token in
  Playground.
- [Refunds](/order-management/refunds/) — give money back on an order placed with a token.