Archive a saved payment method

Retires a saved card or bank account so it can no longer be charged. The stored token is deleted at the payment processor, the method's status becomes ARCHIVE for good (there is no un-archive; the customer's details must be captured again), and every ACTIVE contract on the account that collects from it is moved to FAILING rather than cancelled, so the operator or the customer can attach another method. Used when a customer asks for a card to be removed, when a card is known to be compromised, or from the hosted checkout when the customer deletes one of their saved cards.

Where you can do this

Merchant View: Payment method details (Archive)
The hosted checkout: Payment form (Delete)
API: Delete a payment method (DELETE /payment_methods/{payment_method_id})
The hosted checkout

Before you start

The payment method exists on the client. Any status is accepted (see Rules).
The method's account exists; its divisions are what the permission is checked against.
For the token to be removed at the provider, the method's gateway and its provider connection must still resolve; if they do not, the archive proceeds without the provider call.

Inputs

Input	Required	Meaning and constraints
payment_method_id	yes	Path parameter; the `pm_` id of the method to archive
(body)	no	Ignored. The request carries no body; the archive always sets the status to ARCHIVE and no sub-status or reason can be supplied through either entry point

Rules

Checked by the API means Shuttle refuses the request however it is sent; a screen name means only that screen refuses it, and a direct API call would be accepted.

Rule	Checked by	What you see
The payment method must exist on the client	The API	NOT_FOUND: "Payment method not found" (404)
Through the API, a customer session may only archive a method that belongs to its own account	The API	NO_PERMISSION: "No permissions" (403)
If the provider cannot be reached, or answers with an unusable response, nothing is archived and the error is returned	The API	INVALID with Shuttle's provider error message (400)
Where the gateway's provider connection cannot be resolved, or the provider has no token-deletion support, the provider call is skipped and the method is archived anyway	The API	silent; 204
Every ACTIVE contract on the account whose payment method is this one becomes FAILING; no failing reason is recorded and the next charge date is kept. Contracts in any other status (PENDING, SUSPENDED, UNRESOLVED, SETUP) keep pointing at the archived method and are not moved	The API	status change as stated; otherwise silent
the hosted checkout refuses the deletion when the checkout was opened with payments disabled	The hosted checkout	browser alert "Payment has been disabled"

What happens

The method's status is ARCHIVE. It disappears from the customer's saved cards at checkout and from the account's active saved cards in Merchant View (it stays visible under the archived list). It cannot be charged or reactivated; a replacement is captured with Save a payment method without charging it.
The stored token is deleted at the payment processor, where the provider supports it.
Every ACTIVE contract on the account collecting from the method is now FAILING and will not collect until another method is attached (Change the payment method on a contract).
Webhook PAYMENT_METHOD.ARCHIVE is delivered, and an audit entry is written against the method. No email or SMS is sent to the customer.
The API answers 204 No Content; the hosted checkout reloads its saved-card list; Merchant View closes the dialog and no longer offers Archive.

Who can do this

Roles: Admin and Support. From the hosted checkout, none; that entry point is customer-facing.
Permission keys (for clients managing permissions directly): account or * on the client or on one of the owning account's divisions, checked by Shuttle; without it UNAUTHORIZED: "Unauthorized" (401). A customer session that holds the account passes without a key. Merchant View shows Archive to any user holding account (or *) on any object, so a user whose account key is on a different division sees the control and is refused by the server.
App options: none. the hosted checkout offers the control whenever saved cards are shown, whether or not the customer is present.

Updated 10 minutes ago

Did this page help you?