Payments - Capture

POST /payments/{payment_id}/capture

Use this endpoint to capture an authorized payment (full or partial).

Authentication (required)

Header: api-key (string) Use the API key created under your merchant account from the HyperSwitch dashboard. API key is used to authenticate API requests from your merchant server only. Don't expose this key on a website or embed it in a mobile application.

Path parameters

  • payment_id (string, required) — The identifier for the payment.

Request body (application/json)

  • merchant_id (string | null) — The unique identifier for the merchant. Usually inferred from the API key.

  • amount_to_capture (integer | null) — Amount to capture in the lowest denomination of the currency. If omitted, the entire amount_capturable will be captured. Must be ≤ current amount_capturable. Example: 6540

  • refund_uncaptured_amount (boolean | null) — Decider to refund the uncaptured amount. (Behavior may vary by connector.)

  • statement_descriptor_suffix (string | null) — Dynamic suffix that appears on customer's card statement. Concatenated with your account's prefix. Combined length must respect connector limits (typically 22 chars).

  • statement_descriptor_prefix (string | null) — Optional prefix to override the default account prefix for the statement descriptor.

  • merchant_connector_details (object) — Merchant connector details used to make payments.

    • all_keys_required (boolean | null) — If true, returns stringified connector raw response body.

Example: Capture partial amount (cURL)

Responses

  • 200 application/json — Payment captured (returns the Payment object)

  • 400 — Bad request / validation error

Response: Payment object (summary)

The full response object is large. Key fields include:

  • payment_id (string) — Unique identifier for the payment.

  • merchant_id (string) — Merchant account identifier inferred from the API key.

  • status (enum) — Overall status of the payment intent. Examples: succeeded, requires_capture, partially_captured, etc.

  • amount (integer) — Payment amount (minor units).

  • net_amount (integer) — net_amount = amount + surcharge + tax + shipping + order_tax_amount.

  • amount_capturable (integer) — Amount still capturable (relevant for manual capture method).

  • currency (string) — ISO 4217 currency code (e.g., USD, AED).

  • payment_method (string) — Eg: card, wallet, bank_transfer, etc.

  • attempts (array) — List of attempts related to this payment.

  • captures (array) — List of captures done on the latest attempt.

  • customer (object) — Customer object (id, name, email, phone, ...).

  • payment_method_data (object) — Details of the payment method used.

  • metadata (object) — Custom metadata (up to 50 keys).

  • connector_metadata (object) — Connector-specific metadata (Apple Pay, Airwallex, etc.).

  • next_action (object) — Contains redirect URL for flows requiring customer action.

  • error_code, error_message — Last failed attempt error info (if present).

  • many other optional fields (mandate_id, capture_method, setup_future_usage, shipping, billing, etc.)

Full example response (click to expand)

Notes

  • If amount_to_capture is omitted, the endpoint captures the full amount_capturable.

  • refund_uncaptured_amount behavior may vary by connector and is not fully supported universally.

  • Keep your api-key secure; do not expose it in client-side code.

Suggest edits or raise issues on the original docs:

  • Edit: https://github.com/juspay/hyperswitch/edit/main/api-reference/v1/payments/payments--capture.mdx

  • Raise issue: https://github.com/juspay/hyperswitch/issues/new?title=Issue%20on%20docs&body=Path:%20/v1/payments/payments--capture

Original API reference: https://api-reference.hyperswitch.io/v1/payments/payments--capture

PreviousPayouts - CancelNextPayment Method - Delete