Payments - Create and Confirm Intent

POST https://sandbox.hyperswitch.io/v2/payments

Try it

Example cURL

curl --request POST \
  --url https://sandbox.hyperswitch.io/v2/payments \
  --header 'Content-Type: application/json' \
  --header 'X-Profile-Id: <x-profile-id>' \
  --header 'api-key: <api-key>' \
  --data '
{
  "authentication_type": "no_three_ds",
  "payment_link_config": {
    "display_sdk_only": false,
    "enabled_saved_payment_method": false,
    "hide_card_nickname_field": false,
    "show_card_form_by_default": true
  },
  "enable_partial_authorization": false
}
'

Response examples

200 (success)

400 (example error responses will return appropriate error object)

Authorizations

  • api-key (header) — 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.

Headers

  • X-Profile-Id (header) — string — required Profile ID associated to the payment intent

Body (application/json)

Top-level request fields (high-level overview; child attributes are available for complex objects):

  • amount_details (object) — required

  • customer_id (string) — required The identifier for the customer Required string length: 32 - 64 Example: "12345_cus_01926c58bc6e77c09e809964e72af8c8"

  • payment_method_data (object) — required The payment method information provided for making a payment. Supported payment method objects include Card, CardRedirect, Wallet, PayLater, BankRedirect, BankDebit, BankTransfer, RealTimePayment, Crypto, Upi, Voucher, GiftCard, CardToken, OpenBanking, MobilePayment, NetworkToken, etc.

  • payment_method_type (enum) — required Indicates the type of payment method. Available options: card, card_redirect, pay_later, wallet, bank_redirect, bank_transfer, crypto, bank_debit, reward, real_time_payment, upi, voucher, gift_card, open_banking, mobile_payment, network_token

  • payment_method_subtype (enum) — required Indicates the subtype of payment method (e.g., google_pay, apple_pay). (Long list of options supported)

  • merchant_reference_id (string|null) Unique identifier for the payment to ensure idempotency. Required string length: 30 Example: "pay_mbabizu24mvu3mela5njyhpit4"

  • routing_algorithm_id (string|null) — The routing algorithm id to be used for the payment

  • capture_method (enum) — Specifies how the payment is captured. Options: automatic (default), manual, manual_multiple, scheduled, sequential_automatic

  • authentication_type (enum) — default: no_three_ds Options: three_ds, no_three_ds. Specifies cardholder authentication behavior.

  • billing (object) — billing details

  • shipping (object) — shipping details

  • customer_present (enum) — present or absent

  • description (string|null) — A description for the payment

  • return_url (string|null) — URL to redirect user after completion

  • setup_future_usage (enum) — off_session or on_session (defaults to on_session)

  • apply_mit_exemption (enum) — Apply or Skip

  • statement_descriptor (string|null) — For non-card charges; max 22 chars

  • order_details (object[]|null) — Array describing products; sum must equal overall amount

  • allowed_payment_method_types (enum[]|null) — Restrict shown payment methods (long list)

  • metadata (object) — Arbitrary key/value pairs

  • connector_metadata (object) — Additional connector-specific data (Apple Pay, Airwallex, Noon, etc.)

  • feature_metadata (object) — Additional data required by Hyperswitch

  • payment_link_enabled (enum) — Enable or Skip

  • payment_link_config (object)

  • request_incremental_authorization (enum) — true, false, default

  • session_expiry (integer|null) — client secret expiry in seconds (default from profile if omitted; example 900)

  • frm_metadata (object) — Fraud Risk Management related

  • request_external_three_ds_authentication (enum) — Enable or Skip

  • customer_acceptance (object) — Used during Payments-Confirm; contains type, time, and mode of acceptance

  • browser_info (object) — Browser info for 3DS 2.0

  • payment_method_id (string|null) — Associate an existing payment_method_id

  • force_3ds_challenge (boolean|null)

  • is_iframe_redirection_enabled (boolean|null)

  • merchant_connector_details (object)

  • return_raw_connector_response (boolean|null) — If true, includes stringified connector raw response

  • enable_partial_authorization (boolean|null) — default: false

  • webhook_url (string|null) — Webhook endpoint URL for status notifications

Response (200 application/json)

Payment created — key response fields:

  • id (string) — required; unique identifier for the payment (32 - 64 characters)

  • status (enum) — required; overall payment intent status (e.g., succeeded, failed, requires_customer_action, requires_capture, etc.)

  • amount (object) — required; various amount-related fields

  • customer_id (string) — required

  • processor_merchant_id (string) — required

  • created (date-time) — required

  • modified_at (date-time) — required

  • initiator (enum) — platform or connected

  • connector (string|null) — connector used for payment

  • payment_method_data (object) — payment method details

  • payment_method_type (enum)

  • payment_method_subtype (enum)

  • connector_transaction_id (string|null)

  • connector_reference_id (string|null)

  • merchant_connector_id (string|null)

  • browser_info (object)

  • error (object) — error details if applicable

  • shipping (object)

  • billing (object)

  • attempts (object[]|null) — list of payment attempts

  • connector_token_details (object) — token information usable by merchant

  • payment_method_id (string|null)

  • next_action (object) — contains URL for redirection flows

  • return_url (string|null)

  • authentication_type (enum)

  • authentication_type_applied (enum)

  • is_iframe_redirection_enabled (boolean|null)

  • merchant_reference_id (string|null)

  • raw_connector_response (string|null) — only returned when requested

  • feature_metadata (object)

  • metadata (object)

Note: Some fields (for example: shipping, billing, customer, payment_method) can be returned as expandable objects only when explicitly requested.

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

Related:

  • Payments - Get: https://api-reference.hyperswitch.io/v2/payments/payments--get

  • Payments - List: https://api-reference.hyperswitch.io/v2/payments/payments--list

(Responses are generated using AI and may contain mistakes.)

PreviousList payment methods for a MerchantNextPayment Method Session - Retrieve