Payments - Update

Update an existing payment.

POST https://sandbox.hyperswitch.io/payments/{payment_id}

Request example (cURL):

curl
curl --request POST \
  --url https://sandbox.hyperswitch.io/payments/{payment_id} \
  --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
}
'

Authorization

Header: api-key (string, required) 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 payment.

Body (application/json)

Below are common fields accepted in the request body (types and brief descriptions). For many fields there are additional child attributes (not exhaustively expanded here).

  • amount (integer | null) — Primary amount in the lowest currency unit (e.g., 6540 = $65.40). Required range: x >= 0. Example: 6540.

  • order_tax_amount (integer | null) — Total tax amount in minor units. Example: 6540.

  • currency (enum) — ISO 4217 currency code (e.g., USD, EUR). Example options include AED, USD, EUR, etc.

  • amount_to_capture (integer | null) — Amount to capture from payment method in minor units. Example: 6540.

  • shipping_cost (integer | null) — Shipping cost in minor units. Example: 6540.

  • payment_id (string | null) — Optional merchant-provided unique identifier (30 characters). Example: "pay_mbabizu24mvu3mela5njyhpit4".

  • routing (object) — Routing configuration (Single, Priority, VolumeSplit).

  • connector (string[] | null) — Manually select connectors (e.g., ["stripe", "adyen"]).

  • capture_method (enum) — How the payment is captured: automatic, manual, manual_multiple, scheduled, sequential_automatic.

  • authentication_type (enum, default: three_ds) — three_ds or no_three_ds.

  • billing (object) — Billing information (address, phone, email).

  • confirm (boolean | null, default: false) — If true, attempts to confirm and authorize immediately. Example: true.

  • customer (object) — Create or attach a customer.

  • customer.customer_id (string | null) — Customer identifier (1–64 chars).

  • off_session (boolean | null) — Indicate customer not present (required when passing a mandate_id for recurring). Example: true.

  • description (string | null) — Arbitrary description. Example: "It's my first payment request".

  • return_url (string | null) — URL to redirect customer post-payment/authentication (max 2048). Example: "https://hyperswitch.io".

  • setup_future_usage (enum) — off_session or on_session.

  • payment_method_data (object) — Payment method details (Card, Wallet, BankRedirect, etc.).

  • payment_method (enum) — Type of payment method (e.g., card, wallet, bank_transfer).

  • payment_token (string | null) — Reference to a stored payment method. Example: "187282ab-40ef-47a9-9206-5099ba31e432".

  • shipping (object) — Shipping information.

  • statement_descriptor_name (string | null) — Deprecated; use billing_descriptor.

  • statement_descriptor_suffix (string | null) — Deprecated; use billing_descriptor.

  • order_details (object[] | null) — Details of products for the payment. Example: "[{ "product_name": "Apple iPhone 16", "quantity": 1, "amount" : 69000, "product_img_link" : "https://dummy-img-link.com" }]"

  • mandate_data (object) — Create a mandate (includes customer_acceptance and mandate_type).

  • customer_acceptance (object) — Type, time, and mode of acceptance; usually passed by SDK/client.

  • browser_info (object) — Browser information for 3DS 2.0.

  • payment_experience (enum) — redirect_to_url, invoke_sdk_client, display_qr_code, etc.

  • payment_method_type (enum) — Subtype of payment method (e.g., apple_pay, google_pay, ach).

  • merchant_connector_details (object) — Merchant connector details.

  • allowed_payment_method_types (string[] | null) — Restrict shown payment method subtypes.

  • retry_action (enum) — manual_retry or requeue.

  • metadata (object) — Up to 50 key/value pairs (key ≤ 40 chars, value ≤ 500 chars).

  • connector_metadata (object) — Connector-specific additional information (e.g., Apple Pay session data).

  • payment_link (boolean | null, default: false) — Generate a payment link if applicable.

  • payment_link_config (object) — Configure custom payment link for this payment.

  • surcharge_details (object) — Surcharge and tax amounts.

  • payment_type (enum) — normal, new_mandate, setup_mandate, recurring_mandate.

  • request_incremental_authorization (boolean | null) — Request an incremental authorization.

  • session_expiry (integer | null) — Client secret expiry in seconds (e.g., 900).

  • frm_metadata (object) — FRM-related additional data.

  • request_external_three_ds_authentication (boolean | null) — Whether to perform external 3DS authentication.

  • three_ds_data (object) — External 3DS authentication data.

  • recurring_details (object) — Recurring payment details.

  • split_payments (object) — Split payments fee information.

  • request_extended_authorization (boolean | null, default: false) — Extend authorization period (capture_method must be manual or manual_multiple).

  • merchant_order_reference_id (string | null) — Merchant order identifier (max 255 chars).

  • skip_external_tax_calculation (boolean | null) — Whether to calculate tax for this payment intent.

  • psd2_sca_exemption_type (enum) — low_value or transaction_risk_analysis.

  • force_3ds_challenge (boolean | null) — Force 3DS challenge.

  • threeds_method_comp_ind (enum) — Y, N, or U.

  • is_iframe_redirection_enabled (boolean | null) — Open redirection inside an iframe.

  • all_keys_required (boolean | null) — Provide whole connector response if enabled.

  • payment_channel (enum) — Describes channel; available option shown: ecommerce.

  • tax_status (enum) — taxable or exempt.

  • discount_amount (integer | null) — Discount amount in minor units.

  • shipping_amount_tax (integer) — Shipping tax amount.

  • duty_amount (integer) — Duty amount.

  • order_date (string | null) — Date order placed.

  • enable_partial_authorization (boolean | null, default: false) — Allow partial authorization.

  • enable_overcapture (boolean | null) — Enable overcapture.

  • is_stored_credential (boolean | null) — Indicate stored credential usage.

  • mit_category (enum) — installment, unscheduled, recurring, resubmission.

  • billing_descriptor (object) — Billing descriptor information.

  • tokenization (enum) — skip_psp or tokenize_at_psp.

  • partner_merchant_identifier_details (object) — Partner/merchant application info.

(There are many nested/connector-specific child attributes for several of the above fields; refer to connector-specific docs where applicable.)

Responses

  • 200 application/json — Payment updated. Response includes payment details such as:

    • payment_id (string, required)

    • merchant_id (string, required)

    • status (enum, default requires_confirmation)

    • amount, net_amount, amount_capturable (integers)

    • processor_merchant_id, currency, payment_method, attempt_count

    • shipping_cost, amount_received, initiator, connector

    • client_secret, created, modified_at

    • customer_id (deprecated), description

    • refunds, disputes, attempts, captures (arrays of objects)

    • mandate_id, mandate_data, setup_future_usage, off_session

    • capture_method, payment_method_data, payment_token

    • shipping, billing, order_details

    • email (deprecated), name (deprecated), phone (deprecated)

    • return_url, authentication_type, statement_descriptor_* (deprecated)

    • next_action, cancellation_reason, 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

    • authorization_count, incremental_authorizations, external_authentication_details

    • external_3ds_authentication_attempted, expires_on, fingerprint, browser_info

    • payment_channel, payment_method_id, network_transaction_id, payment_method_status

    • updated, split_payments, frm_metadata

    • extended_authorization_applied, extended_authorization_last_applied_at

    • capture_before, merchant_order_reference_id, order_tax_amount

    • connector_mandate_id, card_discovery, force_3ds_challenge, issuer_error_*

    • is_iframe_redirection_enabled, whole_connector_response

    • enable_partial_authorization, enable_overcapture, is_overcapture_enabled

    • network_details, is_stored_credential, mit_category, billing_descriptor

    • tokenization, partner_merchant_identifier_details, payment_method_tokenization_details

Example response (abbreviated). Expand to view the full example:

200 — Full JSON example

  • 400 — Bad request (validation or other client-side error).

Notes & hints

  • To confirm and authorize immediately, set confirm: true (requires sufficient payment method details).

  • For off-session recurring charges with a mandate, set off_session: true and provide mandate_id.

  • If using manual capture flows, set capture_method: "manual" and use /payments/{payment_id}/capture to capture.

Related

  • Payments — Create: https://api-reference.hyperswitch.io/v1/payments/payments--create

  • Payments — Confirm: https://api-reference.hyperswitch.io/v1/payments/payments--confirm

Suggest edits: https://github.com/juspay/hyperswitch/edit/main/api-reference/v1/payments/payments--update.mdx Raise an issue: https://github.com/juspay/hyperswitch/issues/new?title=Issue%20on%20docs&body=Path:%20/v1/payments/payments--update

PreviousCustomers - RetrieveNextCustomers - List