Take a one-off payment

Takes a single payment from an account now: through the hosted checkout (an operator on the phone, or a customer on the merchant’s site or a payment link), or directly from an integration with a saved payment method or card details. The checkout call only prepares the session and the form; the money moves when the hosted checkout submits, and the payment is recorded as a one-off contract with a single charge and a PAYMENT (or AUTHORISE) transaction. This page also owns the rules every checkout submission shares, whatever shape of contract it creates: account resolution, channel and initiative selection, fraud blocking, gateway routing, the duplicate-nonce protection and the tamper check. Set up a recurring or scheduled agreement and Collect a contract’s arrears now link here for those rather than restating them.

Where you can do this

Merchant View: Account (New Payment)
Merchant View: Account header (New Payment)
The hosted checkout: Payment form (Process Payment)
API: Create a checkout (POST /checkouts) — frequency ONEOFF for an account
The hosted checkout: the hosted checkout submits a ONEOFF with no scheduled date or charge schedule; card, bank, wallet, gateway-hosted and offline paths all post here
The hosted checkout: completing the same payment after a 3DS or hosted redirect
API: Create a payment (POST /payments) — no contract named and frequency ONEOFF or absent, with no start_date / start_days, scheduled_date / scheduled_days or charges[]

Before you start

A web channel on the client that is not run down or archived; Merchant View offers New Payment only when the account’s client has one.
An initiative on that channel that can currently take payments (active, not deleted, inside its availability dates) and whose designation has a route for the account’s country.
An account: an existing one by id or crm_key, or, when the channel allows it, one created by the checkout from the details supplied (anonymous checkout).
A payment method the gateway accepts for the currency and the account’s country: card details, a saved method on the account, a bank account, a wallet token, or a gateway-hosted page.
From the hosted checkout: a checkout request for the channel, prepared by POST /c/api/checkout (or the legacy signed request the hosted checkout still accepts), that has finished building and has not expired.

Inputs

Names are as POST /c/api/checkout and POST /c/api/payments carry them. Fields that make the contract recurring, scheduled or a charge schedule belong to Set up a recurring or scheduled agreement; contract belongs to Collect a contract’s arrears now; both are accepted on the same calls.

Input	Required	Meaning and constraints
account	yes on the checkout; conditional on `POST /c/api/payments` (account, a crm_key, or a saved payment_method; otherwise an anonymous account is created)	An account id, or an object: id, crm_key (no spaces), first_name, last_name, email, phone, company, address (country as an ISO 3166-1 alpha-2 code, else it is blanked; line1 to line6), tags. Details supplied for an existing account update it; an unknown crm_key creates the account
gateway	no	Pins the gateway; otherwise routing picks it (see Rules)
default_amount	no (checkout only)	Pre-fills the amount; the customer or operator can change it
currency	conditional	Required with amount; ISO 4217. Fixed on the form when sent; otherwise the form offers the initiative’s currencies for the source
frequency	yes for this function	ONEOFF (absent on `POST /c/api/payments` also means ONEOFF when no charges[] are sent). Anything else is Set up a recurring or scheduled agreement
source	no	ECOMMERCE (default), MOTO or POS. MOTO and POS mark the operator as present; ECOMMERCE and POS mark the customer as present. Drives which gateways and methods are offered, the CVC and 3DS decisions and how the transaction is reported
action	no	PAYMENT (default) or AUTHORISE (AUTH and AUTHORIZE accepted) for an authorisation to capture later (Capture an authorised payment, Void an authorisation)
nonce	no	Idempotency key. `POST /c/api/checkout` generates one when absent; `POST /c/api/payments` does not, so a payment sent without one has no duplicate protection at all. The contract it creates is remembered against the nonce for 24 hours, or two years for a payment-link nonce (`pl_`), but that only governs the binding the checkout call reads: the duplicate check below is a fixed 24-hour window whatever the nonce
locale	no	Language for the form, the customer session and the receipt
alt_key	no	Your reference for the payment, stored as the contract’s alt_key
description	no	Goods or service description shown on receipts; default_description pre-fills it on the form
event_date	no	The date the payment relates to; gateway routing rules with a notice window are checked against it
tags	no	Comma-separated references stored on the account (inside account)
save_card	no	true stores the card as a saved payment method after the payment; false hides the option; absent lets the form’s configuration decide. default_save_card pre-ticks it. Storage is what Save a payment method without charging it does without a charge
payment_method	yes on `POST /c/api/payments` unless gateway_data or force_payment_method is sent	A saved payment method id, or an object: card_number, card_expiry (MMYY, MM/YY or YYYY-MM), card_cvc, card_type, cardholder_name, billing (country, line1 to line6), save_card, description; a bank account (iban with account_holder_name; or ach_routing_number, ach_account_number, ach_account_type, ach_account_holder_name); a gateway token (token with gateway); or a network token (cryptogram, eci, token_requestor_id, transaction_id)
force_payment_method	no (`POST /c/api/payments`)	Creates the contract even when no payment method can be resolved; meant for recurring agreements, see Set up a recurring or scheduled agreement
shipping	no (`POST /c/api/payments`)	Shipping address (country, line1 to line6) passed to the gateway
legal_entity / legal_entities	no	Pins the legal entity, or splits the amount across several (id, amount); split payments are authorised per entity and captured together
line_items / hotel_data	no (`POST /c/api/payments`)	Order lines and hotel data passed to the gateway for level-3 and lodging data
title / logo_url / checkout_text / footer_text	no (checkout only)	Presentation of the hosted checkout
success_url / cancel_url	no	Where the customer returns after a successful or abandoned 3DS or hosted step
success_post / success_email	no (checkout only)	A URL to POST the transaction and contract to, and addresses to email, when the payment succeeds
skip_receipt / disable_confirm / disable_close / enable_my_details / disable_account_login	no (checkout only)	Form behaviour: skip the receipt page, submit without the confirm step, hide close, show the customer’s details, hide login
payment_method_type	no (checkout only)	Restricts the form to the listed method types (CARDS expands to every card type)
avs_required / cvc_required	no (checkout only)	Force the address check and the CVC on the form
disable_saved_cards / force_add	no (checkout only)	Hide the account’s saved methods and force a new one

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 body must be present and a crm_key must not contain spaces	The API	VALIDATION_ERROR “API body error: missing checkout object” / “crm_key cannot inlcude spaces” (the message’s spelling is the server’s); `POST /c/api/payments`: VALIDATION_ERROR “API body error: missing payment object” / “crm_key cannot inlcude spaces”
A nonce is never required. `POST /c/api/checkout` generates one when absent; `POST /c/api/payments` forwards what the caller sent, so omitting it there forgoes the duplicate protection below. A nonce already bound to a contract cannot be used to prepare another checkout	The API	PROCESSING “duplicate nonce” (the contract is still in setup with a payment in flight) or DUPLICATE “duplicate nonce”, with the contract id
The checkout and its customer session live for expires seconds (default one day); afterwards the form cannot load it	The API	NOT_FOUND “checkout not found”
Values the hosted checkout collects must validate before it submits: a valid card number and expiry, the CVC when the customer is present, the billing address or postcode when the address check is required, name, email or phone when the configuration requires them, and the customer must acknowledge when the gateway cannot save the card	The hosted checkout only	the Confirm button stays disabled; nothing reaches the server
The channel must exist and be one the session can use	The API	BOLT-1108 “Internal Error: Invalid channel”, or VALIDATION_ERROR on the channel key
A nonce with a contract created in the last 24 hours that holds a successful, pending, unattributed or unresolved transaction is a duplicate and no second payment is taken. The window is 24 hours for every nonce, including a payment-link one whose binding is kept for two years: after a day the link’s nonce is refused at the checkout call but no longer by this check	The API, mirrored by the hosted checkout	status DUPLICATE, BOLT-1191 “Duplicate contract” with the existing contract and transaction identifiers and the receipt reference; the form shows “This payment has already been processed.” and offers Continue to the existing receipt; `POST /c/api/payments`: DUPLICATE “This nonce has been used for a successful or pending payment in the last 24 hours.” with contract, transaction and payment ids
Only one submission per nonce runs at a time, and only one payment per contract	The API	BOLT-7059; the form shows “It appears this payment is already in progress.” and retries for up to five minutes; `POST /c/api/payments`: INVALID (BOLT-7059)
An account given by id must exist; when a customer session is present it must be for that account (merged accounts resolve to the surviving account)	The API	BOLT-1131 “Invalid account”; BOLT-1105 “You do not have permission to complete this request”
An account given by crm_key that does not exist is created through the channel only when the channel allows registration	The API	BOLT-1187 “Registration is disabled.”; a lookup that fails for another reason: BOLT-1131 “Invalid account”
No account, no session and no saved method means an anonymous account is created from the details supplied, only when the channel allows anonymous checkout	The API	BOLT-1186 “Anonymous is disabled.”
The fraud screening service may block the customer session created for the payment	The API	status ERROR, BOLT-1188 with the fraud screening service’s reason as the message; no contract is created
An initiative key and an initiative code cannot both be given	The API	BOLT-1165
At least one initiative on the channel must be able to take payments: active or linked, not deleted, inside its availability dates, and selectable for the account’s country; a channel being run down offers none. An initiative pinned by the request that fails this is ignored and the others offered	The API	BOLT-7081 “There is not currently anything you can pay towards.”; the form shows the no-initiative error
The initiative’s designation must have a country route for the account’s country (and the pinned legal entity, when one is given)	The API	BOLT-1164
A new card, bank account or wallet needs a route: a legal entity currency for the currency, the method type and the account’s country (or the pinned gateway). A saved method whose gateway is archived has none	The API	BOLT-7085 “Sorry we could not process this type of payment (routing).”; BOLT-7185 “Sorry we could not process this type of payment (archived gateway).”
A card number is normalised to digits and its type derived when none is sent; a number that resolves to no supported type is refused	The API	BOLT-1193 “Could not resolve card number to a supported card type.”
A saved method must belong to the account, and its card type must be one the route accepts	The API	BOLT-7020 “Internal Error: The selected payment method does not exist”; BOLT-1189 “Your card details are not available to the processor for this payment, please select another card or re-enter details.”
A gateway token needs a gateway: the one named must exist, or exactly one active gateway with a currency route must exist to infer it	The API	BOLT-1195 “Invalid gateway”
Missing or invalid payment-method values leave the agreement unable to reach submission	The API	BOLT-1101 “Failed to create your agreement” with the field errors; `POST /c/api/payments` refuses first with VALIDATION_ERROR “Missing payment method” when no payment_method, gateway_data or force_payment_method is sent
A start date, scheduled date or charge schedule changes the contract’s shape; the rules for those are Set up a recurring or scheduled agreement’s. A contract named in the request makes it Collect a contract’s arrears now	The API	see those pages
A declined, errored or not-attempted payment is reported with the gateway’s message. The card details are discarded and a saved method that declined moves to FAILING	The API	status ERROR: BOLT-1176 “Sorry, but your payment was declined (gateway message). Please correct your details and retry.”, BOLT-1177 (temporary issue, retry), BOLT-1178 or BOLT-1278 (technical issue; the MOTO variant carries the gateway message), BOLT-1192 “This payment method is not available.” (method failed, expired or archived); the form shows the code and message
On `POST /c/api/payments` a payment that reached the gateway and was declined is not an error: the response is 200 with the payment in status DECLINED (INVALID_PAYMENT_METHOD when not attempted) and the gateway message. Only a failure that produced no contract or transaction, or a duplicate, is returned as an error	The API	200 with payment.status DECLINED; otherwise INVALID with the BOLT code, or DUPLICATE
A gateway that does not answer leaves the payment unresolved rather than declined	The API	the transaction is UNRESOLVED “No response from gateway (timeout)” and settled by the status check about ten minutes later
When the customer returns from a 3DS or hosted step, the nonce is checked again for a completed duplicate before the authorisation is completed	The API	BOLT-1191; the customer is sent to cancel_url with the message
The completion call re-runs submission for the same contract with the gateway reference verified; a contract that has already left setup returns its existing transaction rather than a second one	The API	as submission
The tokenise-only path (`action` TOKENISE) is Save a payment method without charging it, not this function	The API	see that page

What happens

A one-off contract is created for the account (the API reports it as type FIXED_AMOUNT_DUE_NOW and carries no frequency: ONEOFF is an input value, not one the response returns; the contract ends COMPLETED on success) with one charge and one PAYMENT transaction (AUTHORISE when action is AUTHORISE). The response carries the contract and transaction identifiers, the receipt reference and the gateway’s message; a declined payment comes back with status ERROR and the gateway’s reason, and a not-attempted one with “This payment method is not available.”.
On success PAYMENT.SUCCESS (PAYMENT.PENDING while a delayed-settlement method such as a bank debit clears) and ACCOUNT.UPDATE are raised, and the account’s last payment updates. No contract webhooks are raised for a one-off.
No receipt is emailed or texted to the payer automatically. The hosted checkout shows a receipt page at the end (unless skip_receipt is set), and the checkout’s success_email emails the addresses the checkout request names, but sending the payer a receipt of their own is the integrator’s to do.
On decline PAYMENT.FAILED and ACCOUNT.UPDATE are raised, the card details entered are discarded (except where the gateway said to call the bank, which keeps them so the customer can retry the same card), a saved method that declined moves to FAILING if it was ACTIVE or in error (one already failing or expired is left alone), and the same nonce can be retried straight away.
If the gateway needs 3DS or a hosted page the response carries a redirect URL; the payment completes when the customer returns and the form calls the completion endpoint, and success_post and success_email are then delivered.
With save_card, or when the customer ticks it, the card becomes a saved payment method on the account after the payment (PAYMENT_METHOD.ACTIVE).
A new account created by the checkout stays on the client with the checkout’s details; the hosted checkout is also handed an account session for it so the customer can see the receipt and their history.

Who can do this

Roles: Admin and Support. From the hosted checkout and POST /c/api/payments, no operator role applies.
Permission keys (for clients managing permissions directly): on the instance path, division, division_view or * on the application’s division, falling back to the client’s divisions; on the application-key or OAuth path, account, account_view or *. Updating an account whose crm_key already exists needs account, checkout or * on the client or the account’s divisions (UNAUTHORIZED “Unauthorized”). Merchant View shows the control to roles holding payment_contract.
When the recurring option is on, Merchant View leaves frequency open so the operator may also set up a recurring agreement from the same button (Set up a recurring or scheduled agreement).
Merchant View sends source MOTO, the account’s currency, default_occurrences 12 and no start date; it fixes nothing else, so the operator types the amount on the form.
Checkout form: save_card, payment_method_type, avs_required, cvc_required, disable_saved_cards and the presentation options above shape what the form offers; the channel configuration’s saved-card opt-in and disabled-saved-cards settings apply when the request says nothing.

Was this page helpful?