Payments - Confirm

Endpoint: POST /payments/{payment_id}/confirm

Overview: Confirm and (optionally) authorize a payment. If confirm: true and sufficient payment method details are provided, Hyperswitch will attempt to confirm and authorize immediately. Otherwise create the payment and call this endpoint later to confirm.

Example — cURL

curl --request POST \
  --url https://sandbox.hyperswitch.io/payments/{payment_id}/confirm \
  --header 'Content-Type: application/json' \
  --header 'api-key: <api-key>' \
  --data '
{
  "authentication_type": "three_ds",
  "confirm": false,
  "payment_link": false,
  "payment_link_config": {
    "display_sdk_only": false,
    "enabled_saved_payment_method": false,
    "hide_card_nickname_field": false,
    "show_card_form_by_default": true
  },
  "request_extended_authorization": false,
  "enable_partial_authorization": false
}
'

Response status codes: 200, 400

Example response (200)

Authorization

Header: api-key (string) — required

Use the API key created under your merchant account from the HyperSwitch dashboard. API key authenticates API requests from your merchant server only. Do not expose this key in client-side code.

Path parameters

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

Request body (application/json)

Common fields (high-level):

  • amount — integer (int64) | null Primary amount in the lowest currency denomination (e.g., 6540 = $65.40). Required for creating a payment. Range: x >= 0. Example: 6540

  • order_tax_amount — integer (int64) | null Total tax amount applicable to the order.

  • currency — enum (string) Three-letter ISO 4217 currency code (e.g., "USD"). Example values: AED, USD, EUR, etc.

  • amount_to_capture — integer (int64) | null Amount to capture. If omitted and capture_method is automatic, full payment amount will be captured.

  • shipping_cost — integer (int64) | null

  • payment_id — string | null Merchant-provided unique identifier (30 chars). If provided, ensures idempotency. Example: "pay_mbabizu24mvu3mela5njyhpit4"

  • routing — object (Single · Priority · VolumeSplit)

  • connector — array | null Manually select connector(s) for the payment (e.g., ["stripe", "adyen"]).

  • capture_method — enum Options: automatic, manual, manual_multiple, scheduled, sequential_automatic

  • authentication_type — enum (default: three_ds) Options: three_ds, no_three_ds

  • billing — object

  • confirm — boolean | null (default: false) If true, Hyperswitch attempts to confirm and authorize immediately after creation (if payment method details are present). If false or omitted, the payment may be created in a state requiring confirmation.

  • customer — object (to create or attach a customer)

  • customer_id — string | null

  • off_session — boolean | null Set true if customer is not present (required when making recurring payment with mandate_id).

  • description — string | null

  • return_url — string | null URL to redirect the customer after off-site flows (max length 2048).

  • setup_future_usage — enum Options: off_session, on_session

  • payment_method_data — object (Card · CardRedirect · Wallet · ...)

  • payment_method — enum e.g., card, wallet, pay_later, bank_redirect, crypto, upi, etc.

  • payment_token — string | null Reference to a tokenized payment method.

  • shipping — object

  • statement_descriptor_name — string | null (deprecated)

  • statement_descriptor_suffix — string | null (deprecated)

  • order_details — array | null Details about order items. Sum of amounts should equal overall payment amount.client_secret — string | nullmandate_data — object (to create a mandate during confirm)customer_acceptance — object (CustomerAcceptance metadata)mandate_id — string | nullbrowser_info — object (for 3DS 2.0)payment_experience — enum e.g., redirect_to_url, invoke_sdk_client, display_qr_code, one_click, link_wallet, etc.payment_method_type — enum Many options (ach, apple_pay, google_pay, paypal, etc.)merchant_connector_details — objectallowed_payment_method_types — array | nullretry_action — enum (manual_retry, requeue)metadata — object (up to 50 keys)connector_metadata — object (connector-specific extras)payment_link — boolean | null (default: false)payment_link_config — objectpayment_type — enum (normal, new_mandate, setup_mandate, recurring_mandate)request_incremental_authorization — boolean | nullsession_expiry — integer (int32) | null (seconds)frm_metadata — objectrequest_external_three_ds_authentication — boolean | nullthree_ds_data — objectrecurring_details — objectsplit_payments — objectrequest_extended_authorization — boolean | null (default: false) capture_method must be manual or manual_multiplemerchant_order_reference_id — string | nullskip_external_tax_calculation — boolean | nullpsd2_sca_exemption_type — enum (low_value, transaction_risk_analysis)ctp_service_details — objectforce_3ds_challenge — boolean | nullthreeds_method_comp_ind — enum (Y, N, U)is_iframe_redirection_enabled — boolean | nullall_keys_required — boolean | nullpayment_channel — enum (ecommerce)tax_status — enum (taxable, exempt)discount_amount — integer | nullshipping_amount_tax — integerduty_amount — integerorder_date — string | nullenable_partial_authorization — boolean | null (default: false)is_stored_credential — boolean | nullmit_category — enum (installment, unscheduled, recurring, resubmission)billing_descriptor — objecttokenization — enum (skip_psp, tokenize_at_psp)partner_merchant_identifier_details — object(See the response section below for fields returned by the API.)Response (200 — application/json)The response is the confirmed payment object. Key fields include (but are not limited to):payment_id (string) — requiredmerchant_id (string) — requiredstatus (enum) — required Possible values include: succeeded, failed, cancelled, processing, requires_customer_action, requires_payment_method, requires_confirmation, requires_capture, partially_captured, expired, conflicted, etc.amount (integer) — requirednet_amount (integer) — requiredamount_capturable (integer) — requiredprocessor_merchant_id (string) — requiredcurrency (enum) — requiredpayment_method (enum) — requiredattempt_count (integer) — requiredshipping_cost, amount_received, initiator, connector, client_secret, created, modified_at, customer_id, description, refunds, disputes, attempts, captures, mandate_id, mandate_data, setup_future_usage, off_session, capture_method, payment_method_data, payment_token, shipping, billing, order_details, return_url, authentication_type, statement descriptors, next_action, error_code, error_message, payment_experience, payment_method_type, connector_label, business_country, allowed_payment_method_types, manual_retry_allowed, connector_transaction_id, frm_message, metadata, connector_metadata, feature_metadata, reference_id, payment_link, profile_id, surcharge_details, merchant_decision, merchant_connector_id, incremental_authorization_allowed, external_authentication_details, expires_on, fingerprint, browser_info, payment_channel, payment_method_id, network_transaction_id, payment_method_status, updated, split_payments, extended_authorization_applied, capture_before, merchant_order_reference_id, order_tax_amount, card_discovery, force_3ds_challenge, is_iframe_redirection_enabled, whole_connector_response, enable_partial_authorization, enable_overcapture, network_details, is_stored_credential, mit_category, billing_descriptor, tokenization, partner_merchant_identifier_details, payment_method_tokenization_details, etc.Many of these fields are documented in the example response above.Large enums / listsSome fields (currency codes, connectors, payment_method_type, allowed_payment_method_types, business_country, etc.) have long enumerated lists. Expand for details:Notes / tipsconfirm: true triggers immediate confirmation/authorization when sufficient payment details are included. confirm: false (default) requires a subsequent confirm call to proceed.capture_method determines whether capture is automatic or requires a separate capture call.For recurring payments using an existing mandate, provide mandate_id and set off_session appropriately.client_secret is returned for client-side verification flows; handle it carefully.If you want this page converted into specific GitBook advanced blocks (for example: separate tabs for request languages, or stepper for an example flow), tell me which variants you need (cURL, Node, Python, Java) and I will rearrange the examples into tabs or steppers.

PreviousSubscription - CreateNextSubscription - Resume Subscription