# Save a payment method without charging it

> Stores a card, bank account or wallet against an account as a saved payment method, tokenised at the gateway, without taking a payment. Support staff use it fro

Stores a card, bank account or wallet against an account as a saved payment method, tokenised at the gateway, without taking a payment. Support staff use it from the account screen to put a customer's new card on file over the phone; customers use it from the hosted checkout when a checkout request asks for a method to be saved, and integrators call the API directly. The same call can name contracts the new method should be attached to, and can register a token the integrator already holds at the gateway.

### Where you can do this

- Merchant View: [Account](/platforms/user-guides/admin-accounts-view/) (Add Payment Method)
- Merchant View: [Account header](/platforms/user-guides/admin-sections-accounts/#account-header) (Add Payment Method)
- The hosted checkout: [Payment form](/platforms/user-guides/checkout-checkout-payment/) (Confirm (confirm page, TOKENISE); the gateway's own save-card page (hosted))
- API: [Create a checkout](/platforms/reference/operations/createcheckout/) (`POST /checkouts`) — action TOKENISE for an account; prepares the checkout, the save itself is the POST below
- The hosted checkout: the hosted checkout submits in TOKENISE mode; the hosted checkout forwards it to POST /c/api/payment_methods
- API: [Create a payment method](/platforms/reference/operations/createpaymentmethod/) (`POST /payment_methods`) — body carries card, bank or wallet details, or the id of a saved method; with token it registers a token already held at the gateway without calling it
- Automatically (Shuttle): gateway return for a redirect-based method — the provider's connector receives the customer's return or webhook and posts the token to Shuttle, which activates the method and attaches any contracts parked on it

### Before you start

- An account, named by id or CRM key, or account details from which one can be registered or created anonymously (the channel must allow that).
- A gateway that can save cards or create tokens for the card type, either named in the call or reachable through the initiative's routing for the account's country.
- For a saved method named by `id`, that method must be ACTIVE or FAILING.
- For a token registered directly, the gateway must exist and the token must be supplied.

### Inputs

Fields on `POST /c/api/payment_methods`, inside `payment_method`:

| Input | Required | Meaning and constraints |
|---|---|---|
| account | yes | An account id, or an object: `id`, or `crm_key` (alias `alt_key`) with `first_name`, `last_name`, `company`, `email`, `phone`, `address` (`country`, `line1` to `line6`) and `tags`. With `crm_key` and no `id` the most recently created account with that CRM key is used, or one is registered through the channel. With neither, an anonymous account is created from the details |
| id | no | A saved payment method to reuse; nothing new is stored or tokenised, the call only attaches it to `contracts` |
| gateway | conditional | Required with `token`. Otherwise optional: when omitted the gateway is chosen by routing (initiative, the account's country, card type) |
| currency | no | Passed to the gateway with the tokenisation |
| code | no | Reporting code for the method; must not be in use by an ACTIVE or FAILING method |
| nonce | no | Serialises concurrent calls carrying the same value and is stored on the method. A payment-link nonce (`pl_...`) marks that link complete once the method is ACTIVE |
| type | no | Card type (alias `card_type`). Derived from `card_number` when omitted; SEPA, ACH or BACS is inferred from the bank fields |
| card_number | conditional | One of a card, bank or wallet detail set is needed for a new method. Non-digits are stripped |
| card_expiry | no | Alias `expiry`. Accepts MMYY, MM/YY, M/YY or MYY and is stored as a month; other formats are not stored |
| card_cvc | no | Passed to the gateway, never stored |
| last4 | no | Alias `card_ending` |
| bin | no | Alias `card_bin` |
| requires_cvc | no | Marks the saved method as needing a CVC on later use |
| iban | conditional | Alias `sepa_iban`; makes the method SEPA |
| account_holder_name | no | Aliases `cardholder_name`, `card_holder_name`, `sepa_account_holder_name`, `ach_account_holder_name` |
| account_type | conditional | Alias `ach_account_type`; makes the method ACH |
| routing_number | no | Alias `ach_routing_number` |
| account_number | conditional | Alias `ach_account_number`; makes the method BACS when no other type applies |
| name | no | Alias `description`. Stored as the method's description, localised with the card type and ending |
| address | no | Alias `billing`. Billing address (`country`, `line1` to `line6`) sent to the gateway and stored |
| tags | no | Stored on the method |
| metadata | no | Stored on the method |
| source | no | `ecommerce` (default), `moto`, `pos` or `recurring`; sets whether the customer and staff are present, which the gateway is told and the method records |
| success_url | no | Where a redirect-based method returns on success; `#PAYMENTMETHODKEY#` is replaced and `payment_method=pm_...` appended |
| cancel_url | no | As `success_url`, for a cancelled or failed authorisation |
| locale | no | As `user_agent` |
| token | conditional | A token already held at the gateway. Switches the call to registration: no gateway call is made and the method is stored with `status` (default ACTIVE), `sub_status` and `sub_status_reason` as sent |
| manual | no | Same effect as sending `token` |
| contracts[] | no | Contracts to attach the method to; see [Change the payment method on a contract](/platforms/user-guides/rules-contract-change-payment-method/) |

Fields on `POST /c/api/checkout` for this function: `action` TOKENISE (required), `force_add` (hides the account's saved methods so a new one must be entered; Merchant View always sets it), `legal_entity` (narrows the gateways the form offers), and the checkout fields that belong to [Take a one-off payment](/platforms/user-guides/rules-payment-take/) (`nonce`, `account`, `channel`, `source`, `currency`) and to [Change the payment method on a contract](/platforms/user-guides/rules-contract-change-payment-method/) (`contracts[]`).

### 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 checkout call follows the checkout rules of [Take a one-off payment](/platforms/user-guides/rules-payment-take/) (body, nonce, CRM key without spaces, duplicate nonce) | The API | see [Take a one-off payment](/platforms/user-guides/rules-payment-take/) |
| An account is required | The API | VALIDATION_ERROR: "Missing account" |
| A token registered directly needs a gateway | The API | VALIDATION_ERROR: "Missing gateway" |
| A CRM key must not contain spaces | The API | VALIDATION_ERROR: "crm_key cannot inlcude spaces" (sic) |
| A customer's account session may only save a method on its own account; the check is on the account, whether given by id or resolved from `crm_key` | The API | NO_PERMISSION: "No permissions"; Shuttle: INVALID (BOLT-1005) |
| An account object with neither `id` nor `crm_key` creates an anonymous account, which the channel must allow | The API | INVALID (BOLT-1086, anonymous accounts disabled) |
| An account named by `crm_key` that the CRM does not know is refused unless the channel allows registration | The API | INVALID (BOLT-1031 with registration on, BOLT-1087 with it off) |
| The account must resolve | The API | INVALID (BOLT-1031) |
| A merged account resolves to the account it was merged into; the method is stored there | The API | silent (see Link a duplicate account) |
| Every call creates a customer session for the account and runs the fraud screening on it; a blocked session refuses the call with the screening's reason | The API | INVALID (BOLT-1088) with the fraud reason as the message |
| The channel must exist and accept payments | The API | INVALID: "Invalid value for field channelKey." / channel not accepting payments |
| A saved method named by `id` must exist and be ACTIVE or FAILING. It is attached to `contracts` only when ACTIVE; a FAILING method returns OK and changes nothing | The API | NOT_FOUND on "payment_method <id>" / INVALID on "payment_method" |
| Each contract in `contracts[]` must exist and be in a status that accepts a new method; the set and the attach rules are on [Change the payment method on a contract](/platforms/user-guides/rules-contract-change-payment-method/) | The API | INVALID on "contract: <id>" |
| `code` must not be in use by an ACTIVE or FAILING method | The API | INVALID: "Invalid code" |
| The card type is derived from the card number when not sent; a number whose type cannot be recognised is refused | The API | INVALID (BOLT-1093) |
| A card expiry of December in the current year, or on the test card ending 1111, is not stored (test-card convention) | The API | silent; the method shows no expiry |
| A named gateway must exist and have a payment processor; when none is named, the initiative's routing for the account's country and the card type must reach one. A `legal_entity` in the body plays no part in this routing, and no part in anything else: it is dropped on the way in | The API | INVALID (BOLT-1095 named gateway; BOLT-1105 no route) |
| The gateway must offer card saving or token creation for the card type; checked only when a card type is known, so a call with no recognisable type skips it | The API | INVALID (BOLT-1096, tokenisation not available) |
| The gateway call itself failing (a connector error rather than a decline) abandons the call; nothing is stored | The API | INVALID (BOLT-1167) with the gateway's messages |
| A gateway decline is not an error: the method is stored INACTIVE with the gateway's reason in `gateway_status` and the call returns OK. Callers must read `status`; the hosted checkout does and shows the reason | The API and the hosted checkout | OK with `status` INACTIVE |
| Only one call per nonce runs at a time (a random one when none is sent); a second call with the same nonce while the first runs fails at once rather than waiting | The API | INVALID (BOLT-7059) |
| The nonce does not stop duplicates: once the first call completes, a second call with the same nonce and details stores a second method. Only a payment carries a duplicate-nonce rule (see [Take a one-off payment](/platforms/user-guides/rules-payment-take/)) | The API | silent; two methods |
| From the hosted checkout, two calls updating the **same saved method** are serialised: the second waits for the first rather than running alongside it. The key is the method's id, so a new-card submission (which has none) is keyed by the clock and nothing serialises it beyond the nonce rule above. This does not serialise payments, only the saving of a method, and two payments on the same saved card are unaffected | The API | second call waits |
| the hosted checkout offers a gateway for saving only when it can save cards or create tokens for the card type, the currency matches, the gateway is not running down and its routing rules allow the card; a currency whose maximum amount rule is zero is treated as disabled for saving | The hosted checkout | gateway or currency not offered |
| Registering a token directly: the gateway must exist, `token` is mandatory, `code` must be unique, and the session needs `account` on the account | The API | NOT_FOUND on "payment_gateway <id>" / MANDATORY on "token" / INVALID: "Invalid code" / NO_PERMISSION |
| Merchant View offers Add Payment Method only when the account's division has a WEB channel; the server has no such rule | Merchant View screen | control hidden |

### What happens

- A new saved method appears on the account and in the response, with `status` ACTIVE (ready to use; `sub_status` PENDING where a mandate is still being set up), REQAUTH with an `authorisation_url` the customer must complete, or INACTIVE with the gateway's reason in `gateway_status`. Nothing is charged.
- Where `contracts[]` was sent, those contracts switch to the new method as soon as it is ACTIVE (at once, or when the customer completes the authorisation) and any outstanding amount is collected straight away; see [Change the payment method on a contract](/platforms/user-guides/rules-contract-change-payment-method/). the hosted checkout warns the customer of that before they confirm.
- Webhook subscribers receive PAYMENT_METHOD.CREATED, then PAYMENT_METHOD.ACTIVE, PAYMENT_METHOD.PENDING or PAYMENT_METHOD.FAILED, and CONTRACT.UPDATE for each contract attached; a redirect-based method raises PAYMENT_METHOD.UPDATE and PAYMENT_METHOD.ACTIVE when it completes.
- An account named by CRM key that Shuttle did not know is registered; details sent with an existing account update its CRM record; an anonymous account is created when neither id nor CRM key is sent. In Merchant View the account screen reloads its saved methods when the checkout reports success.
- A payment link whose nonce was used is marked complete with the method.
- No email or SMS is sent by the tokenisation itself.

### Who can do this

- Roles: Admin and Support. From the hosted checkout, no operator role applies.
- Admin app: the `moto_tokenise` dashboard option, a WEB channel on the division, and a legal entity chosen when the division has more than one active; applies to the admin entry points only.
- Checkout form: `force_add` hides saved methods; a gateway feature can skip the confirm step; the save-card toggle is hidden in tokenise mode because saving is the point of the request.

### Related

- [Take a one-off payment](/platforms/user-guides/rules-payment-take/)
- [Change the payment method on a contract](/platforms/user-guides/rules-contract-change-payment-method/)
- [Archive a saved payment method](/platforms/user-guides/rules-payment-method-archive/)