--- title: "Capture a payment" method: POST path: "/payments/{id}/captures" tags: ["Payments"] --- # Capture a payment `POST /payments/{id}/captures` ## Request - Base URL: `https://{prefix}.api.sandbox.checkout.com` - URL: `https://{prefix}.api.sandbox.checkout.com/payments/{id}/captures` - Auth: one of: - OAuth 2 - Client credentials - Token URL: `string` scopes: `gateway`, `gateway:payment-captures` - API key in header `Authorization` - TypeScript: (a function with typed inputs; its response is checked against the schema) Captures a payment if supported by the payment method. For card payments, capture requests are processed asynchronously. You can use [workflows](#tag/Workflows) to be notified if the capture is successful. ## Path parameters - `id` string, required ## Headers - `Cko-Idempotency-Key` string ## Request body - CaptureRequest - `amount` integer: The amount to capture. If not specified, the full payment amount will be captured. - `capture_type` 'NonFinal' | 'Final': The type of capture. If set to `Final`, the remaining available-to-capture balance will be voided. - `reference` string: A reference you can later use to identify this capture request.
For Amex, the string limit is 30 characters. - `customer` CustomerRequest: The customer's details. Required if `source.type` is `tamara` - `id` string: The identifier of an existing customer - `email` string, email: The customer's email address. If `source.type` is set to `sequra`, this field is required. If `source.type` is set to `tamara`, this field is required and has a maximum length of 50 characters. - `name` string: The customer's name. Required if `source.type` is: - `alipay_cn` - `alipay_hk` - `alipay_plus` - `dana` - `gcash` - `kakaopay` - `sequra` - `tamara` - `tng` - `truemoney` - `tax_number` string: Contains the customer's value-added tax (VAT) registration number. - `phone` PhoneNumber: A phone number - `country_code` string: The international country calling code. Required if `source.type` is `tamara`. - `number` string: The phone number. Required if `source.type` is `tamara`. - `summary` CustomerSummary: Summary of the customer's transaction history.
Used for risk assessment when `source.type` is `Tamara` - `registration_date` string, date: The date the customer registered. - `first_transaction_date` string, date: The date of the customer's first transaction. - `last_payment_date` string, date: The date of the customer's last payment. - `total_order_count` integer: The total number of orders made by the customer. - `last_payment_amount` number, float: The amount of the customer's last payment. - `is_premium_customer` boolean: Specifies whether the customer is a premium customer. - `is_returning_customer` boolean: Specifies whether the customer is a returning customer. - `lifetime_value` number, float: The customer's lifetime value. This is the total monetary amount that the customer has ordered, in their local currency, excluding the following: - canceled orders - rejected payments - refunded payments - Tamara payments The lifetime value is an indicator of how valuable the relationship with the customer is to your company. - `description` string: A description of the payment. - `billing_descriptor` BillingDescriptor: An optional description that is displayed on the customer's statement identifying a purchase. - `name` string, required: A dynamic description of the payment. Applies to card payments only. - `city` string, required: The city from which the payment originated. Applies to card payments only. - `reference` string: The reference that should be shown on the statement. Required for payouts to bank accounts. - `local_descriptors` LocalBillingDescriptor[], nullable - `name` string, required: A dynamic description of the card payment. Other payment methods will not display this description. The character set specified will determine the maximum length of the field. For `katakana`, the maximum length is 23 characters, equivalent to 23 katakana characters. For `kanji`, the maximum length is 40 characters, equivalent to 20 kanji characters. - `character_set` 'kanji' | 'katakana', required: The character set of the descriptor - `shipping` object: The shipping details. - `address` Address - `address_line1` string: The first line of the address. - `address_line2` string: The second line of the address.

For SEPA payments, this value has a maximum length of 10 characters. - `city` string: The address city. - `state` string: The state or province of the address country ISO 3166-2 code (for example: CA for California in the United States). - `zip` string: The address zip or postal code. - `country` string: The two-letter ISO country code of the address. - `phone` PhoneNumber: A phone number - `country_code` string: The international country calling code. Required if `source.type` is `tamara`. - `number` string: The phone number. Required if `source.type` is `tamara`. - `from_address_zip` string: The postal code or zip code of the location being shipped from. - `tracking_info` TrackingInfo[]: The tracking information for the payment capture. - `return_shipping_company` string: Name of the shipping company for the return shipment (as specific as possible). - `return_tracking_number` string: Tracking number for the return shipment. - `return_tracking_uri` string: URL where the customer can track the return shipment. - `shipping_company` string: Name of the shipping company (as specific as possible) - `tracking_number` string: Tracking number for the shipment. - `tracking_uri` string: URI where the customer can track their shipment. - `items` object[]: The order's line items. - `type` 'digital' | 'discount' | 'physical': The item type. For example, `physical` or `digital`. This field is used to provide item level metadata where applicable. If `source.type` is `sequra`, this field is required. - `sub_type` 'blockchain' | 'cbdc' | 'cryptocurrency' | 'nft' | 'stablecoin': The digital item type. If `type` is set to `digital`, this field is required. - `name` string: The descriptive name of the line item. If `source.type` is `sequra`, this field is required. - `quantity` integer: The number of line items. If `source.type` is `sequra`, this field is required. - `unit_price` integer: The unit price of the item the minor currency unit. Required if `source.type` is `sequra` - `reference` string: The item reference or product SKU (stock-keeping unit). For Visa and Mastercard's interchange reduction programs, this value has a maximum length of 12 characters. If `source.type` is `sequra`, this field is required. - `commodity_code` string: A code identifying a Commodity for value-added tax (VAT) purposes. - `unit_of_measure` string: Unit of Measure code used for an item in transaction. - `total_amount` number: The total cost of the line item, in minor currency units. Calculate this using the following formula: `total_amount` = (`quantity` * `unit_price`) - `discount_amount`. If `source.type` is `sequra`, this field is required. - `tax_rate` number: The tax rate of the item line in minor units. The percentage value is represented with two implicit decimals. For example, 2000=20%. - `tax_amount` number: Contains the total amount of sales tax or value-added tax (VAT) on the total purchase amount. Tax should be included in the total purchase. - `tax_exempt` boolean: Indicates whether the products or services are tax-exempt.

Set to `true` if: - You are processing a card payment. - The `tax_amount` field is `0` due to a tax-exempt product or service. - `discount_amount` number: The discount applied to each invoice line item. - `wxpay_goods_id` string: Unified product No. defined by WeChat Pay - `url` string: Link to the line item's product page - `image_url` string: Link to the line item's product page - `service_ends_on` string, date: Maximum date for the service to be rendered or ended. If `source.type` is `sequra` and `item.type` is `digital`, this field is required. - `purchase_country` string: The country where the purchase was made.
Format – ISO alpha-2 country code - `foreign_retailer_amount` integer: The foreign retailer amount the merchant applied to the transaction, in the [minor currency unit](https://www.checkout.com/docs/payments/accept-payments/format-the-amount-value). - `amount_allocations` object[]: The sub-entities that the payment is being processed on behalf of - `id` string, required: The id of the sub-entity. - `amount` integer, required: The split amount - this will be credited to your sub-entity's currency account. The sum of all split amounts must be equal to the payment amount. The amount must be provided in the minor currency unit. - `reference` string: A reference you can later use to identify this split, such as an order number. - `commission` object: Commission you'd like to collect from this split - this will be credited to your currency account. The commission cannot exceed the split amount. Commission = (`amount` * `commission.percentage`) + `commission.amount` - `amount` integer: Optional fixed amount of commission to collect. The amount must be provided in the minor currency unit. - `percentage` number: Optional percentage of commission to collect. Supports up to 8 decimal places. - `processing` CaptureRequestProcessingSettings: Use the processing object to influence or override the data sent during card processing - `order_id` string: The number provided by the cardholder. Purchase order or invoice number may be used. - `otp_value` string: One time password sent to customer by SMS. - `tax_amount` number: The total amount of sales tax on the total purchase amount. - `surcharge_amount` integer: Surcharge amount applied to the partial capture transaction in minor units by the merchant - `discount_amount` number: The discount amount applied to the transaction by the merchant. - `duty_amount` number: The total charges for any import/export duty included in the transaction. - `shipping_amount` number: The total freight or shipping and handling charges for the transaction. - `shipping_tax_amount` number: The tax amount of the freight or shipping and handling charges for the transaction. - `purchase_country` string: The country where the goods are purchased or the seller is based. ISO 3166 alpha-2 purchase country code. - `foreign_retailer_amount` integer: The amount of the transaction that originates from a foreign retailer, in the [minor currency unit](https://www.checkout.com/docs/payments/accept-payments/format-the-amount-value). - `metadata` object: A set of key-value pairs to attach to the authorization request. You can use this to store additional information in a structured format. The `metadata` object only supports primitive data types. Objects and arrays are not supported. ## Response `200` Payment is already captured - object: The response received when you attempt a repeated payment action. For example, if you attempt to refund a payment that is already refunded. - `action_id` string, required: The action identifier - `_links` object: Links related to the payment. - `payment` Link, required - `href` string, required: The link URL ## Other responses - `202`: Capture accepted - `401`: Unauthorized - `403`: Capture not allowed - `404`: Payment not found - `422`: Invalid data was sent - `502`: Bad gateway --- [API](https://skmtc.dev/checkout/apis/checkout-com-api-reference.md) - [All operations](https://skmtc.dev/checkout/apis/checkout-com-api-reference/llms.txt) - [OpenAPI document](https://skmtc.dev/checkout/apis/checkout-com-api-reference/revisions/0f1abdb1c3e9?raw)