Capture an authorised payment

Takes some or all of the money an earlier authorisation reserved. The capture is its own transaction (a ca_ id) attached to the authorisation: it is sent to the gateway, settles the account's open charges on the contract, and moves the contract's paid and completed totals exactly as a payment does. What is left authorised stays open for a later capture where the gateway allows one, or can be released with Void an authorisation. An authorisation is never refunded; capture it first, then refund the capture (Refund a payment).

Where you can do this

Merchant View: Capture a transaction (Capture)
API: Capture a payment (POST /payments/{payment_id}/capture) — amount up to the authorised amount

Before you start

The source is an authorisation (action AUTH) with an amount above zero and something still uncaptured and unvoided. Its status may be SUCCESS, PENDING, UNATTRIBUTED or UNRESOLVED; DECLINED, INVALID_PAYMENT_METHOD and REQAUTH cannot be captured.
The gateway the authorisation was taken on is active, not archived or inactive.
Fewer than ten captures already exist on the authorisation.
From Merchant View: the option manual_capture is on, the authorisation still reports an amount authorised (which it does only while SUCCESS or PENDING), and, once something has been captured, the gateway advertises MULTI_CAPTURE for the payment method type.

Inputs

Input	Required	Meaning and constraints
amount	no	Decimal as a string (`"50.00"`), above zero and no more than what is left to capture. Omitted: the authorisation's amount less what has already been captured and voided (which ignores any maximum capturable amount the gateway set; see Rules)

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
`:id` must resolve to an AUTHORISE transaction: a `pay_`, `ca_` or `tr_` id is fetched directly, anything else is searched as the `alt_key` of an authorisation, newest first	The API	NOT_FOUND: "Payment not found"
An `alt_key` that matches two authorisations, the older created within the last six months, is ambiguous	The API	INVALID_REQUEST: "Duplicate alt_key"
At most ten captures per authorisation. The count includes captures that failed, and Shuttle enforces no limit of its own	The API	VALIDATION_ERROR: "You can only capture 10 times."
The source must be an authorisation	The API	INVALID (HTTP 400) carrying the message for `apiValidation.error.no.capture.type`
The authorisation must not be DECLINED, INVALID_PAYMENT_METHOD or REQAUTH. SUCCESS, PENDING, UNATTRIBUTED and UNRESOLVED are all accepted	The API	INVALID carrying the message for `apiValidation.error.no.capture.status`
The authorisation's amount must be above zero	The API	INVALID carrying the message for `apiValidation.error.no.capture`
`amount` must be above zero and no more than what is left: the authorisation's amount, or the maximum capturable amount the gateway set when there is one and `amount` is given, less what has already been captured and voided. An authorisation with nothing left is refused the same way	The API	INVALID carrying the message for `apiValidation.error.invalid.amount`
The gateway the authorisation was taken on must not be archived or inactive	The API	INVALID (BOLT-7185)
Only one capture of an authorisation runs at a time; Shuttle takes a lock and does not wait for it	The API	INVALID (BOLT-7059)
A gateway decline is not an error response: the call returns the capture with status DECLINED and the gateway's `gateway_message`; a connector that gives no usable answer leaves it UNRESOLVED, also returned as a result. Only a connector that raises an exception fails the call	The API	HTTP 200 with `capture.status` DECLINED or UNRESOLVED; INVALID (BOLT-7010) on a connector exception
The server has no notion of "one capture only": a second capture is allowed whenever the amounts allow it, and whether the gateway accepts it is the gateway's business. The MULTI_CAPTURE feature the gateway advertises is applied by Merchant View only	The API	none
A capture is not checked against what the contract still owes, unlike a payment. It settles the account's open charges oldest due first, and where it exceeds a charge, instalment or part the amount due is raised to what was captured; money that finds no open charge is still added to the contract's paid and completed totals	The API	none
Authorisation expiry is not checked, by the app or by the server: the gateway decides. The capture screen warns once the expiry date has passed, within two days of it, or from five days after an authorisation that carries no expiry date, but does not block; the transaction screen drops only its "open" badge and still offers Capture and Void	Merchant View screen and gateway	"This authorisation expired {date}. Capturing may be declined by the issuing bank." or "This authorisation is {n} days old. Capturing may be declined by the issuing bank."; then the gateway's decline message
The `manual_capture` option gates the Capture and Void controls, not the screen: the capture screen is still reachable by its address with `payment_transaction` alone, and the server applies no option check	Merchant View screen and the API	none
Merchant View requires a partial amount of at least one minor unit and no more than what is left authorised; the server accepts any number of decimals	Merchant View screen	Capture button disabled

What happens

The caller receives the capture (ca_ id, amount, balance, reference, status, gateway_status, gateway_message, gateway_reference, processed, parts, and payment, the authorisation it came from) with status SUCCESS, PENDING, DECLINED, UNRESOLVED or UNATTRIBUTED. A decline still returns HTTP 200, so check status.
On success the money is taken: the authorisation shows the captured amount and less left authorised, the captured amount settles the account's open charges on the contract oldest due first, and the contract's paid and completed totals rise with it. A contract still in setup becomes ACTIVE, and one with nothing left outstanding and no next charge becomes COMPLETED.
No receipt is emailed or texted to the payer when a capture succeeds; sending one is the integrator's to do.
Webhooks: CAPTURE.SUCCESS, CAPTURE.PENDING, CAPTURE.FAILED or CAPTURE.UNRESOLVED for the capture, PAYMENT.UPDATE for the authorisation, and ACCOUNT.UPDATE; CHARGE.COMPLETE for each charge the capture completes, and CONTRACT.START, CONTRACT.UPDATE or CONTRACT.COMPLETE for the contract. A one-off due at once raises none of the contract or charge events. PAYMENT.SUCCESS and PAYMENT.FAILED are still raised for the capture as deprecated duplicates of the CAPTURE events.
A capture the gateway declines moves the contract to FAILING and the payment method to FAILING, counts a failure against the contract, and re-arms the retry schedule of a recurring contract or a one-off with a scheduled date so the arrears process picks it up. A capture the gateway leaves unresolved moves the contract to UNRESOLVED.
What is left authorised stays open: capture it again where the gateway allows a second capture, or release it with Void an authorisation. The capture itself can be refunded (Refund a payment); the authorisation cannot.

Who can do this

Roles: Admin only. Support holds none of the keys Shuttle accepts, and captures are deliberately withheld from it.
Permission keys (for clients managing permissions directly): Shuttle requires one of agreement, payment_contract, payment_transaction or * on the client or on the authorisation's division; Admin's * satisfies it. Shuttle runs no permission check for this operation, so Shuttle's is the only one. Without a key the caller sees UNAUTHORIZED (HTTP 401) "Unauthorized". A session bound to the authorisation's own account also passes the check, so a customer session for the payer can capture their own authorisation. Accepting agreement and payment_contract means a role given contract write but not transaction write can capture, which principle 1 says it must not. Merchant View instead requires payment_transaction (or *) on any object, both to open the capture screen and to show the Capture control.
Admin app options: manual_capture shows the Capture and Void controls on an authorisation. It gates the controls only; see Rules.
API keys: an instance session reaches the route with the same server check. A token whose scope is * acts as Admin; tokens limited to the read-only or payment-links scopes carry view keys only and cannot capture.