v1

latestOpenAPI 3.0.02026-07-26168846732.2 KB

Payments

Payments - Create

Creates a payment resource, which represents a customer's intent to pay. This endpoint is the starting point for various payment flows:

post/payments

Request body

amountinteger required

The primary amount for the payment, provided in the lowest denomination of the specified currency (e.g., 6540 for $65.40 USD). This field is mandatory for creating a payment.

order_tax_amountinteger nullable

Total tax amount applicable to the order, in the lowest denomination of the currency.

currency'AED' | 'AFN' | 'ALL' | 'AMD' | 'ANG' | 'AOA' | 'ARS' | 'AUD' | 'AWG' | 'AZN' | 'BAM' | 'BBD' | 'BDT' | 'BGN' | 'BHD' | 'BIF' | 'BMD' | 'BND' | 'BOB' | 'BRL' | 'BSD' | 'BTN' | 'BWP' | 'BYN' | 'BZD' | 'CAD' | 'CDF' | 'CHF' | 'CLF' | 'CLP' | 'CNY' | 'COP' | 'CRC' | 'CUC' | 'CUP' | 'CVE' | 'CZK' | 'DJF' | 'DKK' | 'DOP' | 'DZD' | 'EGP' | 'ERN' | 'ETB' | 'EUR' | 'FJD' | 'FKP' | 'GBP' | 'GEL' | 'GHS' | 'GIP' | 'GMD' | 'GNF' | 'GTQ' | 'GYD' | 'HKD' | 'HNL' | 'HRK' | 'HTG' | 'HUF' | 'IDR' | 'ILS' | 'INR' | 'IQD' | 'IRR' | 'ISK' | 'JMD' | 'JOD' | 'JPY' | 'KES' | 'KGS' | 'KHR' | 'KMF' | 'KPW' | 'KRW' | 'KWD' | 'KYD' | 'KZT' | 'LAK' | 'LBP' | 'LKR' | 'LRD' | 'LSL' | 'LYD' | 'MAD' | 'MDL' | 'MGA' | 'MKD' | 'MMK' | 'MNT' | 'MOP' | 'MRU' | 'MUR' | 'MVR' | 'MWK' | 'MXN' | 'MYR' | 'MZN' | 'NAD' | 'NGN' | 'NIO' | 'NOK' | 'NPR' | 'NZD' | 'OMR' | 'PAB' | 'PEN' | 'PGK' | 'PHP' | 'PKR' | 'PLN' | 'PYG' | 'QAR' | 'RON' | 'RSD' | 'RUB' | 'RWF' | 'SAR' | 'SBD' | 'SCR' | 'SDG' | 'SEK' | 'SGD' | 'SHP' | 'SLE' | 'SLL' | 'SOS' | 'SRD' | 'SSP' | 'STD' | 'STN' | 'SVC' | 'SYP' | 'SZL' | 'THB' | 'TJS' | 'TMT' | 'TND' | 'TOP' | 'TRY' | 'TTD' | 'TWD' | 'TZS' | 'UAH' | 'UGX' | 'USD' | 'UYU' | 'UZS' | 'VES' | 'VND' | 'VUV' | 'WST' | 'XAF' | 'XCD' | 'XOF' | 'XPF' | 'YER' | 'ZAR' | 'ZMW' | 'ZWL' required

The three-letter ISO 4217 currency code (e.g., "USD", "EUR") for the payment amount. This field is mandatory for creating a payment.

amount_to_captureinteger nullable

The amount to be captured from the user's payment method, in the lowest denomination. If not provided, and capture_method is automatic, the full payment amount will be captured. If capture_method is manual, this can be specified in the /capture call. Must be less than or equal to the authorized amount.

shipping_costinteger nullable

The shipping cost for the payment. This is required for tax calculation in some regions.

payment_idstring nullable

Optional. A merchant-provided unique identifier for the payment, contains 30 characters long (e.g., "pay_mbabizu24mvu3mela5njyhpit4"). If provided, it ensures idempotency for the payment creation request. If omitted, Hyperswitch generates a unique ID for the payment.

connectorConnector[] nullable

This allows to manually select a connector with which the payment can go through.

capture_method'automatic' | 'manual' | 'manual_multiple' | 'scheduled' | 'sequential_automatic'

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.

authentication_type'three_ds' | '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.

confirmboolean nullable

If set to true, Hyperswitch attempts to confirm and authorize the payment immediately after creation, provided sufficient payment method details are included. If false or omitted (default is false), the payment is created with a status such as requires_payment_method or requires_confirmation, and a separate POST /payments/{payment_id}/confirm call is necessary to proceed with authorization.

customer_idstring nullable

The identifier for the customer

off_sessionboolean nullable

Set to true to indicate that the customer is not in your checkout flow during this payment, and therefore is unable to authenticate. This parameter is intended for scenarios where you collect card details and charge them later. When making a recurring payment by passing a mandate_id, this parameter is mandatory

descriptionstring nullable

An arbitrary string attached to the payment. Often useful for displaying to users or for your own internal record-keeping.

return_urlstring nullable

The URL to redirect the customer to after they complete the payment process or authentication. This is crucial for flows that involve off-site redirection (e.g., 3DS, some bank redirects, wallet payments).

setup_future_usage'off_session' | 'on_session'

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.

Indicates the type of payment method. Eg: 'card', 'wallet', etc.

payment_tokenstring nullable

As Hyperswitch tokenises the sensitive details about the payments method, it provides the payment_token as a reference to a stored payment method, ensuring that the sensitive details are not exposed in any manner.

statement_descriptor_namestring nullable

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. To be deprecated soon, use billing_descriptor instead.

statement_descriptor_suffixstring nullable

Provides information about a card payment that customers see on their statements. Concatenated with the prefix (shortened descriptor) or statement descriptor that’s set on the account to form the complete statement descriptor. Maximum 22 characters for the concatenated descriptor. To be deprecated soon, use billing_descriptor instead.

mandate_idstring nullable

A unique identifier to link the payment to a mandate. To do Recurring payments after a mandate has been created, pass the mandate_id instead of payment_method_data

To indicate the type of payment experience that the customer would go through

Indicates the sub type of payment method. Eg: 'google_pay' & 'apple_pay' for wallets.

business_country'AF' | 'AX' | 'AL' | 'DZ' | 'AS' | 'AD' | 'AO' | 'AI' | 'AQ' | 'AG' | 'AR' | 'AM' | 'AW' | 'AU' | 'AT' | 'AZ' | 'BS' | 'BH' | 'BD' | 'BB' | 'BY' | 'BE' | 'BZ' | 'BJ' | 'BM' | 'BT' | 'BO' | 'BQ' | 'BA' | 'BW' | 'BV' | 'BR' | 'IO' | 'BN' | 'BG' | 'BF' | 'BI' | 'KH' | 'CM' | 'CA' | 'CV' | 'KY' | 'CF' | 'TD' | 'CL' | 'CN' | 'CX' | 'CC' | 'CO' | 'KM' | 'CG' | 'CD' | 'CK' | 'CR' | 'CI' | 'HR' | 'CU' | 'CW' | 'CY' | 'CZ' | 'DK' | 'DJ' | 'DM' | 'DO' | 'EC' | 'EG' | 'SV' | 'GQ' | 'ER' | 'EE' | 'ET' | 'FK' | 'FO' | 'FJ' | 'FI' | 'FR' | 'GF' | 'PF' | 'TF' | 'GA' | 'GM' | 'GE' | 'DE' | 'GH' | 'GI' | 'GR' | 'GL' | 'GD' | 'GP' | 'GU' | 'GT' | 'GG' | 'GN' | 'GW' | 'GY' | 'HT' | 'HM' | 'VA' | 'HN' | 'HK' | 'HU' | 'IS' | 'IN' | 'ID' | 'IR' | 'IQ' | 'IE' | 'IM' | 'IL' | 'IT' | 'JM' | 'JP' | 'JE' | 'JO' | 'KZ' | 'KE' | 'KI' | 'KP' | 'KR' | 'KW' | 'KG' | 'LA' | 'LV' | 'LB' | 'LS' | 'LR' | 'LY' | 'LI' | 'LT' | 'LU' | 'MO' | 'MK' | 'MG' | 'MW' | 'MY' | 'MV' | 'ML' | 'MT' | 'MH' | 'MQ' | 'MR' | 'MU' | 'YT' | 'MX' | 'FM' | 'MD' | 'MC' | 'MN' | 'ME' | 'MS' | 'MA' | 'MZ' | 'MM' | 'NA' | 'NR' | 'NP' | 'NL' | 'NC' | 'NZ' | 'NI' | 'NE' | 'NG' | 'NU' | 'NF' | 'MP' | 'NO' | 'OM' | 'PK' | 'PW' | 'PS' | 'PA' | 'PG' | 'PY' | 'PE' | 'PH' | 'PN' | 'PL' | 'PT' | 'PR' | 'QA' | 'RE' | 'RO' | 'RU' | 'RW' | 'BL' | 'SH' | 'KN' | 'LC' | 'MF' | 'PM' | 'VC' | 'WS' | 'SM' | 'ST' | 'SA' | 'SN' | 'RS' | 'SC' | 'SL' | 'SG' | 'SX' | 'SK' | 'SI' | 'SB' | 'SO' | 'ZA' | 'GS' | 'SS' | 'ES' | 'LK' | 'SD' | 'SR' | 'SJ' | 'SZ' | 'SE' | 'CH' | 'SY' | 'TW' | 'TJ' | 'TZ' | 'TH' | 'TL' | 'TG' | 'TK' | 'TO' | 'TT' | 'TN' | 'TR' | 'TM' | 'TC' | 'TV' | 'UG' | 'UA' | 'AE' | 'GB' | 'UM' | 'UY' | 'UZ' | 'VU' | 'VE' | 'VN' | 'VG' | 'VI' | 'WF' | 'EH' | 'YE' | 'ZM' | 'ZW' | 'US'

business_labelstring nullable

Business label of the merchant for this payment. To be deprecated soon. Pass the profile_id instead

allowed_payment_method_typesPaymentMethodType[] nullable

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

metadataobject nullable

You can specify up to 50 keys, with key names up to 40 characters long and values up to 500 characters long. Metadata is useful for storing additional, structured information on an object.

payment_linkboolean nullable

Whether to generate the payment link for this payment or not (if applicable)

payment_link_config_idstring nullable

Custom payment link config id set at business profile, send only if business_specific_configs is configured

profile_idstring nullable

The business profile to be used for this payment, if not passed the default business profile associated with the merchant account will be used. It is mandatory in case multiple business profiles have been set up.

payment_type'normal' | 'new_mandate' | 'setup_mandate' | 'recurring_mandate' | 'installment'

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

request_incremental_authorizationboolean nullable

Request an incremental authorization, i.e., increase the authorized amount on a confirmed payment before you capture it.

session_expiryinteger nullable

Will be used to expire client secret after certain amount of time to be supplied in seconds (900) for 15 mins

frm_metadataobject nullable

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

request_external_three_ds_authenticationboolean nullable

Whether to perform external authentication (if applicable)

request_extended_authorizationboolean nullable

Optional boolean value to extent authorization period of this payment

capture method must be manual or manual_multiple

merchant_order_reference_idstring nullable

Your unique identifier for this payment or order. This ID helps you reconcile payments on your system. If provided, it is passed to the connector if supported.

skip_external_tax_calculationboolean nullable

Whether to calculate tax for this payment intent

psd2_sca_exemption_type'low_value' | 'transaction_risk_analysis'

SCA Exemptions types available for authentication

force_3ds_challengeboolean nullable

Indicates if 3ds challenge is forced

threeds_method_comp_ind'Y' | 'N' | 'U'

Indicates if 3DS method data was successfully completed or not

is_iframe_redirection_enabledboolean nullable

Indicates if the redirection has to open in the iframe

all_keys_requiredboolean nullable

If enabled, provides whole connector response

tax_status'taxable' | 'exempt'

discount_amountinteger nullable

Total amount of the discount you have applied to the order or transaction.

shipping_amount_taxinteger

This Unit struct represents MinorUnit in which core amount works

duty_amountinteger

This Unit struct represents MinorUnit in which core amount works

order_datestring date-time nullable

Date the payer placed the order.

enable_partial_authorizationboolean nullable

Allow partial authorization for this payment

enable_overcaptureboolean nullable

Boolean indicating whether to enable overcapture for this payment

is_stored_credentialboolean nullable

Boolean flag indicating whether this payment method is stored and has been previously used for payments

mit_category'installment' | 'unscheduled' | 'recurring' | 'resubmission'

Specifies the category of a Merchant Initiated Transaction (MIT). In the case of MIT, mit_category tells what kind of MIT is being processed. In the case of CIT, it tells the future intended MIT type.

tokenization'skip_psp' | 'tokenize_at_psp'

The type of tokenization to use for the payment method

profile_acquirer_idstring nullable

Identification for the profile acquirer to be used for this payment.

external_surcharge_strategy'apply' | 'waive'

Strategy for applying external surcharge

Example request

{
  "order_tax_amount": 6540,
  "amount_to_capture": 6540,
  "shipping_cost": 6540,
  "payment_id": "pay_mbabizu24mvu3mela5njyhpit4",
  "connector": [
    "stripe",
    "adyen"
  ],
  "billing": {
    "address": {
      "city": "New York",
      "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"
    }
  },
  "confirm": true,
  "customer": {
    "id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
    "name": "John Doe",
    "email": "johntest@test.com",
    "phone": "9123456789",
    "phone_country_code": "+1",
    "document_details": {
      "document_number": "12345678911"
    }
  },
  "customer_id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
  "off_session": true,
  "description": "It's my first payment request",
  "return_url": "https://hyperswitch.io",
  "payment_method_data": {
    "card": {
      "card_number": "4242424242424242",
      "card_exp_month": "24",
      "card_exp_year": "24",
      "card_holder_name": "John Test",
      "card_cvc": "242",
      "card_issuer": "chase",
      "card_type": "CREDIT",
      "card_issuing_country": "INDIA",
      "card_issuing_country_code": "IN",
      "bank_code": "JP_AMEX",
      "nick_name": "John Test"
    },
    "billing": {
      "address": {
        "city": "New York",
        "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"
      }
    }
  },
  "payment_token": "187282ab-40ef-47a9-9206-5099ba31e432",
  "shipping": {
    "address": {
      "city": "New York",
      "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"
    }
  },
  "statement_descriptor_name": "Hyperswitch Router",
  "statement_descriptor_suffix": "Payment for shoes purchase",
  "order_details": [
    {
      "product_name": "shirt",
      "quantity": 1
    }
  ],
  "mandate_data": {
    "customer_acceptance": {
      "accepted_at": "2022-09-10T10:11:12Z",
      "online": {
        "ip_address": "123.32.25.123"
      }
    },
    "mandate_type": {
      "single_use": {
        "amount": 6540,
        "start_date": "2022-09-10T00:00:00Z",
        "end_date": "2023-09-10T23:59:59Z"
      }
    }
  },
  "customer_acceptance": {
    "accepted_at": "2022-09-10T10:11:12Z",
    "online": {
      "ip_address": "123.32.25.123"
    }
  },
  "mandate_id": "mandate_iwer89rnjef349dni3",
  "browser_info": {
    "accept_header": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8"
  },
  "business_label": "food",
  "connector_metadata": {
    "santander": {
      "boleto": {
        "discount_rules": {
          "tiers": [
            {
              "amount": "5.50",
              "end_date": "2027-12-31"
            }
          ]
        },
        "penalties": {
          "fixed_penalty": {
            "value": "2.00",
            "grace_period_days": 1
          },
          "interest": {
            "interest_percentage": "5.00",
            "iof_percentage": "32.45325"
          }
        },
        "collection_actions": {
          "legal_protest": {
            "days_after_due_date": 30
          },
          "auto_write_off_days": 60
        },
        "payment_constraints": {
          "details": {
            "min_value": "38.02",
            "max_value": "38.02"
          }
        },
        "beneficiary": {
          "name": "João da Silva",
          "document_number": "9615865832"
        }
      }
    }
  },
  "payment_link": true,
  "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"
    },
    "custom_message_for_payment_method_types": [
      {
        "payment_method_types": [
          {
            "message": {
              "display_mode": "custom",
              "value": "Sample message"
            },
            "payment_method_type": "credit"
          }
        ]
      }
    ],
    "show_merchant_name": true
  },
  "surcharge_details": {
    "surcharge_amount": 6540
  },
  "session_expiry": 900,
  "request_external_three_ds_authentication": true,
  "recurring_details": {
    "data": {
      "card_number": "4242424242424242",
      "card_exp_month": "24",
      "card_exp_year": "24",
      "card_holder_name": "John Test",
      "card_issuer": "chase",
      "card_type": "CREDIT",
      "card_issuing_country": "INDIA",
      "card_issuing_country_code": "IN",
      "bank_code": "JP_AMEX",
      "nick_name": "John Test"
    }
  },
  "split_payments": {
    "stripe_split_payment": {
      "application_fees": 6540,
      "on_behalf_of": "acct_1234567890"
    }
  },
  "merchant_order_reference_id": "Custom_Order_id_123",
  "discount_amount": 6540,
  "enable_overcapture": true,
  "is_stored_credential": true,
  "billing_descriptor": {
    "name": "The Online Retailer",
    "city": "San Francisco",
    "phone": "9123456789"
  },
  "partner_merchant_identifier_details": {
    "partner_details": {
      "version": "1.0.0"
    }
  }
}

Response

Payment created

payment_idstring required

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

merchant_idstring required

This is an identifier for the merchant account. This is inferred from the API key provided during the request

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

amountinteger required

The payment amount. Amount for the payment in lowest denomination of the currency. (i.e) in cents for USD denomination, in paisa for INR denomination etc.,

net_amountinteger required

The payment net amount. net_amount = amount + surcharge_details.surcharge_amount + surcharge_details.tax_amount + shipping_cost + order_tax_amount, If no surcharge_details, shipping_cost, order_tax_amount, net_amount = amount

shipping_costinteger nullable

The shipping cost for the payment.

amount_capturableinteger required

The amount (in minor units) that can still be captured for this payment. This is relevant when capture_method is manual. Once fully captured, or if capture_method is automatic and payment succeeded, this will be 0.

amount_receivedinteger nullable

The total amount (in minor units) that has been captured for this payment. For fauxpay sandbox connector, this might reflect the authorized amount if status is succeeded even if capture_method was manual.

processor_merchant_idstring required

The identifier for the processor merchant account. In platform-connected setups, this is the connected merchant ID. For standard merchants, this is same as merchant_id.

initiator'platform' | 'connected'

Represents the initiator context in platform-connected setups Used in payment/refund/dispute responses to indicate who initiated the operation None indicates a standard merchant flow / JWT flow / Admin flow or insufficient information

sdk_authorizationstring nullable

Token containing encoded information for sdk authorization.

connectorstring nullable

The name of the payment connector (e.g., 'stripe', 'adyen') that processed or is processing this payment.

client_secretstring nullable

A secret token unique to this payment intent. It is primarily used by client-side applications (e.g., Hyperswitch SDKs) to authenticate actions like confirming the payment or handling next actions. This secret should be handled carefully and not exposed publicly beyond its intended client-side use.

createdstring date-time nullable

Timestamp indicating when this payment intent was created, in ISO 8601 format.

modified_atstring date-time nullable

Timestamp indicating when this payment intent was last modified, in ISO 8601 format.

connector_customer_idstring nullable

A unique identifier for a customer provided by the connector.

The three-letter ISO 4217 currency code (e.g., "USD", "EUR") for the payment amount. This field is mandatory for creating a payment.

customer_idstring nullable

The identifier for the customer object. If not provided the customer ID will be autogenerated. This field will be deprecated soon. Please refer to customer.id

descriptionstring nullable

An arbitrary string providing a description for the payment, often useful for display or internal record-keeping.

mandate_idstring nullable

A unique identifier to link the payment to a mandate, can be used instead of payment_method_data, in case of setting up recurring payments

setup_future_usage'off_session' | 'on_session'

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.

off_sessionboolean nullable

capture_method'automatic' | 'manual' | 'manual_multiple' | 'scheduled' | 'sequential_automatic'

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.

Indicates the type of payment method. Eg: 'card', 'wallet', etc.

payment_tokenstring nullable

Provide a reference to a stored payment method

emailstring nullable

description: The customer's email address This field will be deprecated soon. Please refer to customer.email object

namestring nullable

description: The customer's name This field will be deprecated soon. Please refer to customer.name object

phonestring nullable

The customer's phone number This field will be deprecated soon. Please refer to customer.phone object

return_urlstring nullable

The URL to redirect after the completion of the operation

authentication_type'three_ds' | '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.

statement_descriptor_namestring nullable

statement_descriptor_suffixstring nullable

Provides information about a card payment that customers see on their statements. Concatenated with the prefix (shortened descriptor) or statement descriptor that’s set on the account to form the complete statement descriptor. Maximum 255 characters for the concatenated descriptor. To be deprecated soon, use billing_descriptor instead.

cancellation_reasonstring nullable

If the payment intent was cancelled, this field provides a textual reason for the cancellation (e.g., "requested_by_customer", "abandoned").

error_codestring nullable

The connector-specific error code from the last failed payment attempt associated with this payment intent.

error_messagestring nullable

A human-readable error message from the last failed payment attempt associated with this payment intent.

To indicate the type of payment experience that the customer would go through

Indicates the sub type of payment method. Eg: 'google_pay' & 'apple_pay' for wallets.

connector_labelstring nullable

A label identifying the specific merchant connector account (MCA) used for this payment. This often combines the connector name, business country, and a custom label (e.g., "stripe_US_primary").

business_labelstring nullable

The label identifying the specific business unit or profile under which this payment was processed by the merchant. To be deprecated soon. Pass the profile_id instead

business_sub_labelstring nullable

An optional sub-label for further categorization of the business unit or profile used for this payment. To be deprecated soon. Pass the profile_id instead

allowed_payment_method_typesPaymentMethodType[] nullable

Allowed Payment Method Types for a given PaymentIntent

manual_retry_allowedboolean nullable

If true the payment can be retried with same or different payment method which means the confirm call can be made again.

connector_transaction_idstring nullable

A unique identifier for a payment provided by the connector

metadataobject nullable

You can specify up to 50 keys, with key names up to 40 characters long and values up to 500 characters long. Metadata is useful for storing additional, structured information on an object.

reference_idstring nullable

reference(Identifier) to the payment at connector side

profile_idstring nullable

The business profile that is associated with this payment

attempt_countinteger required

Total number of attempts associated with this payment

merchant_decisionstring nullable

Denotes the action(approve or reject) taken by merchant in case of manual review. Manual review can occur when the transaction is marked as risky by the frm_processor, payment processor or when there is underpayment/over payment incase of crypto payment

merchant_connector_idstring nullable

Identifier of the connector ( merchant connector account ) which was chosen to make the payment

incremental_authorization_allowedboolean nullable

If true, incremental authorization can be performed on this payment, in case the funds authorized initially fall short.

authorization_countinteger nullable

Total number of authorizations happened in an incremental_authorization payment

external_3ds_authentication_attemptedboolean nullable

Flag indicating if external 3ds authentication is made or not

expires_onstring date-time nullable

Date Time for expiry of the payment

fingerprintstring nullable

Payment Fingerprint, to identify a particular card. It is a 20 character long alphanumeric code.

payment_method_idstring nullable

A unique identifier for the payment method used in this payment. If the payment method was saved or tokenized, this ID can be used to reference it for future transactions or recurring payments. Refer payment_method_tokenization_details for detailed view of payment method tokenization

network_transaction_idstring nullable

The network transaction ID is a unique identifier for the transaction as recognized by the payment network (e.g., Visa, Mastercard), this ID can be used to reference it for future transactions or recurring payments. Refer payment_method_tokenization_details for detailed view of payment method tokenization

network_transaction_link_idstring nullable

The Mastercard Transaction Link Identifier (TLID) for this payment. Returned on CITs that set up stored credentials. External-vault merchants should persist this and echo it back on subsequent MIT requests. Mandatory for Mastercard recurring/MIT (no static fallback).

Payment Method Status

updatedstring date-time nullable

Date time at which payment was updated

frm_metadataobject nullable

You can specify up to 50 keys, with key names up to 40 characters long and values up to 500 characters long. FRM Metadata is useful for storing additional, structured information on an object related to FRM.

extended_authorization_appliedboolean nullable

flag that indicates if extended authorization is applied on this payment or not

extended_authorization_last_applied_atstring date-time nullable

date and time at which extended authorization was last applied on this payment

request_extended_authorizationboolean nullable

Optional boolean value to extent authorization period of this payment

capture method must be manual or manual_multiple

capture_beforestring date-time nullable

date and time after which this payment cannot be captured

merchant_order_reference_idstring nullable

Merchant's identifier for the payment/invoice. This will be sent to the connector if the connector provides support to accept multiple reference ids. In case the connector supports only one reference id, Hyperswitch's Payment ID will be sent as reference.

order_tax_amountinteger

This Unit struct represents MinorUnit in which core amount works

connector_mandate_idstring nullable

Connector Identifier for the payment method

card_discovery'manual' | 'saved_card' | 'click_to_pay'

Indicates the method by which a card is discovered during a payment

force_3ds_challengeboolean nullable

Indicates if 3ds challenge is forced

force_3ds_challenge_triggerboolean nullable

Indicates if 3ds challenge is triggered

issuer_error_codestring nullable

Error code received from the issuer in case of failed payments

issuer_error_messagestring nullable

Error message received from the issuer in case of failed payments

is_iframe_redirection_enabledboolean nullable

Indicates if the redirection has to open in the iframe

whole_connector_responsestring nullable

Contains whole connector response

enable_partial_authorizationboolean nullable

Allow partial authorization for this payment

enable_overcaptureboolean nullable

Bool indicating if overcapture must be requested for this payment

is_overcapture_enabledboolean nullable

Boolean indicating whether overcapture is effectively enabled for this payment

is_stored_credentialboolean nullable

Boolean flag indicating whether this payment method is stored and has been previously used for payments

mit_category'installment' | 'unscheduled' | 'recurring' | 'resubmission'

tokenization'skip_psp' | 'tokenize_at_psp'

The type of tokenization to use for the payment method

sender_payment_instrument_idstring nullable

A connector-specific identifier representing the stored payment instrument

Example response

{
  "payment_id": "pay_mbabizu24mvu3mela5njyhpit4",
  "merchant_id": "merchant_1668273825",
  "amount": 6540,
  "net_amount": 6540,
  "shipping_cost": 6540,
  "amount_capturable": 6540,
  "amount_received": 6540,
  "processor_merchant_id": "merchant_1689512302",
  "sdk_authorization": "cHJvZmlsZV9pZD1wcm9mXzEyMyxwdWJsaXNoYWJsZV9rZXk9cGtfbGl2ZV8xMjM=",
  "connector": "stripe",
  "client_secret": "pay_U42c409qyHwOkWo3vK60_secret_el9ksDkiB8hi6j9N78yo",
  "created": "2022-09-10T10:11:12Z",
  "modified_at": "2022-09-10T10:11:12Z",
  "connector_customer_id": "cus_Rnm2pDKGyQi506",
  "customer_id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
  "description": "It's my first payment request",
  "refunds": [
    {
      "amount": 6540,
      "connector": "stripe",
      "split_refunds": {
        "adyen_split_refund": {
          "split_items": [
            {
              "amount": 6540
            }
          ]
        }
      }
    }
  ],
  "attempts": [
    {
      "amount": 6540,
      "order_tax_amount": 6540,
      "created_at": "2022-09-10T10:11:12Z",
      "modified_at": "2022-09-10T10:11:12Z",
      "reference_id": "993672945374576J"
    }
  ],
  "captures": [
    {
      "amount": 6540
    }
  ],
  "mandate_id": "mandate_iwer89rnjef349dni3",
  "mandate_data": {
    "customer_acceptance": {
      "accepted_at": "2022-09-10T10:11:12Z",
      "online": {
        "ip_address": "123.32.25.123"
      }
    },
    "mandate_type": {
      "single_use": {
        "amount": 6540,
        "start_date": "2022-09-10T00:00:00Z",
        "end_date": "2023-09-10T23:59:59Z"
      }
    }
  },
  "off_session": true,
  "payment_method_data": {
    "billing": {
      "address": {
        "city": "New York",
        "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"
      }
    }
  },
  "payment_token": "187282ab-40ef-47a9-9206-5099ba31e432",
  "shipping": {
    "address": {
      "city": "New York",
      "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"
    }
  },
  "billing": {
    "address": {
      "city": "New York",
      "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"
    }
  },
  "order_details": [
    {
      "product_name": "shirt",
      "quantity": 1
    }
  ],
  "email": "johntest@test.com",
  "name": "John Test",
  "phone": "9123456789",
  "return_url": "https://hyperswitch.io",
  "statement_descriptor_name": "Hyperswitch Router",
  "statement_descriptor_suffix": "Payment for shoes purchase",
  "next_action": {
    "redirect_to_url": "https://example.com/redirect"
  },
  "error_code": "E0001",
  "error_message": "Failed while verifying the card",
  "connector_label": "stripe_US_food",
  "connector_transaction_id": "993672945374576J",
  "connector_metadata": {
    "santander": {
      "boleto": {
        "discount_rules": {
          "tiers": [
            {
              "amount": "5.50",
              "end_date": "2027-12-31"
            }
          ]
        },
        "penalties": {
          "fixed_penalty": {
            "value": "2.00",
            "grace_period_days": 1
          },
          "interest": {
            "interest_percentage": "5.00",
            "iof_percentage": "32.45325"
          }
        },
        "collection_actions": {
          "legal_protest": {
            "days_after_due_date": 30
          },
          "auto_write_off_days": 60
        },
        "payment_constraints": {
          "details": {
            "min_value": "38.02",
            "max_value": "38.02"
          }
        },
        "beneficiary": {
          "name": "João da Silva",
          "document_number": "9615865832"
        }
      }
    }
  },
  "feature_metadata": {
    "apple_pay_recurring_details": {
      "regular_billing": {
        "recurring_payment_start_date": "2023-09-10T23:59:59Z",
        "recurring_payment_end_date": "2023-09-10T23:59:59Z"
      },
      "management_url": "https://hyperswitch.io"
    },
    "pix_additional_details": {
      "scheduled": {
        "date": "2026-07-08",
        "validity_after_expiration": 10
      }
    },
    "boleto_additional_details": {
      "due_date": "2026-12-31",
      "covenant_code": "3568253",
      "discount_rules": {
        "tiers": [
          {
            "amount": "5.50",
            "end_date": "2027-12-31"
          }
        ]
      },
      "penalties": {
        "fixed_penalty": {
          "value": "2.00",
          "grace_period_days": 1
        },
        "interest": {
          "interest_percentage": "5.00",
          "iof_percentage": "32.45325"
        }
      },
      "collection_actions": {
        "legal_protest": {
          "days_after_due_date": 30
        },
        "auto_write_off_days": 60
      },
      "payment_constraints": {
        "details": {
          "min_value": "38.02",
          "max_value": "38.02"
        }
      },
      "beneficiary": {
        "name": "João da Silva",
        "document_number": "9615865832"
      }
    },
    "pix_automatico_additional_details": {
      "time": 3600,
      "retry_policy": true,
      "mandate_details": {
        "fixed_recurring_amount": 6540,
        "min_recurring_amount": 6540,
        "start_date": "2026-12-31",
        "end_date": "2026-12-31"
      }
    },
    "finix_additional_details": {
      "fraud_session_id": "1234567890abcdef"
    }
  },
  "reference_id": "993672945374576J",
  "surcharge_details": {
    "surcharge_amount": 6540
  },
  "incremental_authorizations": [
    {
      "amount": 6540
    }
  ],
  "expires_on": "2022-09-10T10:11:12Z",
  "browser_info": {
    "accept_header": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8"
  },
  "updated": "2022-09-10T10:11:12Z",
  "split_payments": {
    "stripe_split_payment": {
      "application_fees": 6540,
      "on_behalf_of": "acct_1234567890"
    }
  },
  "extended_authorization_last_applied_at": "2022-09-10T10:11:12Z",
  "merchant_order_reference_id": "Custom_Order_id_123",
  "is_stored_credential": true,
  "billing_descriptor": {
    "name": "The Online Retailer",
    "city": "San Francisco",
    "phone": "9123456789"
  },
  "partner_merchant_identifier_details": {
    "partner_details": {
      "version": "1.0.0"
    }
  }
}