Payments - Incremental Authorization

POST /payments/{payment_id}/incremental_authorization

Description: Incrementally authorize an existing payment by increasing the total authorized amount.

Example request (cURL)

curl --request POST \
  --url https://sandbox.hyperswitch.io/payments/{payment_id}/incremental_authorization \
  --header 'Content-Type: application/json' \
  --header 'api-key: <api-key>' \
  --data '
{
  "amount": 6540,
  "reason": "<string>"
}
'

Authorizations (Headers)

  • api-key (string, header, 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)

  • amount (integer, required) The total amount including previously authorized amount and additional amount Example: 6540

  • reason (string | null) Reason for incremental authorization

Responses

200 — application/json

Payment authorized amount incremented.

Example response body (application/json)

Response fields (high-level)

The response contains a Payment object with many attributes. Key fields include (type and brief description):

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

  • merchant_id (string) — Identifier for the merchant account inferred from the API key.

  • status (enum) — Overall status of the payment intent (e.g., succeeded, requires_confirmation, requires_capture, etc.).

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

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

  • amount_capturable (integer) — Amount still capturable (relevant when capture_method is manual).

  • processor_merchant_id (string) — Processor merchant identifier.

  • currency (enum) — ISO 4217 currency code.

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

  • attempts, captures, refunds, disputes — Arrays containing respective objects.

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

  • payment_method_data, payment_token — Payment method details or token.

  • incremental_authorizations (object[]) — List of incremental authorizations applied to this payment.

  • incremental_authorization_allowed (boolean) — Whether incremental authorization is allowed for this payment.

  • connector, connector_transaction_id, connector_label — Connector-related values.

  • error_code, error_message, unified_code, unified_message — Error information when applicable.

  • capture_method (enum) — How the payment should be captured (automatic, manual, etc.).

  • created, modified_at, updated, expires_on — Timestamp fields.

(For the full list of fields and nested attributes, see the example response above.)

Notes

  • amount must represent the total authorized amount including prior authorizations and the additional amount you are requesting.

  • incremental_authorization_allowed must be true on the payment to perform incremental authorizations.

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

Suggest edits / Raise issue:

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

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

PreviousGsm - DeleteNextCustomers - Create