Payments - Create

POST /payments

Create a payment.

Example (cURL)

Create a payment with minimal fields
curl --request POST \
  --url https://sandbox.hyperswitch.io/payments \
  --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
}
'

Response (200):

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.

Request body (application/json)

Below are the request body fields. Types, constraints, defaults and brief descriptions are included.

  • amount (integer) — required The primary amount for the payment, provided in the lowest denomination of the specified currency (e.g., 6540 for $65.40 USD). Required range: x >= 0.

  • currency (enum) — required Three-letter ISO 4217 currency code. Available options: AED, AFN, ALL, ... , USD, ... , ZWL.

  • order_tax_amount (integer | null) Total tax amount applicable to the order, in the lowest denomination of the currency. Example: 6540

  • amount_to_capture (integer | null) The amount to be captured from the user's payment method, in the lowest denomination. If not provided and capture_method is automatic, full payment amount will be captured. If capture_method is manual, this can be specified in the /capture call. Must be <= authorized amount. Example: 6540

  • shipping_cost (integer | null) Shipping cost for the payment. Required for tax calculation in some regions. Example: 6540

  • payment_id (string | null) Optional merchant-provided unique identifier for the payment (30 characters long). Ensures idempotency. If omitted, Hyperswitch generates a unique ID. Required length: 30. Example: "pay_mbabizu24mvu3mela5njyhpit4"

  • routing (object) Routing options: Single · object (Single, Priority, VolumeSplit) — show child attributes in API.

  • connector (enum[] | null) Manually select a connector. Examples: ["stripe", "adyen"]. Available options include many connectors (authipay, adyenplatform, stripe_test, stripe, paypal, etc.).

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

  • authentication_type (enum) — default: three_ds Type of cardholder authentication. Options: three_ds, no_three_ds. Note merchant/connector configuration may influence behavior.

  • billing (object) Billing object (show child attributes in API).

  • confirm (boolean | null) — default: false If true, Hyperswitch attempts to confirm and authorize the payment immediately after creation (if sufficient payment method details are included). If false/omitted, separate POST /payments/{payment_id}/confirm is needed. Example: true

  • customer (object) Passing this object creates a new customer or attaches an existing one to the payment. See child attributes.

  • customer_id (string | null) Identifier for the customer. Required length 1–64. Example: "cus_y3oqhf46pyzuxjbcn2giaqnb44"

  • off_session (boolean | null) Set true to indicate customer is not in checkout flow and unable to authenticate (e.g., charging saved card later). Mandatory when making recurring payment by passing mandate_id. Example: true

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

  • return_url (string | null) URL to redirect the customer to after completing payment/authentication. Max length 2048. Example: "https://hyperswitch.io"

  • setup_future_usage (enum) Specifies how payment method can be used for future payments. Options: off_session, on_session. Defaults to on_session if omitted.

  • payment_method_data (object) Payment method information. Types supported include Card, CardRedirect, Wallet, PayLater, BankRedirect, BankDebit, BankTransfer, RealTimePayment, Crypto, Upi, Voucher, GiftCard, CardToken, OpenBanking, MobilePayment, NetworkToken.

  • payment_method (enum) Indicates general type: 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_token (string | null) Reference to a stored payment method token. Example: "187282ab-40ef-47a9-9206-5099ba31e432"

  • shipping (object) Shipping object (show child attributes in API).

  • statement_descriptor_name (string | null) — deprecated For non-card charges the complete description on customers’ statements. At least one letter, max 22 characters. To be deprecated soon; use billing_descriptor.

  • statement_descriptor_suffix (string | null) — deprecated Provides information about card payment seen on statements. Concatenated with prefix/statement descriptor. To be deprecated soon; use billing_descriptor.

  • order_details (object[] | null) Capture line items for the order. Sum of amounts across products should equal overall payment amount. Example JSON provided in API.

  • mandate_data (object) Passing this object during payments creates a mandate. Server passes mandate_type sub-object.

  • customer_acceptance (object) Customer acceptance object passed during Payments-Confirm, enlisting type/time/mode of acceptance. Usually passed by SDK/client.

  • mandate_id (string | null) Unique identifier to link payment to a mandate. For recurring payments pass mandate_id instead of payment_method_data. Max length 64. Example: "mandate_iwer89rnjef349dni3"

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

  • payment_experience (enum) Type of payment experience. Options: redirect_to_url, invoke_sdk_client, display_qr_code, one_click, link_wallet, invoke_payment_app, display_wait_screen, collect_otp.

  • payment_method_type (enum) Sub-type of payment method (e.g., google_pay, apple_pay for wallets). Many options listed (ach, affirm, apple_pay, paypal, pix, sepa, upi_qr, venmo, etc.).

  • business_country (enum) Business country code (ISO 3166-1 alpha-2). Options include AF, AL, AM, ... , US.

  • business_label (string | null) Business label of the merchant for this payment. To be deprecated soon; pass profile_id instead. Example: "food"

  • merchant_connector_details (object) Merchant connector details used to make payments. Showchild attributes in API.

  • allowed_payment_method_types (enum[] | null) Restrict allowed payment method types for a given PaymentIntent. Options similar to payment_method_type list.

  • metadata (object) Up to 50 keys, key names up to 40 chars, values up to 500 chars. Useful for storing structured additional information.

  • connector_metadata (object) Additional connector-specific metadata required by some connectors (Apple Pay, Airwallex, Noon, etc.)

  • payment_link (boolean | null) — default: false Whether to generate a payment link for this payment (if applicable). Example: true

  • payment_link_config (object) Configure a custom payment link for this particular payment. (See child attributes.)

  • payment_link_config_id (string | null) Custom payment link config id set at business profile. Send only if business_specific_configs is configured.

  • profile_id (string | null) Business profile to be used for this payment. If not passed default business profile associated with merchant account is used. Mandatory if multiple business profiles set up.

  • surcharge_details (object) Details of surcharge applied on this payment, if applicable.

  • payment_type (enum) Type of payment differentiating normal and mandate payments. Use 'setup_mandate' for zero auth flow. Options: normal, new_mandate, setup_mandate, recurring_mandate.

  • request_incremental_authorization (boolean | null) Request incremental authorization (increase authorized amount on a confirmed payment before capture).

  • session_expiry (integer | null) Seconds to expire client_secret after certain amount of time. Example: 900 for 15 mins. Required range: x >= 0.

  • frm_metadata (object) Additional data related to some FRM (Fraud Risk Management) connectors.

  • request_external_three_ds_authentication (boolean | null) Whether to perform external authentication (if applicable). Example: true

  • three_ds_data (object) External 3DS authentication data used in payment flow.

  • recurring_details (object) Details required for recurring payment (child options shown in API).

  • split_payments (object) Fee information for Split Payments to be charged on the payment being collected (child options shown in API).

  • request_extended_authorization (boolean | null) — default: false Optional boolean to extend authorization period of this payment. capture_method must be manual or manual_multiple.

  • merchant_order_reference_id (string | null) Merchant unique identifier for this payment/order. Passed to connector if supported. Max length: 255. Example: "Custom_Order_id_123"

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

  • psd2_sca_exemption_type (enum) SCA Exemption types: low_value, transaction_risk_analysis.

  • ctp_service_details (object) Child attributes shown in API.

  • force_3ds_challenge (boolean | null) Indicates if 3DS challenge is forced.

  • threeds_method_comp_ind (enum) Indicates if 3DS method data was successfully completed or not. Options: Y, N, U.

  • is_iframe_redirection_enabled (boolean | null) Indicates if redirection should open in an iframe.

  • all_keys_required (boolean | null) If enabled, provides whole connector response.

  • payment_channel (enum) Describes the channel through which payment initiated. Available options: ecommerce.

  • tax_status (enum) Options: taxable, exempt.

  • discount_amount (integer | null) Total discount amount applied to the order/transaction. Example: 6540

  • shipping_amount_tax (integer) Unit struct representing minor unit in which core amount works.

  • duty_amount (integer) Unit struct representing minor unit in which core amount works.

  • order_date (string | null) Date the payer placed the order.

  • enable_partial_authorization (boolean | null) — default: false Allow partial authorization for this payment.

  • enable_overcapture (boolean | null) Indicates whether to enable overcapture for this payment. Example: true

  • is_stored_credential (boolean | null) Indicates whether this payment method is stored and previously used. Example: true

  • mit_category (enum) MIT categories: installment, unscheduled, recurring, resubmission.

  • billing_descriptor (object) Billing descriptor information to be sent to the payment gateway.

  • tokenization (enum) Type of tokenization to use. Options: skip_psp, tokenize_at_psp.

  • partner_merchant_identifier_details (object) Information identifying partner and merchant application initiating the request.

(For many fields above, child attributes / detailed sub-objects are available — see API reference for the full schema.)

Response (application/json)

200 — Payment created.

Top-level response fields include:

  • payment_id (string) — required Unique identifier for the payment. Required length: 30. Example: "pay_mbabizu24mvu3mela5njyhpit4"

  • merchant_id (string) — required Identifier for the merchant account (inferred from API key). Example: "merchant_1668273825"

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

  • amount (integer) — required Payment amount in the lowest denomination. Example: 6540

  • net_amount (integer) — required net_amount = amount + surcharge_details.surcharge_amount + surcharge_details.tax_amount + shipping_cost + order_tax_amount. If none of those exist, net_amount = amount. Example: 6540

  • amount_capturable (integer) — required Amount that can still be captured. Relevant when capture_method is manual. Required range: x >= 100. Example: 6540

  • processor_merchant_id (string) — required Identifier for the processor merchant account (connected merchant ID in platform-connected setups). Example: "merchant_1689512302"

  • currency (enum) — required Three-letter ISO 4217 currency code. (list of currencies as in request)

  • payment_method (enum) — required Type of payment method: card, wallet, bank_redirect, etc.

  • attempt_count (integer) — required Total number of attempts associated with this payment.

  • shipping_cost (integer | null) Example: 6540

  • amount_received (integer | null) Total amount captured for this payment. Example: 6540

  • initiator (enum) Indicates initiator context in platform-connected setups: platform, connected, or None.

  • connector (string | null) Name of the payment connector that processed/is processing this payment. Example: "stripe"

  • client_secret (string | null) Secret token unique to this payment intent for client-side apps. Example: "pay_U42c409qyHwOkWo3vK60_secret_el9ksDkiB8hi6j9N78yo"

  • created (string | null) Timestamp when intent was created. Example: "2022-09-10T10:11:12Z"

  • modified_at (string | null) Timestamp when intent was last modified. Example: "2022-09-10T10:11:12Z"

  • customer_id (string | null) — deprecated Deprecated in favor of customer.id. Example: "cus_y3oqhf46pyzuxjbcn2giaqnb44"

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

  • refunds (object[] | null) Array of refund objects associated with this payment.

  • disputes (object[] | null) List of disputes on this intent.

  • attempts (object[] | null) List of attempts on this intent.

  • captures (object[] | null) List of captures done on latest attempt.

  • mandate_id (string | null) Link to a mandate (for recurring/mandate payments). Example: "mandate_iwer89rnjef349dni3"

  • mandate_data (object) Mandate data (child attributes shown in API).

  • setup_future_usage (enum) off_session or on_session (see request).

  • off_session (boolean | null) True if customer not present in checkout for this payment (can only be used with confirm=true). Example: true

  • capture_method (enum) How payment was captured (automatic/manual/etc.)

  • payment_method_data (object) Payment method details (child attributes).

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

  • shipping (object) / billing (object) Shipping and billing objects (child attributes).

  • order_details (object[] | null) Product/quantity/amount info for connectors (e.g., Klarna).

  • email, name, phone (deprecated) Deprecated; use customer.email, customer.name, customer.phone.

  • return_url (string | null) URL to redirect after operation. Example: "https://hyperswitch.io"

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

  • statement_descriptor_name / statement_descriptor_suffix (string | null) Statement descriptor fields (see request).

  • next_action (object) Contains URL for redirection flow (child attributes shown in API).

  • cancellation_reason (string | null) If cancelled, textual reason (e.g., "requested_by_customer", "abandoned").

  • error_code (string | null) Connector-specific error code from last failed attempt. Example: "E0001"

  • error_message (string | null) Human-readable error message from last failed attempt. Example: "Failed while verifying the card"

  • payment_experience, payment_method_type, connector_label, business_country, business_label, 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, request_extended_authorization, capture_before, merchant_order_reference_id, order_tax_amount, connector_mandate_id, card_discovery, force_3ds_challenge, issuer_error_code, issuer_error_message, 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, etc.

(Full response schema contains many nested child attributes — consult the API reference for complete field definitions.)

Notes:

  • Many fields reference nested child attributes. See the full API schema for nested object structures.

  • Several fields are marked deprecated (statement descriptor fields, top-level customer fields like email/name/phone). Prefer new customer object fields (customer.id, customer.email, etc.) and billing_descriptor/profile_id where applicable.

If you want, I can convert specific repeated lists (for example the full currency list or connector list) into collapsible sections or tables for easier reading.

PreviousPayments - Get IntentNextMerchant Account - Delete