> For the complete documentation index, see [llms.txt](https://docs.hyperswitch.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hyperswitch.io/integration-guide/payment-suite/payments/manual-capture.md). # Manual Capture Place a hold on your customers' funds and capture them later, fully or partially, in one capture or several {% embed url="" %} In most online payments the merchant captures funds in one step, right after the issuer authorizes. Hyperswitch calls that the automatic capture flow. Manual capture splits it in two. The authorization places a hold on the customer's funds, and you capture later, once you have shipped the goods or delivered the service. The industry calls this auth and capture, or the two-step flow. ### Why use it 1. You capture only after you have delivered, so you control when the customer is charged. 2. You can capture the full authorized amount or part of it. 3. The customer sees a charge that matches what they received. ### Choose a capture method before you authorize `capture_method` is set at payment creation and decides everything that follows, including whether an uncaptured remainder survives. The wire values are: | `capture_method` | What it does | | ---------------------- | -------------------------------------------------------------------------------------------------------------- | | `automatic` | Default. Authorization and capture happen together. The capture endpoint rejects it. | | `manual` | One capture only. Capture the whole hold or part of it, once. | | `manual_multiple` | Several captures against one authorization, up to the authorized amount. | | `scheduled` | Not implemented. Accepted as a wire value, but payment create and update reject it with `501 Not Implemented`. | | `sequential_automatic` | Separate authorization and capture run back to back, like `automatic`. | Do not build against `scheduled`: it is declared in the enum and published in the spec, but every payment create or update carrying it returns `501 Not Implemented` before the payment is touched. To capture at a later time, use `manual` or `manual_multiple` and call the capture endpoint when you are ready. Pick `manual_multiple` at creation if you might capture in more than one go. You cannot change your mind after authorizing: with `manual`, whatever you do not take in the single capture call stops being capturable. ### How to do manual capture #### Step 1. Create the payment with deferred capture Set `"capture_method": "manual"` when you create the payment from your server. Omitting `capture_method` gives you `automatic`. **Sample curl:** ```bash curl --location 'https://sandbox.hyperswitch.io/payments' \ --header 'Content-Type: application/json' \ --header 'Accept: application/json' \ --header 'api-key: ' \ --data '{ "amount": 6540, "currency": "USD", "confirm": false, "capture_method": "manual", "authentication_type": "no_three_ds", "return_url": "https://duck.com", "billing": { "address": { "line1": "1467", "line2": "Harrison Street", "line3": "Harrison Street", "city": "San Fransico", "state": "California", "zip": "94122", "country": "US", "first_name": "John" } } }' ``` #### Step 2. Confirm, which authorizes [Confirm](https://api-reference.hyperswitch.io/v1/payments/payments--confirm) the payment after you collect the payment method details, and tell the customer their funds will be held and charged later. Unified checkout does this for you. On successful authorization the payment moves to `requires_capture`. You can also set `"confirm": true` in step 1 and go straight to capture. **Sample curl:** ```bash curl --location 'https://sandbox.hyperswitch.io/payments//confirm' \ --header 'Content-Type: application/json' \ --header 'Accept: application/json' \ --header 'api-key: ' \ --data '{ "payment_method": "card", "client_secret": "", "payment_method_data": { "card": { "card_number": "4242424242424242", "card_exp_month": "10", "card_exp_year": "25", "card_holder_name": "joseph Doe", "card_cvc": "123" } } }' ``` #### Step 3. Capture Call [`POST /payments/{payment_id}/capture`](https://api-reference.hyperswitch.io/v1/payments/payments--capture). Omit `amount_to_capture` and the whole of `amount_capturable` is captured. Pass it to capture less. **Sample curl:** ```bash curl --location 'https://sandbox.hyperswitch.io/payments//capture' \ --header 'Content-Type: application/json' \ --header 'Accept: application/json' \ --header 'api-key: ' \ --data '{ "amount_to_capture": 6540, "statement_descriptor_name": "Joseph", "statement_descriptor_suffix": "JS" }' ``` The endpoint rejects `capture_method: automatic` outright. It accepts the payment only in `requires_capture`, `partially_captured_and_capturable`, `partially_authorized_and_requires_capture`, or `processing`, and `processing` only when the capture method is `manual_multiple`. `amount_to_capture` must be greater than zero and no greater than the current `amount_capturable`. The only exception is a payment with overcapture enabled, where the ceiling check is skipped; see [Overcapture](/integration-guide/payment-suite/payments/manual-capture/overcapture.md). For `manual_multiple`, `amount_to_capture` is required on every capture call. ### What happens to the amount you did not capture This is the part that decides whether you lose the remainder, and `capture_method` decides it. **`manual`.** One capture, and the payment lands in a terminal state. Capture the full amount and the payment is `succeeded`. Capture less and the payment is `partially_captured`, `amount_capturable` is set to `0`, and the rest of the hold is not capturable through Hyperswitch again. There is no second capture call. What that changes is Hyperswitch's own bookkeeping: the remainder is no longer capturable here. It is not a void, and Hyperswitch does not send one for the untouched part. What the processor and issuer do with the remaining hold, whether a partial capture releases it right away or it sits until the authorization ages out, is the connector's behavior, not Hyperswitch's. Ask your connector if you need to know when the customer stops seeing the hold. **`manual_multiple`.** Each capture creates a capture record. After a capture that does not exhaust the hold, the payment is `partially_captured_and_capturable` and `amount_capturable` becomes the authorized amount minus everything already blocked by earlier captures. That remainder stays capturable, so you can call the capture endpoint again. When the captures add up to the authorized amount, the payment becomes `succeeded`. `amount_captured` tracks what you actually took, and it is the ceiling for refunds. A payment is refundable only in `succeeded` or `partially_captured`. A `manual_multiple` payment sitting in `partially_captured_and_capturable` is not refundable yet. See [Refunds](/integration-guide/payment-suite/refunds.md). ### Statuses you will see | Status | What it means for capture | | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | | `requires_capture` | Authorized. The full authorized amount is capturable. | | `succeeded` | Everything capturable has been captured. Terminal. | | `partially_captured` | Part captured, nothing left to capture. Terminal. Refundable up to `amount_captured`. | | `partially_captured_and_capturable` | Part captured, remainder still capturable. Not terminal. Not refundable until it becomes terminal. | | `processing` | A `manual_multiple` capture is in flight and no capture has been charged yet. The capture endpoint still accepts calls in this state. | | `partially_authorized_and_requires_capture` | The processor authorized less than you asked for. Capture against the smaller authorized amount. | | `cancelled` | Voided before any capture. | | `cancelled_post_capture` | Voided after a capture. A payment in this state cannot be refunded. | `processing` on a `manual_multiple` payment means a capture has been sent and none has been charged yet. Where it goes next depends on what the captures add up to: if the charged total reaches the authorized amount the payment is `succeeded`, and if a capture is charged while the total is still short it is `partially_captured_and_capturable`. `partially_captured_and_processing` is a different status, and it is not a capture status. It is produced only on the partial authorization path, when `enable_partial_authorization` is on, some amount has already been captured, and the attempt is still pending at the processor. No value of `capture_method` produces it. If you are seeing it, look at partial authorization, not at your capture calls. ### About `refund_uncaptured_amount` The capture request accepts a boolean `refund_uncaptured_amount`. It does nothing today. No code path in the payments backend reads it, so sending `true`, sending `false`, and omitting it all behave the same way, and there is no default to speak of. The field's own description in the API reference says it is not fully supported. We are working on it; the tracking issue is [juspay/hyperswitch#14274](https://github.com/juspay/hyperswitch/issues/14274). Until it does something, do not plan around it. What governs the remainder is `capture_method`, described above: choose `manual_multiple` at creation if you need the uncaptured part to stay capturable, and accept that with `manual` a partial capture ends the payment. ### Questions this page does not answer * Capturing more than you authorized, the `enable_overcapture` and `is_overcapture_enabled` fields, and which connectors accept it: [Overcapture](/integration-guide/payment-suite/payments/manual-capture/overcapture.md). * Refund eligibility, the refundable ceiling, and how many refunds one payment allows: [Refunds](/integration-guide/payment-suite/refunds.md). * Raising the authorized amount before capture: [Incremental Authorization](/integration-guide/payment-suite/payments/authorizations/incremental-authorization.md). * Holding an authorization open for longer: [Extended Authorization](/integration-guide/payment-suite/payments/authorizations/extended-authorization.md). * Whether a given connector supports single or multiple captures: the connector's page under Connectors and Integrations. Whether an authorization can lapse before you capture it, and what Hyperswitch shows when it does, is not answered here. The backend declares an `expired` status and a `payment_expired` webhook event, but at the commit this page was checked against, no code path sets either for an uncaptured authorization. Until that is resolved, treat authorization lifetime as a connector question and confirm the window with your connector. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.hyperswitch.io/integration-guide/payment-suite/payments/manual-capture.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.