Payments - Create Intent

Create a PaymentIntent for initiating a payment.

Endpoint

  • POST https://sandbox.hyperswitch.io/v2/payments/create-intent

  • Path: /v2/payments/create-intent

  • Method: POST

  • Content-Type: application/json

Authorizations

  • Header: api-key (string) — required Use the API key created under your merchant account from the HyperSwitch dashboard. Do not expose this key in client-side code.

Request example (cURL)

curl
curl --request POST \
  --url https://sandbox.hyperswitch.io/v2/payments/create-intent \
  --header 'Content-Type: application/json' \
  --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
}
'

Request body (application/json)

  • amount_details (object) — required

    • child attributes available (see details in API reference)

  • customer_id (string) — required

    • Identifier for the customer. Required length: 32–64.

    • Example: "12345_cus_01926c58bc6e77c09e809964e72af8c8"

  • merchant_reference_id (string | null) — unique identifier for idempotency. Required length: 30.

    • Example: "pay_mbabizu24mvu3mela5njyhpit4"

  • routing_algorithm_id (string | null)

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

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

  • billing (object)

  • shipping (object)

  • customer_present (enum) — present or absent

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

  • return_url (string | null) — example: "https://hyperswitch.io"

  • setup_future_usage (enum) — off_session or on_session

  • apply_mit_exemption (enum) — Apply or Skip

  • statement_descriptor (string | null) — max 22 chars. Example: "Hyperswitch Router"

  • order_details (object[] | null) — use to capture product details; amounts should sum to overall payment amount.

  • allowed_payment_method_types (enum[] | null) — use to restrict payment method types shown (long list of supported values)

  • metadata (object) — unstructured additional data

  • connector_metadata (object) — optional connector-specific data (e.g., apple_pay, airwallex, noon, braintree, adyen)

  • feature_metadata (object) — additional data that might be required by hyperswitch

  • payment_link_enabled (enum) — Enable or Skip

  • payment_link_config (object) — UI / payment link settings

  • request_incremental_authorization (enum) — true, false, or default

  • session_expiry (integer | null) — seconds to expire client secret (default from profile if omitted). Example: 900

  • frm_metadata (object) — fraud management connector data

  • request_external_three_ds_authentication (enum) — Enable or Skip

  • force_3ds_challenge (boolean | null)

  • merchant_connector_details (object)

  • enable_partial_authorization (boolean | null) — default: false

(Full request body child attributes and details available in the API reference links.)

Response

Success: 200 application/json — "Payment created"

Response fields (selected)

  • id (string) — Global Payment Id

  • status (enum) — overall status of the payment intent. Options include: succeeded, failed, cancelled, processing, requires_customer_action, requires_confirmation, requires_capture, partially_captured, expired, etc.

  • amount_details (object) — required (order_amount, currency, shipping_cost, order_tax_amount, amount_captured, etc.)

  • client_secret (string) — required. Token used for client-side verification. Example: "cs_0195b34da95d75239c6a4bf514458896"

  • profile_id (string) — inferred from x-profile-id header

  • capture_method (enum)

  • customer_id (string)

  • customer_present (enum)

  • setup_future_usage (enum)

  • apply_mit_exemption (enum)

  • payment_link_enabled (enum)

  • request_incremental_authorization (enum)

  • split_txns_enabled (enum)

  • expires_on (string, date-time)

  • request_external_three_ds_authentication (enum)

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

  • merchant_reference_id (string | null)

  • routing_algorithm_id (string | null)

  • authentication_type (enum)

  • billing (object)

  • shipping (object)

  • description (string | null)

  • return_url (string | null)

  • statement_descriptor (string | null)

  • order_details (object[] | null)

  • allowed_payment_method_types (enum[] | null)

  • metadata (object)

  • connector_metadata (object)

  • feature_metadata (object)

  • payment_link_config (object)

  • frm_metadata (object)

  • enable_partial_authorization (boolean | null)

Example response (truncated)

200 — Example JSON response (expand)

Errors

  • Common client errors will return 4xx responses. See the API reference for detailed error schemas and codes.

Additional links

  • Documentation overview: https://api-reference.hyperswitch.io/introduction

  • Locker API Reference: https://api-reference.hyperswitch.io/locker-api-reference/overview

  • Intelligent Router API Reference: https://api-reference.hyperswitch.io/intelligent-router-api-reference/overview

  • Suggest edits: https://github.com/juspay/hyperswitch/edit/main/api-reference/v2/payments/payments--create-intent.mdx

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

If you want, I can split the full request/response schemas into stepper steps or expand specific sections (e.g., amount_details, connector_metadata, payment_link_config) for inclusion in the page.

PreviousRouting - Retrieve Default For ProfileNextRouting - Rule Evaluate