# Capture a Transaction Capture an authorized transaction. A captured transaction will be settled during the next scheduled batch closure and funds will be transferred from the cardholder's account to the merchant's account. This operation is only available for approved authorization requests. Endpoint: POST /v1/transactions/{id}/capture Version: 1.0.0-beta.27 Security: ApiKeyAuth ## Security: - `ApiKeyAuth` (unknown) apiKey in header Api-Key ## Path parameters: - `id` (string, required) The ID of the transaction to capture. You can find the transaction ID in the response of the original authorization transaction. ## Header parameters: - `Client-Id` (string, required) - `X-Acting-As-Client-Id` (string) The child client this request acts on behalf of. A reseller still authenticates as itself — `Api-Key` and `Client-Id` stay the reseller's — and names the child here. This works only from a parent to its own children. Merchants have no children, so a merchant calling as itself omits the header. Sending your own client ULID here is not the same as omitting it, and is rejected on some operations. ## Request fields (application/json): - `amount` (integer, required) Amount in cents (e.g. `10000` = $100.00). All transactions are in US dollars (USD). - `tip` (integer) Tip amount in cents (e.g. `1000` = $10.00). If no tip is included, use `0` or omit the field. `amount` is the whole charge and `tip` declares how much of it is gratuity. The two are not added together: a $100.00 bill with a $20.00 tip is `amount: 12000` with `tip: 2000`, and the cardholder is charged $120.00. The tip is reported to the processor separately at settlement and never increases the settled amount. Minimum 0 cents ($0.00). Maximum 99,999,999 cents ($999,999.99). All transactions are in US dollars (USD). ## Request examples: - `Capture a card authorization` (unknown) Captures the full $100.00 authorized by `authWithCard`. Send this to the transaction ID returned by that authorization. - `Capture a stored-token authorization` (unknown) Captures the full $100.00 authorized by `authWithToken`. The capture request body is identical whichever payment method the authorization used — only the response differs. ## Response 200: - `200` (unknown) Transaction captured successfully ## Response 200 fields (application/json): - `id` (string) Unique identifier for the transaction assigned by the API server. - `reference_transaction_id` (string | null) The `transaction_id` of the transaction that this request references, that is, the transaction that this request updated, captured, canceled, or refunded. Null for original transactions. - `type` (string) The type of transaction, as reported on a response. This is not the same set a request may ask for — see `TransactionCreateType`. A cancelled payment is reported as `CANCEL`, never as `VOID`. Enum: "SALE", "AUTH", "INCREMENTAL_AUTH", "PAYOUT", "REFUND", "CANCEL", "CAPTURE" - `result` (string) Enum: "APPROVED", "DECLINED", "ERROR" - `client_id` (string) The `client_id` of the client account that requested this transaction. - `client_dba` (string) Doing Business As (DBA) name of the client account. - `integrations` (array) Third-party integrations tied to the merchant account for this transaction. Includes the payment processor that processed the payment and may include additional services (e.g. network token providers) as offerings expand. - `response_code` (string) Response code generated by the payment processor. - `response_description` (string) Human-readable description of the transaction outcome. - `batch_id` (string | null) Unique identifier of the batch containing this transaction. Null when the transaction has not yet been assigned to a batch. - `is_settled` (boolean) Whether the transaction is settled. - `settlement_issue` (string | null) An issue preventing the transaction from settling. Null when there is no issue — because the transaction was canceled, has already settled, or is still in an open batch. Read `is_settled` to see whether it settled. Enum: "REMOVED_FROM_BATCH", null - `is_returned` (boolean) Whether the transaction has been returned by the processor. A return is a transaction outcome rather than an API error, it arrives days after the transaction was approved, and it can follow a transaction that has already settled - so read this alongside `is_settled` rather than instead of it. Always false on a card transaction. - `returned_at` (string | null) The time the processor sent the return. In ISO-8601 format (YYYY-MM-DDTHH:MM:SS.SSSZ), UTC, matching `time_created`. Null when the transaction has not been returned. - `return_code` (string | null) The NACHA return code, three characters. Omitted entirely when the transaction has not been returned, and omitted on a returned transaction the processor sent no code for - not sent as null. - `return_reason` (string | null) Human-readable description of the reason the processor returned the transaction. Omitted entirely when the transaction has not been returned, the way `return_code` is - not sent as null. - `time_created` (string) the API server generated time indicating when the object was created. In ISO-8601 format (YYYY-MM-DDTHH:MM:SS.SSSZ). - `amount` (integer) Amount in cents (e.g. `10000` = $100.00). All transactions are in US dollars (USD). - `tip` (integer) Tip amount in cents (e.g. `1000` = $10.00). If no tip is included, use `0` or omit the field. `amount` is the whole charge and `tip` declares how much of it is gratuity. The two are not added together: a $100.00 bill with a $20.00 tip is `amount: 12000` with `tip: 2000`, and the cardholder is charged $120.00. The tip is reported to the processor separately at settlement and never increases the settled amount. Minimum 0 cents ($0.00). Maximum 99,999,999 cents ($999,999.99). All transactions are in US dollars (USD). - `currency` (string) Three-letter ISO 4217 currency code for the transaction. - `payment_method` (any) Base schema for payment methods returned on a transaction response. Concrete subtypes are discriminated by the `type` property. A response reports the underlying instrument, so `type` is `CARD` or `ACH`. Paying with a token is not a third kind of response: send `payment_method.type` of `Token` and the gateway resolves the token to the card or bank account behind it, then reports that. The token itself comes back in `payment_token` on either subtype. - `payment_method.type` (string, required) The type of payment method returned on a response. A request supplies a different set of values — see `PaymentMethodTypeInput`. A token-funded transaction reports the instrument the token resolves to, so there is no separate token value here. `PaymentMethodTypeInput` still accepts `Token` on the way in. Enum: "ACH", "CARD" - `payment_method.standard_entry_class` (string) ACH Standard Entry Class (SEC) code that defines the transaction type and authorization method. Enum: "PPD", "CCD", "WEB", "TEL", "POP", "BOC" - `payment_method.account_type` (string) The type of bank account. Enum: "CHECKING", "SAVINGS" - `payment_method.route_number_truncated` (string) Nine-digit ABA routing number truncated to the last 4 digits. - `payment_method.account_number_truncated` (string) Bank account number truncated to the last 4 digits. - `payment_method.payment_token` (string | null) Reference to a previously stored (tokenized) payment method. Null when tokenization was not performed or failed. - `payment_method.first_name` (string) Account holder's first name. On a transaction response this is the name submitted with the request. On a reporting response it is derived by splitting the stored account holder name at the last space, so a single-word stored name returns an empty string here and puts the whole name in `last_name`. - `payment_method.last_name` (string) Account holder's last name. - `payment_method.description` (string) Optional information to include on customer's bank statement. This is a short description that, e.g., identifies the goods or services purchased or the merchant's name. If left blank, the merchant's name will be used as a default description. - `payment_method.truncated_pan` (string) Masked card number with only the last 4 digits visible (e.g. `****1111`). - `payment_method.expiry` (any) Card expiration date. Null on capture/void/refund responses where expiry is not echoed back. - `payment_method.expiry.month` (string, required) Month of the card expiration date as a two-digit number - `payment_method.expiry.year` (string, required) Year of the card expiration date as a four-digit number. - `payment_method.first_name` (string | null) First name of the cardholder. Null if not provided. - `payment_method.last_name` (string | null) Last name of the cardholder. Null if not provided. - `payment_method.entry_method` (string) How the card payment method was entered (e.g. `keyed`, `swiped`, `chip`, `contactless`, `magstripe`, `barcode`, `qr`, `other`). - `payment_method.auth_code` (string) Authorization code generated by the card provider when the card is successfully authorized. - `payment_method.retrieval_reference_number` (string | null) The retrieval reference number (RRN) is a 12-character alphanumeric identifier assigned to a card transaction to allow the tracking of a specific transaction record. - `payment_method.card_type` (string) The type of card. `UNKNOWN` is returned when the processor cannot determine the card type. Enum: "DEBIT", "CREDIT", "UNKNOWN" - `payment_method.card_brand` (string) Card network brand (e.g. `Visa`, `Mastercard`, `Amex`, `Discover`). - `payment_method.cvv_result_code` (string | null) The result returned from a card verification value check. Null on void/refund responses where CVV is not re-checked. - `payment_method.avs_result_code` (any) The result of the Address Verification Service (AVS) check. May be a single-letter string code or integer `0` when AVS was not performed. - `payment_method.avs_response` (string) Human-readable AVS response message. - `recurring` (boolean) Whether the transaction is part of a recurring payment agreement. - `initiator` (any) Who initiated the transaction. Null on a transaction read back through `GET /v1/transactions/{id}`, which does not currently return the value supplied on create. Tracked as a gateway defect — treat the value from the create response as authoritative. - `recurring_details` (any) Stored-credential details for the recurring agreement this transaction belongs to. Null on a one-off transaction. - `recurring_details.sequence` (string, required) The position of this transaction within a recurring payment agreement. Enum: "INITIAL", "SUBSEQUENT" - `recurring_details.initial_transaction_id` (string | null) The transaction ID of the initial customer-initiated (CIT) transaction that established the recurring payment agreement. Required when `sequence` is `SUBSEQUENT`; omit (or send `null`) on the `INITIAL` transaction. - `recurring_details.initial_network_transaction_id` (string | null) The network-assigned transaction identifier (Visa Transaction ID / Mastercard Trace ID) returned on the initial authorization that established the agreement. Supply this only when the initial transaction was processed outside this gateway (e.g. migration from another provider). When `initial_transaction_id` references a transaction processed by this gateway, the network ID is resolved automatically and this field may be omitted. - `network_transaction_id` (string | null) The network-assigned transaction identifier (Visa Transaction ID / Mastercard Trace ID) assigned by the card network. On the initial transaction of a recurring agreement, store this value and supply it as `recurring.initial_network_transaction_id` on subsequent transactions billed against the agreement (required when those transactions are processed by a different gateway). Null when the network did not return an identifier. - `metadata` (object | null) Key-value pairs for storing additional information on the transaction. Send `null` to clear all metadata. At most 50 keys. Keys may contain letters, digits, hyphens, and underscores, up to 40 characters. Values are strings up to 500 characters. Every limit below is enforced; a request that exceeds any of them is rejected. ## Response 200 headers (application/json): - `x-request-id` (string, required) Unique identifier assigned to the request by the API server. Returned on every response, including errors. Log this value and supply it when contacting support so that a specific request can be traced. ## Response 400: - `400` (unknown) Bad request ## Response 400 fields (application/json): - `error_code` (string) The Gateway generated error code. - `error_message` (string) Human-readable explanation that is specific to this occurrence of the problem. - `details` (object | null) The field in the request that caused the error. May be null if not applicable. - `source` (object | null) Object containing host-processor-specific error information. May be null if not applicable. - `source.system` (string | null) The host processor name. - `source.code` (string | null) The host processor code. - `source.message` (string | null) The host processor message. ## Response 400 headers (application/json): - `x-request-id` (string, required) Unique identifier assigned to the request by the API server. Returned on every response, including errors. Log this value and supply it when contacting support so that a specific request can be traced. ## Response 401: - `401` (unknown) Not authenticated ## Response 401 fields (application/json): - `error_code` (string) The Gateway generated error code. - `error_message` (string) Human-readable explanation that is specific to this occurrence of the problem. - `details` (object | null) The field in the request that caused the error. May be null if not applicable. - `source` (object | null) Object containing host-processor-specific error information. May be null if not applicable. - `source.system` (string | null) The host processor name. - `source.code` (string | null) The host processor code. - `source.message` (string | null) The host processor message. ## Response 401 headers (application/json): - `x-request-id` (string, required) Unique identifier assigned to the request by the API server. Returned on every response, including errors. Log this value and supply it when contacting support so that a specific request can be traced. ## Response 403: - `403` (unknown) Forbidden ## Response 403 fields (application/json): - `error_code` (string) The Gateway generated error code. - `error_message` (string) Human-readable explanation that is specific to this occurrence of the problem. - `details` (object | null) The field in the request that caused the error. May be null if not applicable. - `source` (object | null) Object containing host-processor-specific error information. May be null if not applicable. - `source.system` (string | null) The host processor name. - `source.code` (string | null) The host processor code. - `source.message` (string | null) The host processor message. ## Response 403 headers (application/json): - `x-request-id` (string, required) Unique identifier assigned to the request by the API server. Returned on every response, including errors. Log this value and supply it when contacting support so that a specific request can be traced. ## Response 404: - `404` (unknown) Not Found ## Response 404 fields (application/json): - `error_code` (string) The Gateway generated error code. - `error_message` (string) Human-readable explanation that is specific to this occurrence of the problem. - `details` (object | null) The field in the request that caused the error. May be null if not applicable. - `source` (object | null) Object containing host-processor-specific error information. May be null if not applicable. - `source.system` (string | null) The host processor name. - `source.code` (string | null) The host processor code. - `source.message` (string | null) The host processor message. ## Response 404 headers (application/json): - `x-request-id` (string, required) Unique identifier assigned to the request by the API server. Returned on every response, including errors. Log this value and supply it when contacting support so that a specific request can be traced. ## Response 409: - `409` (unknown) Conflict ## Response 409 fields (application/json): - `error_code` (string) The Gateway generated error code. - `error_message` (string) Human-readable explanation that is specific to this occurrence of the problem. - `details` (object | null) The field in the request that caused the error. May be null if not applicable. - `source` (object | null) Object containing host-processor-specific error information. May be null if not applicable. - `source.system` (string | null) The host processor name. - `source.code` (string | null) The host processor code. - `source.message` (string | null) The host processor message. ## Response 409 headers (application/json): - `x-request-id` (string, required) Unique identifier assigned to the request by the API server. Returned on every response, including errors. Log this value and supply it when contacting support so that a specific request can be traced. ## Response 500: - `500` (unknown) Internal server error ## Response 500 fields (application/json): - `error_code` (string) The Gateway generated error code. - `error_message` (string) Human-readable explanation that is specific to this occurrence of the problem. - `details` (object | null) The field in the request that caused the error. May be null if not applicable. - `source` (object | null) Object containing host-processor-specific error information. May be null if not applicable. - `source.system` (string | null) The host processor name. - `source.code` (string | null) The host processor code. - `source.message` (string | null) The host processor message. ## Response 500 headers (application/json): - `x-request-id` (string, required) Unique identifier assigned to the request by the API server. Returned on every response, including errors. Log this value and supply it when contacting support so that a specific request can be traced. ## Response 502: - `502` (unknown) The gateway reached the downstream processor and could not use its response. Distinct from a 500, which is a fault inside the gateway. ## Response 502 fields (application/json): - `error_code` (string) The Gateway generated error code. - `error_message` (string) Human-readable explanation that is specific to this occurrence of the problem. - `details` (object | null) The field in the request that caused the error. May be null if not applicable. - `source` (object | null) Object containing host-processor-specific error information. May be null if not applicable. - `source.system` (string | null) The host processor name. - `source.code` (string | null) The host processor code. - `source.message` (string | null) The host processor message. ## Response 502 headers (application/json): - `x-request-id` (string, required) Unique identifier assigned to the request by the API server. Returned on every response, including errors. Log this value and supply it when contacting support so that a specific request can be traced. ## Response 200 examples: - `Capture a card authorization — approved` (unknown) The capture record. It is a new transaction whose `reference_transaction_id` points at the authorization it captured. `expiry` is null because expiry is not echoed back on capture responses. `batch_id` is now assigned, so the funds settle at the next batch close. - `Capture a stored-token authorization — approved` (unknown) The capture record for a token authorization. `payment_method` reports the card the token resolves to, with `expiry` null because a capture does not echo it, and `reference_transaction_id` points at the authorization it captured. ## Response 400 examples: - `Invalid field value in the request body` (unknown) ## Response 401 examples: - `Missing or invalid API key` (unknown) ## Response 403 examples: - `Authenticated but not authorized for this action` (unknown) ## Response 404 examples: - `Resource ID does not exist` (unknown) ## Response 409 examples: - `Duplicate or state-conflicting action` (unknown) ## Response 500 examples: - `Unhandled server fault or downstream processor error` (unknown) ## Response 502 examples: - `The processor returned an invalid or unexpected response` (unknown) Distinct from a 500. A 500 is a fault inside the gateway; a 502 means the gateway reached the processor and could not use what came back. Both are safe to retry, but only a 502 says the transaction may have been seen by the processor — reconcile before retrying a payment.