POST
/
v2
/
payments
/
create-intent
Payments - Create Intent
curl --request POST \
  --url https://sandbox.hyperswitch.io/v2/payments/create-intent \
  --header 'Content-Type: application/json' \
  --header 'api-key: <api-key>' \
  --data '{
  "amount_details": {
    "currency": "USD",
    "order_amount": 6540
  }
}'
{
  "id": "<string>",
  "status": "succeeded",
  "amount_details": {
    "order_amount": 6540,
    "currency": "AED",
    "shipping_cost": 123,
    "order_tax_amount": 123,
    "external_tax_calculation": "skip",
    "surcharge_calculation": "skip",
    "surcharge_amount": 123,
    "tax_on_surcharge": 123
  },
  "client_secret": "cs_0195b34da95d75239c6a4bf514458896",
  "profile_id": "<string>",
  "merchant_reference_id": "pay_mbabizu24mvu3mela5njyhpit4",
  "routing_algorithm_id": "<string>",
  "capture_method": "automatic",
  "authentication_type": "three_ds",
  "billing": {
    "address": {
      "city": "New York",
      "country": "AF",
      "line1": "123, King Street",
      "line2": "Powelson Avenue",
      "line3": "Bridgewater",
      "zip": "08807",
      "state": "New York",
      "first_name": "John",
      "last_name": "Doe",
      "origin_zip": "08807"
    },
    "phone": {
      "number": "9123456789",
      "country_code": "+1"
    },
    "email": "<string>"
  },
  "shipping": {
    "address": {
      "city": "New York",
      "country": "AF",
      "line1": "123, King Street",
      "line2": "Powelson Avenue",
      "line3": "Bridgewater",
      "zip": "08807",
      "state": "New York",
      "first_name": "John",
      "last_name": "Doe",
      "origin_zip": "08807"
    },
    "phone": {
      "number": "9123456789",
      "country_code": "+1"
    },
    "email": "<string>"
  },
  "customer_id": "12345_cus_01926c58bc6e77c09e809964e72af8c8",
  "customer_present": "present",
  "description": "It's my first payment request",
  "return_url": "https://hyperswitch.io",
  "setup_future_usage": "off_session",
  "apply_mit_exemption": "Apply",
  "statement_descriptor": "Hyperswitch Router",
  "order_details": "[{\n        \"product_name\": \"Apple iPhone 16\",\n        \"quantity\": 1,\n        \"amount\" : 69000\n        \"product_img_link\" : \"https://dummy-img-link.com\"\n    }]",
  "allowed_payment_method_types": [
    "ach"
  ],
  "metadata": {},
  "connector_metadata": {
    "apple_pay": {
      "session_token_data": {
        "payment_processing_certificate": "<string>",
        "payment_processing_certificate_key": "<string>",
        "payment_processing_details_at": "Hyperswitch",
        "certificate": "<string>",
        "certificate_keys": "<string>",
        "merchant_identifier": "<string>",
        "display_name": "<string>",
        "initiative": "web",
        "initiative_context": "<string>",
        "merchant_business_country": "AF"
      }
    },
    "airwallex": {
      "payload": "<string>"
    },
    "noon": {
      "order_category": "<string>"
    },
    "braintree": {
      "merchant_account_id": "<string>",
      "merchant_config_currency": "<string>"
    },
    "adyen": {
      "testing": {
        "holder_name": "<string>"
      }
    }
  },
  "feature_metadata": {
    "redirect_response": {
      "param": "<string>",
      "json_payload": {}
    },
    "search_tags": [
      "<string>"
    ],
    "apple_pay_recurring_details": {
      "payment_description": "<string>",
      "regular_billing": {
        "label": "<string>",
        "recurring_payment_start_date": "2023-09-10T23:59:59Z",
        "recurring_payment_end_date": "2023-09-10T23:59:59Z",
        "recurring_payment_interval_unit": "year",
        "recurring_payment_interval_count": 123
      },
      "billing_agreement": "<string>",
      "management_url": "https://hyperswitch.io"
    },
    "revenue_recovery": {
      "total_retry_count": "1",
      "payment_connector_transmission": "ConnectorCallUnsuccessful",
      "billing_connector_id": "mca_1234567890",
      "active_attempt_payment_connector_id": "mca_1234567890",
      "billing_connector_payment_details": {
        "payment_processor_token": "<string>",
        "connector_customer_id": "<string>"
      },
      "payment_method_type": "card",
      "payment_method_subtype": "ach",
      "connector": "authipay",
      "billing_connector_payment_method_details": {
        "type": "card",
        "value": {
          "card_network": "Visa",
          "card_issuer": "JP MORGAN CHASE"
        }
      },
      "invoice_next_billing_time": "2023-11-07T05:31:56Z",
      "invoice_billing_started_at_time": "2023-11-07T05:31:56Z",
      "first_payment_attempt_pg_error_code": "card_declined",
      "first_payment_attempt_network_decline_code": "05",
      "first_payment_attempt_network_advice_code": "02"
    }
  },
  "payment_link_enabled": "Enable",
  "payment_link_config": {
    "theme": "#4E6ADD",
    "logo": "https://i.pinimg.com/736x/4d/83/5c/4d835ca8aafbbb15f84d07d926fda473.jpg",
    "seller_name": "hyperswitch",
    "sdk_layout": "accordion",
    "display_sdk_only": true,
    "enabled_saved_payment_method": true,
    "hide_card_nickname_field": true,
    "show_card_form_by_default": true,
    "transaction_details": [
      {
        "key": "Policy-Number",
        "value": "297472368473924",
        "ui_configuration": {
          "position": 5,
          "is_key_bold": true,
          "is_value_bold": true
        }
      }
    ],
    "background_image": {
      "url": "https://hyperswitch.io/favicon.ico",
      "position": "left",
      "size": {
        "Variants": "cover"
      }
    },
    "details_layout": "layout1",
    "payment_button_text": "<string>",
    "custom_message_for_card_terms": "<string>",
    "payment_button_colour": "<string>",
    "skip_status_screen": true,
    "payment_button_text_colour": "<string>",
    "background_colour": "<string>",
    "sdk_ui_rules": {},
    "payment_link_ui_rules": {},
    "enable_button_only_on_form_ready": true,
    "payment_form_header_text": "<string>",
    "payment_form_label_type": "above",
    "show_card_terms": "always",
    "is_setup_mandate_flow": true,
    "color_icon_card_cvc_error": "<string>"
  },
  "request_incremental_authorization": "true",
  "split_txns_enabled": "enable",
  "expires_on": "2023-11-07T05:31:56Z",
  "frm_metadata": {},
  "request_external_three_ds_authentication": "Enable",
  "payment_type": "normal"
}

Authorizations

​
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.

Body

application/json
​
amount_details
object
required
​
customer_id
string
required

The identifier for the customer

Required string length: 32 - 64
Example:

"12345_cus_01926c58bc6e77c09e809964e72af8c8"

​
merchant_reference_id
string | null

Unique identifier for the payment. This ensures idempotency for multiple payments that have been done by a single merchant.

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<string>

Specifies how the payment is captured.

  • automatic: Funds are captured immediately after successful authorization. This is the default behavior if the field is omitted.
  • manual: Funds are authorized but not captured. A separate request to the /payments/{payment_id}/capture endpoint is required to capture the funds.
Available options:
automatic,
manual,
manual_multiple,
scheduled,
sequential_automatic
​
authentication_type
enum<string>
default:no_three_ds

Specifies the type of cardholder authentication to be applied for a payment.

  • ThreeDs: Requests 3D Secure (3DS) authentication. If the card is enrolled, 3DS authentication will be activated, potentially shifting chargeback liability to the issuer.
  • NoThreeDs: Indicates that 3D Secure authentication should not be performed. The liability for chargebacks typically remains with the merchant. This is often the default if not specified.

Note: The actual authentication behavior can also be influenced by merchant configuration and specific connector defaults. Some connectors might still enforce 3DS or bypass it regardless of this parameter.

Available options:
three_ds,
no_three_ds
​
billing
object
​
shipping
object
​
customer_present
enum<string>

Set to present to indicate that the customer is in your checkout flow during this payment, and therefore is able to authenticate. This parameter should be absent when merchant's doing merchant initiated payments and customer is not present while doing the payment.

Available options:
present,
absent
​
description
string | null

A description for the payment

Example:

"It's my first payment request"

​
return_url
string | null

The URL to which you want the user to be redirected after the completion of the payment operation

Example:

"https://hyperswitch.io"

​
setup_future_usage
enum<string>

Specifies how the payment method can be used for future payments.

  • off_session: The payment method can be used for future payments when the customer is not present.
  • on_session: The payment method is intended for use only when the customer is present during checkout. If omitted, defaults to on_session.
Available options:
off_session,
on_session
​
apply_mit_exemption
enum<string>
Available options:
Apply,
Skip
​
statement_descriptor
string | null

For non-card charges, you can use this value as the complete description that appears on your customers’ statements. Must contain at least one letter, maximum 22 characters.

Maximum length: 22
Example:

"Hyperswitch Router"

​
order_details
object[] | null

Use this object to capture the details about the different products for which the payment is being made. The sum of amount across different products here should be equal to the overall payment amount

Example:

"[{\n \"product_name\": \"Apple iPhone 16\",\n \"quantity\": 1,\n \"amount\" : 69000\n \"product_img_link\" : \"https://dummy-img-link.com\"\n }]"

​
allowed_payment_method_types
enum<string>[] | null

Use this parameter to restrict the Payment Method Types to show for a given PaymentIntent

​
metadata
object | null

Metadata is useful for storing additional, unstructured information on an object.

​
connector_metadata
object

Some connectors like Apple Pay, Airwallex and Noon might require some additional information, find specific details in the child attributes below.

​
feature_metadata
object

additional data that might be required by hyperswitch

​
payment_link_enabled
enum<string>

Whether payment link is requested to be enabled or not for this transaction

Available options:
Enable,
Skip
​
payment_link_config
object
​
request_incremental_authorization
enum<string>
Available options:
true,
false,
default
​
session_expiry
integer | null

Will be used to expire client secret after certain amount of time to be supplied in seconds, if not sent it will be taken from profile config (900) for 15 mins

Required range: x >= 0
Example:

900

​
frm_metadata
object | null

Additional data related to some frm(Fraud Risk Management) connectors

​
request_external_three_ds_authentication
enum<string>

Whether 3ds authentication is requested or not

Available options:
Enable,
Skip
​
force_3ds_challenge
boolean | null

Indicates if 3ds challenge is forced

​
merchant_connector_details
object

Merchant connector details

Response

Payment created

​
id
string
required

Global Payment Id for the payment

​
status
enum<string>
required

Represents the overall status of a payment intent. The status transitions through various states depending on the payment method, confirmation, capture method, and any subsequent actions (like customer authentication or manual capture).

Available options:
succeeded,
failed,
cancelled,
cancelled_post_capture,
processing,
requires_customer_action,
requires_merchant_action,
requires_payment_method,
requires_confirmation,
requires_capture,
partially_captured,
partially_captured_and_capturable,
partially_authorized_and_requires_capture,
conflicted,
expired
​
amount_details
object
required
​
client_secret
string
required

It's a token used for client side verification.

Example:

"cs_0195b34da95d75239c6a4bf514458896"

​
profile_id
string
required

The identifier for the profile. This is inferred from the x-profile-id header

​
capture_method
enum<string>
required

Specifies how the payment is captured.

  • automatic: Funds are captured immediately after successful authorization. This is the default behavior if the field is omitted.
  • manual: Funds are authorized but not captured. A separate request to the /payments/{payment_id}/capture endpoint is required to capture the funds.
Available options:
automatic,
manual,
manual_multiple,
scheduled,
sequential_automatic
​
customer_id
string
required

The identifier for the customer

Required string length: 32 - 64
Example:

"12345_cus_01926c58bc6e77c09e809964e72af8c8"

​
customer_present
enum<string>
required

Set to present to indicate that the customer is in your checkout flow during this payment, and therefore is able to authenticate. This parameter should be absent when merchant's doing merchant initiated payments and customer is not present while doing the payment.

Available options:
present,
absent
​
setup_future_usage
enum<string>
required

Specifies how the payment method can be used for future payments.

  • off_session: The payment method can be used for future payments when the customer is not present.
  • on_session: The payment method is intended for use only when the customer is present during checkout. If omitted, defaults to on_session.
Available options:
off_session,
on_session
​
apply_mit_exemption
enum<string>
required
Available options:
Apply,
Skip
​
payment_link_enabled
enum<string>
required

Whether payment link is requested to be enabled or not for this transaction

Available options:
Enable,
Skip
​
request_incremental_authorization
enum<string>
required
Available options:
true,
false,
default
​
split_txns_enabled
enum<string>
default:skip
required
Available options:
enable,
skip
​
expires_on
string<date-time>
required

Will be used to expire client secret after certain amount of time to be supplied in seconds

​
request_external_three_ds_authentication
enum<string>
required

Whether 3ds authentication is requested or not

Available options:
Enable,
Skip
​
payment_type
enum<string>
required

The type of the payment that differentiates between normal and various types of mandate payments. Use 'setup_mandate' in case of zero auth flow.

Available options:
normal,
new_mandate,
setup_mandate,
recurring_mandate
​
merchant_reference_id
string | null

Unique identifier for the payment. This ensures idempotency for multiple payments that have been done by a single merchant.

Required string length: 30
Example:

"pay_mbabizu24mvu3mela5njyhpit4"

​
routing_algorithm_id
string | null

The routing algorithm id to be used for the payment

​
authentication_type
enum<string>

Specifies the type of cardholder authentication to be applied for a payment.

  • ThreeDs: Requests 3D Secure (3DS) authentication. If the card is enrolled, 3DS authentication will be activated, potentially shifting chargeback liability to the issuer.
  • NoThreeDs: Indicates that 3D Secure authentication should not be performed. The liability for chargebacks typically remains with the merchant. This is often the default if not specified.

Note: The actual authentication behavior can also be influenced by merchant configuration and specific connector defaults. Some connectors might still enforce 3DS or bypass it regardless of this parameter.

Available options:
three_ds,
no_three_ds
​
billing
object
​
shipping
object
​
description
string | null

A description for the payment

Example:

"It's my first payment request"

​
return_url
string | null

The URL to which you want the user to be redirected after the completion of the payment operation

Example:

"https://hyperswitch.io"

​
statement_descriptor
string | null

For non-card charges, you can use this value as the complete description that appears on your customers’ statements. Must contain at least one letter, maximum 22 characters.

Maximum length: 22
Example:

"Hyperswitch Router"

​
order_details
object[] | null

Use this object to capture the details about the different products for which the payment is being made. The sum of amount across different products here should be equal to the overall payment amount

Example:

"[{\n \"product_name\": \"Apple iPhone 16\",\n \"quantity\": 1,\n \"amount\" : 69000\n \"product_img_link\" : \"https://dummy-img-link.com\"\n }]"

​
allowed_payment_method_types
enum<string>[] | null

Use this parameter to restrict the Payment Method Types to show for a given PaymentIntent

​
metadata
object | null

Metadata is useful for storing additional, unstructured information on an object.

​
connector_metadata
object

Some connectors like Apple Pay, Airwallex and Noon might require some additional information, find specific details in the child attributes below.

​
feature_metadata
object

additional data that might be required by hyperswitch

​
payment_link_config
object
​
frm_metadata
object | null

Additional data related to some frm(Fraud Risk Management) connectors