Saved payment methods

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.
• Playground API credentials. See Authentication and environments.
• 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

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:

{
  "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 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:

PATCH /customer-token/v1/tokens/{customerToken}/status
Content-Type: application/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 — what Kustom validates on every order line.
• Capture an order — settle an order you created against a token.
• Error handling conventions — read the error object every Kustom API returns.
• Test data — sample cards and customers for creating a token in Playground.
• Refunds — give money back on an order placed with a token.