PaySwitch
PaySwitch API Reference

Payments

Server

Create and manage payments. Optional metadata on the payment stores per-transaction key/value pairs—see /metadata.


Payments - Create

POST
https://paysw-wiki.lab.next-on.pro/dev-router
/payments
api-key (header)

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

Optional metadata stores per-payment key/value pairs. See Metadata.

Payments - Create › Request Body

amount
​integer · int64 · min: 0 · 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.

currency
​Currency · enum · required

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

Enum values:
AED
AFN
ALL
AMD
ANG
AOA
ARS
AUD
order_tax_amount
​integer | null · int64

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

Example: 6540
amount_to_capture
​integer | null · int64

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.

Example: 6540
shipping_cost
​integer | null · int64

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

Example: 6540
payment_id
​string | null · minLength: 30 · maxLength: 30

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.

Example: pay_mbabizu24mvu3mela5njyhpit4
​
connector
​array | null

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

Enum values:
flexifai
fiftyfourpay
honeycoin
k218pay
bitex
hypergate
maguapay
payadmit
Example: ["stripe","adyen"]
capture_method
​string · enum

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.
Enum values:
automatic
manual
manual_multiple
scheduled
sequential_automatic
authentication_type
​string · enum

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.

Enum values:
three_ds
no_three_ds
Default: three_ds
​object
confirm
​boolean | null

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.

Example: true
Default: false
​object

Passing this object creates a new customer or attaches an existing customer to the payment

customer_id
​string | null · minLength: 1 · maxLength: 64

The identifier for the customer

Example: cus_y3oqhf46pyzuxjbcn2giaqnb44
​object

Merchant-provided customer statistics for advanced routing. All fields are optional.

off_session
​boolean | null

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

Example: true
description
​string | null

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

Example: It's my first payment request
return_url
​string | null · maxLength: 2048

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

Example: https://hyperswitch.io
setup_future_usage
​string · enum

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.
Enum values:
off_session
on_session
​object

The payment method information provided for making a payment

payment_method
​string · enum

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

Enum values:
card
card_redirect
pay_later
wallet
bank_redirect
bank_transfer
crypto
bank_debit
payment_token
​string | null

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.

Example: 187282ab-40ef-47a9-9206-5099ba31e432
​object
​array | 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: [{ "product_name": "Apple iPhone 16", "quantity": 1, "amount" : 69000 "product_img_link" : "https://dummy-img-link.com" }]
​object

Passing this object during payments creates a mandate. The mandate_type sub object is passed by the server.

​object

This "CustomerAcceptance" object is passed during Payments-Confirm request, it enlists the type, time, and mode of acceptance properties related to an acceptance done by the customer. The customer_acceptance sub object is usually passed by the SDK or client.

mandate_id
​string | null · maxLength: 64

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

Example: mandate_iwer89rnjef349dni3
​object

Browser information to be used for 3DS 2.0

payment_experience
​string · enum

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

Enum values:
redirect_to_url
invoke_sdk_client
display_qr_code
one_click
link_wallet
invoke_payment_app
display_wait_screen
collect_otp
payment_method_type
​string · enum

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

Enum values:
ach
affirm
afterpay_clearpay
alfamart
ali_pay
ali_pay_hk
alma
amazon_pay
business_country
​string · enum
Enum values:
AF
AX
AL
DZ
AS
AD
AO
AI
business_label
​string | null

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

Example: food
​object

Merchant connector details used to make payments.

allowed_payment_method_types
​array | null

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

Enum values:
ach
affirm
afterpay_clearpay
alfamart
ali_pay
ali_pay_hk
alma
amazon_pay
metadata
​object | null

Merchant-defined string key/value pairs. Limits: up to 50 keys; key names up to 40 characters; values up to 500 characters. PaySwitch does not interpret these keys—use them for your own logic (e.g. KYC status, trust tier, internal user id). Full guide: /metadata. Do not store secrets, card numbers, or passwords in metadata.

​object

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

payment_link
​boolean | null

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

Example: true
Default: false
​object

Configure a custom payment link for the particular payment

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

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.

​object

Details of surcharge applied on this payment, if applicable

payment_type
​string · enum

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

Enum values:
normal
new_mandate
setup_mandate
recurring_mandate
installment
request_incremental_authorization
​boolean | null

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

session_expiry
​integer | null · int32 · min: 0

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

Example: 900
frm_metadata
​object | null

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

Represents external 3DS authentication data used in the payment flow.

​

Details required for recurring payment

​

Fee information for Split Payments to be charged on the payment being collected

request_extended_authorization
​boolean | null

Optional boolean value to extent authorization period of this payment

capture method must be manual or manual_multiple

Default: false
merchant_order_reference_id
​string | null · maxLength: 255

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.

Example: Custom_Order_id_123
skip_external_tax_calculation
​boolean | null

Whether to calculate tax for this payment intent

psd2_sca_exemption_type
​string · enum

SCA Exemptions types available for authentication

Enum values:
low_value
transaction_risk_analysis
​object
force_3ds_challenge
​boolean | null

Indicates if 3ds challenge is forced

threeds_method_comp_ind
​string · enum

Indicates if 3DS method data was successfully completed or not

Enum values:
Y
N
U
is_iframe_redirection_enabled
​boolean | null

Indicates if the redirection has to open in the iframe

all_keys_required
​boolean | null

If enabled, provides whole connector response

​

Describes the channel through which the payment was initiated.

tax_status
​string · enum
Enum values:
taxable
exempt
discount_amount
​integer | null · int64

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

Example: 6540
shipping_amount_tax
​integer · int64

This Unit struct represents MinorUnit in which core amount works

duty_amount
​integer · int64

This Unit struct represents MinorUnit in which core amount works

order_date
​string | null · date-time

Date the payer placed the order.

enable_partial_authorization
​boolean | null

Allow partial authorization for this payment

Default: false
enable_overcapture
​boolean | null

Boolean indicating whether to enable overcapture for this payment

Example: true
is_stored_credential
​boolean | null

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

Example: true
mit_category
​string · enum

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.

Enum values:
installment
unscheduled
recurring
resubmission
​object

Billing Descriptor information to be sent to the payment gateway

tokenization
​string · enum

The type of tokenization to use for the payment method

Enum values:
skip_psp
tokenize_at_psp
​object

Information identifying partner and merchant application initiating the request

​array | null

Installment payment options grouped by payment method. When provided, the payment is treated as an installment payment.

​object

Installment selection sent by the customer during payment confirmation.

Payments - Create › Responses

Payment created

payment_id
​string · minLength: 30 · maxLength: 30 · required

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

Example: pay_mbabizu24mvu3mela5njyhpit4
merchant_id
​string · maxLength: 255 · required

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

Example: merchant_1668273825
status
​string · enum · 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).

Enum values:
succeeded
failed
cancelled
cancelled_post_capture
processing
requires_customer_action
requires_merchant_action
requires_payment_method
Default: requires_confirmation
amount
​integer · int64 · 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.,

Example: 6540
net_amount
​integer · int64 · 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

Example: 6540
amount_capturable
​integer · int64 · min: 100 · 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.

Example: 6540
processor_merchant_id
​string · maxLength: 255 · 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.

Example: merchant_1689512302
currency
​Currency · enum · required

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

Enum values:
AED
AFN
ALL
AMD
ANG
AOA
ARS
AUD
payment_method
​PaymentMethod · enum · required

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

Enum values:
card
card_redirect
pay_later
wallet
bank_redirect
bank_transfer
crypto
bank_debit
attempt_count
​integer · int32 · required

Total number of attempts associated with this payment

shipping_cost
​integer | null · int64

The shipping cost for the payment.

Example: 6540
amount_received
​integer | null · int64

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.

Example: 6540
initiator
​string · enum

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

Enum values:
platform
connected
sdk_authorization
​string | null

Token containing encoded information for sdk authorization.

Example: cHJvZmlsZV9pZD1wcm9mXzEyMyxwdWJsaXNoYWJsZV9rZXk9cGtfbGl2ZV8xMjM=
connector
​string | null

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

Example: stripe
​object

Additional metadata for payment intent state containing refunded and disputed amounts

client_secret
​string | null

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.

Example: pay_U42c409qyHwOkWo3vK60_secret_el9ksDkiB8hi6j9N78yo
created
​string | null · date-time

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

Example: 2022-09-10T10:11:12Z
modified_at
​string | null · date-time

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

Example: 2022-09-10T10:11:12Z
description
​string | null

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

Example: It's my first payment request
​array | null

An array of refund objects associated with this payment. Empty or null if no refunds have been processed.

​array | null

List of disputes that happened on this intent

​array | null

List of attempts that happened on this intent

​array | null

List of captures done on latest attempt

mandate_id
​string | null · maxLength: 255

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

Example: mandate_iwer89rnjef349dni3
​object

Passing this object during payments creates a mandate. The mandate_type sub object is passed by the server.

setup_future_usage
​string · enum

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.
Enum values:
off_session
on_session
off_session
​boolean | null

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. This parameter can only be used with confirm=true.

Example: true
capture_method
​string · enum

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.
Enum values:
automatic
manual
manual_multiple
scheduled
sequential_automatic
​object
payment_token
​string | null

Provide a reference to a stored payment method

Example: 187282ab-40ef-47a9-9206-5099ba31e432
​object
​object
​array | null

Information about the product , quantity and amount for connectors. (e.g. Klarna)

Example: [{ "product_name": "gillete creme", "quantity": 15, "amount" : 900 }]
return_url
​string | null

The URL to redirect after the completion of the operation

Example: https://hyperswitch.io
authentication_type
​string · enum

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.

Enum values:
three_ds
no_three_ds
Default: three_ds
statement_descriptor_name
​string | null · maxLength: 255

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.

Example: Hyperswitch Router
statement_descriptor_suffix
​string | null · maxLength: 255

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.

Example: Payment for shoes purchase
​
cancellation_reason
​string | null

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

error_code
​string | null

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

Example: E0001
error_message
​string | null

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

Example: Failed while verifying the card
​object

Complete error details for V1 PaymentsResponse containing unified, issuer, and connector-level error information.

payment_experience
​string · enum

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

Enum values:
redirect_to_url
invoke_sdk_client
display_qr_code
one_click
link_wallet
invoke_payment_app
display_wait_screen
collect_otp
payment_method_type
​string · enum

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

Enum values:
ach
affirm
afterpay_clearpay
alfamart
ali_pay
ali_pay_hk
alma
amazon_pay
connector_label
​string | null

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

Example: stripe_US_food
business_country
​string · enum
Enum values:
AF
AX
AL
DZ
AS
AD
AO
AI
business_label
​string | null

The label identifying the specific business unit or profile under which this payment was processed by the merchant.

business_sub_label
​string | null

An optional sub-label for further categorization of the business unit or profile used for this payment.

allowed_payment_method_types
​array | null

Allowed Payment Method Types for a given PaymentIntent

Enum values:
ach
affirm
afterpay_clearpay
alfamart
ali_pay
ali_pay_hk
alma
amazon_pay
manual_retry_allowed
​boolean | null

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

connector_transaction_id
​string | null

A unique identifier for a payment provided by the connector

Example: 993672945374576J
​object

frm message is an object sent inside the payments response...when frm is invoked, its value is Some(...), else its None

metadata
​object | null

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.

​object

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

​
​object

additional data that might be required by hyperswitch

reference_id
​string | null

reference(Identifier) to the payment at connector side

Example: 993672945374576J
​object
profile_id
​string | null

The business profile that is associated with this payment

​object

Details of surcharge applied on this payment, if applicable

merchant_decision
​string | null

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_id
​string | null

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

incremental_authorization_allowed
​boolean | null

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

authorization_count
​integer | null · int32

Total number of authorizations happened in an incremental_authorization payment

​array | null

List of incremental authorizations happened to the payment

​object

Details of external authentication

external_3ds_authentication_attempted
​boolean | null

Flag indicating if external 3ds authentication is made or not

expires_on
​string | null · date-time

Date Time for expiry of the payment

Example: 2022-09-10T10:11:12Z
fingerprint
​string | null

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

​object

Browser information to be used for 3DS 2.0

​

Describes the channel through which the payment was initiated.

payment_method_id
​string | null

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_id
​string | null

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

payment_method_status
​string · enum

Payment Method Status

Enum values:
active
inactive
processing
awaiting_data
new
updated
​string | null · date-time

Date time at which payment was updated

Example: 2022-09-10T10:11:12Z
​

Charge Information

frm_metadata
​object | null

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_applied
​boolean | null

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

extended_authorization_last_applied_at
​string | null · date-time

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

Example: 2022-09-10T10:11:12Z
request_extended_authorization
​boolean | null

Optional boolean value to extent authorization period of this payment

capture method must be manual or manual_multiple

Default: false
capture_before
​string | null · date-time

date and time after which this payment cannot be captured

merchant_order_reference_id
​string | null · maxLength: 255

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.

Example: Custom_Order_id_123
order_tax_amount
​integer · int64

This Unit struct represents MinorUnit in which core amount works

connector_mandate_id
​string | null

Connector Identifier for the payment method

card_discovery
​string · enum

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

Enum values:
manual
saved_card
click_to_pay
force_3ds_challenge
​boolean | null

Indicates if 3ds challenge is forced

force_3ds_challenge_trigger
​boolean | null

Indicates if 3ds challenge is triggered

issuer_error_code
​string | null

Error code received from the issuer in case of failed payments

issuer_error_message
​string | null

Error message received from the issuer in case of failed payments

is_iframe_redirection_enabled
​boolean | null

Indicates if the redirection has to open in the iframe

whole_connector_response
​string | null

Contains whole connector response

enable_partial_authorization
​boolean | null

Allow partial authorization for this payment

Default: false
enable_overcapture
​boolean | null

Bool indicating if overcapture must be requested for this payment

is_overcapture_enabled
​boolean | null

Boolean indicating whether overcapture is effectively enabled for this payment

​object
is_stored_credential
​boolean | null

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

Example: true
mit_category
​string · enum

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.

Enum values:
installment
unscheduled
recurring
resubmission
​object

Billing Descriptor information to be sent to the payment gateway

tokenization
​string · enum

The type of tokenization to use for the payment method

Enum values:
skip_psp
tokenize_at_psp
​object

Information identifying partner and merchant application initiating the request

​object
​array | null

Installment payment options associated with this payment, grouped by payment method

​object

Installment selection made by the customer during payment confirmation.

​object

Statistics for a customer within a single profile

​object

The authorized fee snapshot aggregated across a payment's capture rows.

None on the containing response means that no merchant commission snapshot exists. A calculated zero remains Some(0).


Payments - Retrieve

GET
https://paysw-wiki.lab.next-on.pro/dev-router
/payments/{payment_id}
api-key (header)
or
api-key (header)

Retrieves a Payment. This API can also be used to get the status of a previously initiated payment or next action for an ongoing payment

Payments - Retrieve › path Parameters

payment_id
​string · required

The identifier for payment

Payments - Retrieve › query Parameters

force_sync
​boolean | null

Decider to enable or disable the connector call for retrieve request

client_secret
​string | null

This is a token which expires after 15 minutes, used from the client to authenticate and create sessions from the SDK

expand_attempts
​boolean | null

If enabled provides list of attempts linked to payment intent

expand_captures
​boolean | null

If enabled provides list of captures linked to latest attempt

expand_customer_statistics
​boolean | null

When true, includes customer statistics for the payment profile (OLAP)

Payments - Retrieve › Responses

Gets the payment with final status

payment_id
​string · minLength: 30 · maxLength: 30 · required

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

Example: pay_mbabizu24mvu3mela5njyhpit4
merchant_id
​string · maxLength: 255 · required

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

Example: merchant_1668273825
status
​string · enum · 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).

Enum values:
succeeded
failed
cancelled
cancelled_post_capture
processing
requires_customer_action
requires_merchant_action
requires_payment_method
Default: requires_confirmation
amount
​integer · int64 · 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.,

Example: 6540
net_amount
​integer · int64 · 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

Example: 6540
amount_capturable
​integer · int64 · min: 100 · 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.

Example: 6540
processor_merchant_id
​string · maxLength: 255 · 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.

Example: merchant_1689512302
currency
​Currency · enum · required

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

Enum values:
AED
AFN
ALL
AMD
ANG
AOA
ARS
AUD
payment_method
​PaymentMethod · enum · required

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

Enum values:
card
card_redirect
pay_later
wallet
bank_redirect
bank_transfer
crypto
bank_debit
attempt_count
​integer · int32 · required

Total number of attempts associated with this payment

shipping_cost
​integer | null · int64

The shipping cost for the payment.

Example: 6540
amount_received
​integer | null · int64

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.

Example: 6540
initiator
​string · enum

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

Enum values:
platform
connected
sdk_authorization
​string | null

Token containing encoded information for sdk authorization.

Example: cHJvZmlsZV9pZD1wcm9mXzEyMyxwdWJsaXNoYWJsZV9rZXk9cGtfbGl2ZV8xMjM=
connector
​string | null

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

Example: stripe
​object

Additional metadata for payment intent state containing refunded and disputed amounts

client_secret
​string | null

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.

Example: pay_U42c409qyHwOkWo3vK60_secret_el9ksDkiB8hi6j9N78yo
created
​string | null · date-time

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

Example: 2022-09-10T10:11:12Z
modified_at
​string | null · date-time

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

Example: 2022-09-10T10:11:12Z
​object

Details of customer attached to this payment

description
​string | null

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

Example: It's my first payment request
​array | null

An array of refund objects associated with this payment. Empty or null if no refunds have been processed.

​array | null

List of disputes that happened on this intent

​array | null

List of attempts that happened on this intent

​array | null

List of captures done on latest attempt

mandate_id
​string | null · maxLength: 255

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

Example: mandate_iwer89rnjef349dni3
​object

Passing this object during payments creates a mandate. The mandate_type sub object is passed by the server.

setup_future_usage
​string · enum

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.
Enum values:
off_session
on_session
off_session
​boolean | null

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. This parameter can only be used with confirm=true.

Example: true
capture_on
​string | null · date-time

A timestamp (ISO 8601 code) that determines when the payment should be captured. Providing this field will automatically set capture to true

Example: 2022-09-10T10:11:12Z
capture_method
​string · enum

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.
Enum values:
automatic
manual
manual_multiple
scheduled
sequential_automatic
​object
payment_token
​string | null

Provide a reference to a stored payment method

Example: 187282ab-40ef-47a9-9206-5099ba31e432
​object
​object
​array | null

Information about the product , quantity and amount for connectors. (e.g. Klarna)

Example: [{ "product_name": "gillete creme", "quantity": 15, "amount" : 900 }]
return_url
​string | null

The URL to redirect after the completion of the operation

Example: https://hyperswitch.io
authentication_type
​string · enum

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.

Enum values:
three_ds
no_three_ds
Default: three_ds
statement_descriptor_name
​string | null · maxLength: 255

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.

Example: Hyperswitch Router
statement_descriptor_suffix
​string | null · maxLength: 255

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.

Example: Payment for shoes purchase
​
cancellation_reason
​string | null

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

error_code
​string | null

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

Example: E0001
error_message
​string | null

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

Example: Failed while verifying the card
unified_code
​string | null

error code unified across the connectors is received here if there was an error while calling connector

unified_message
​string | null

error message unified across the connectors is received here if there was an error while calling connector

​object

Complete error details for V1 PaymentsResponse containing unified, issuer, and connector-level error information.

payment_experience
​string · enum

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

Enum values:
redirect_to_url
invoke_sdk_client
display_qr_code
one_click
link_wallet
invoke_payment_app
display_wait_screen
collect_otp
payment_method_type
​string · enum

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

Enum values:
ach
affirm
afterpay_clearpay
alfamart
ali_pay
ali_pay_hk
alma
amazon_pay
connector_label
​string | null

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

Example: stripe_US_food
business_country
​string · enum
Enum values:
AF
AX
AL
DZ
AS
AD
AO
AI
business_label
​string | null

The label identifying the specific business unit or profile under which this payment was processed by the merchant.

business_sub_label
​string | null

An optional sub-label for further categorization of the business unit or profile used for this payment.

allowed_payment_method_types
​array | null

Allowed Payment Method Types for a given PaymentIntent

Enum values:
ach
affirm
afterpay_clearpay
alfamart
ali_pay
ali_pay_hk
alma
amazon_pay
manual_retry_allowed
​boolean | null

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

connector_transaction_id
​string | null

A unique identifier for a payment provided by the connector

Example: 993672945374576J
​object

frm message is an object sent inside the payments response...when frm is invoked, its value is Some(...), else its None

metadata
​object | null

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.

​object

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

​
​object

additional data that might be required by hyperswitch

reference_id
​string | null

reference(Identifier) to the payment at connector side

Example: 993672945374576J
​object
profile_id
​string | null

The business profile that is associated with this payment

​object

Details of surcharge applied on this payment, if applicable

merchant_decision
​string | null

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_id
​string | null

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

incremental_authorization_allowed
​boolean | null

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

authorization_count
​integer | null · int32

Total number of authorizations happened in an incremental_authorization payment

​array | null

List of incremental authorizations happened to the payment

​object

Details of external authentication

external_3ds_authentication_attempted
​boolean | null

Flag indicating if external 3ds authentication is made or not

expires_on
​string | null · date-time

Date Time for expiry of the payment

Example: 2022-09-10T10:11:12Z
fingerprint
​string | null

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

​object

Browser information to be used for 3DS 2.0

​

Describes the channel through which the payment was initiated.

payment_method_id
​string | null

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_id
​string | null

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

payment_method_status
​string · enum

Payment Method Status

Enum values:
active
inactive
processing
awaiting_data
new
updated
​string | null · date-time

Date time at which payment was updated

Example: 2022-09-10T10:11:12Z
​

Charge Information

frm_metadata
​object | null

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_applied
​boolean | null

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

extended_authorization_last_applied_at
​string | null · date-time

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

Example: 2022-09-10T10:11:12Z
request_extended_authorization
​boolean | null

Optional boolean value to extent authorization period of this payment

capture method must be manual or manual_multiple

Default: false
capture_before
​string | null · date-time

date and time after which this payment cannot be captured

merchant_order_reference_id
​string | null · maxLength: 255

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.

Example: Custom_Order_id_123
order_tax_amount
​integer · int64

This Unit struct represents MinorUnit in which core amount works

connector_mandate_id
​string | null

Connector Identifier for the payment method

card_discovery
​string · enum

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

Enum values:
manual
saved_card
click_to_pay
force_3ds_challenge
​boolean | null

Indicates if 3ds challenge is forced

force_3ds_challenge_trigger
​boolean | null

Indicates if 3ds challenge is triggered

issuer_error_code
​string | null

Error code received from the issuer in case of failed payments

issuer_error_message
​string | null

Error message received from the issuer in case of failed payments

is_iframe_redirection_enabled
​boolean | null

Indicates if the redirection has to open in the iframe

whole_connector_response
​string | null

Contains whole connector response

enable_partial_authorization
​boolean | null

Allow partial authorization for this payment

Default: false
enable_overcapture
​boolean | null

Bool indicating if overcapture must be requested for this payment

is_overcapture_enabled
​boolean | null

Boolean indicating whether overcapture is effectively enabled for this payment

​object
is_stored_credential
​boolean | null

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

Example: true
mit_category
​string · enum

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.

Enum values:
installment
unscheduled
recurring
resubmission
​object

Billing Descriptor information to be sent to the payment gateway

tokenization
​string · enum

The type of tokenization to use for the payment method

Enum values:
skip_psp
tokenize_at_psp
​object

Information identifying partner and merchant application initiating the request

​object
​array | null

Installment payment options associated with this payment, grouped by payment method

​object

Installment selection made by the customer during payment confirmation.

​object

Statistics for a customer within a single profile

​object

The authorized fee snapshot aggregated across a payment's capture rows.

None on the containing response means that no merchant commission snapshot exists. A calculated zero remains Some(0).


Payments - Update

POST
https://paysw-wiki.lab.next-on.pro/dev-router
/payments/{payment_id}
api-key (header)
or
api-key (header)

To update the properties of a PaymentIntent object. This may include attaching a payment method, or attaching customer object or metadata fields after the Payment is created

Payments - Update › path Parameters

payment_id
​string · required

The identifier for payment

Payments - Update › Request Body

amount
​integer | null · int64 · min: 0

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.

Example: 6540
order_tax_amount
​integer | null · int64

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

Example: 6540
currency
​string · enum

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

Enum values:
AED
AFN
ALL
AMD
ANG
AOA
ARS
AUD
amount_to_capture
​integer | null · int64

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.

Example: 6540
shipping_cost
​integer | null · int64

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

Example: 6540
payment_id
​string | null · minLength: 30 · maxLength: 30

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.

Example: pay_mbabizu24mvu3mela5njyhpit4
​
connector
​array | null

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

Enum values:
flexifai
fiftyfourpay
honeycoin
k218pay
bitex
hypergate
maguapay
payadmit
Example: ["stripe","adyen"]
capture_method
​string · enum

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.
Enum values:
automatic
manual
manual_multiple
scheduled
sequential_automatic
authentication_type
​string · enum

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.

Enum values:
three_ds
no_three_ds
Default: three_ds
​object
confirm
​boolean | null

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.

Example: true
Default: false
​object

Passing this object creates a new customer or attaches an existing customer to the payment

customer_id
​string | null · minLength: 1 · maxLength: 64

The identifier for the customer

Example: cus_y3oqhf46pyzuxjbcn2giaqnb44
​object

Merchant-provided customer statistics for advanced routing. All fields are optional.

off_session
​boolean | null

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

Example: true
description
​string | null

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

Example: It's my first payment request
return_url
​string | null · maxLength: 2048

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

Example: https://hyperswitch.io
setup_future_usage
​string · enum

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.
Enum values:
off_session
on_session
​object

The payment method information provided for making a payment

payment_method
​string · enum

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

Enum values:
card
card_redirect
pay_later
wallet
bank_redirect
bank_transfer
crypto
bank_debit
payment_token
​string | null

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.

Example: 187282ab-40ef-47a9-9206-5099ba31e432
​object
​array | 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: [{ "product_name": "Apple iPhone 16", "quantity": 1, "amount" : 69000 "product_img_link" : "https://dummy-img-link.com" }]
​object

Passing this object during payments creates a mandate. The mandate_type sub object is passed by the server.

​object

This "CustomerAcceptance" object is passed during Payments-Confirm request, it enlists the type, time, and mode of acceptance properties related to an acceptance done by the customer. The customer_acceptance sub object is usually passed by the SDK or client.

​object

Browser information to be used for 3DS 2.0

payment_experience
​string · enum

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

Enum values:
redirect_to_url
invoke_sdk_client
display_qr_code
one_click
link_wallet
invoke_payment_app
display_wait_screen
collect_otp
payment_method_type
​string · enum

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

Enum values:
ach
affirm
afterpay_clearpay
alfamart
ali_pay
ali_pay_hk
alma
amazon_pay
​object

Merchant connector details used to make payments.

allowed_payment_method_types
​array | null

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

Enum values:
ach
affirm
afterpay_clearpay
alfamart
ali_pay
ali_pay_hk
alma
amazon_pay
retry_action
​string · enum

Denotes the retry action

Enum values:
manual_retry
requeue
metadata
​object | null

Merchant-defined string key/value pairs. Limits: up to 50 keys; key names up to 40 characters; values up to 500 characters. PaySwitch does not interpret these keys—use them for your own logic (e.g. KYC status, trust tier, internal user id). Full guide: /metadata. Do not store secrets, card numbers, or passwords in metadata.

​object

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

payment_link
​boolean | null

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

Example: true
Default: false
​object

Configure a custom payment link for the particular payment

payment_link_config_id
​string | null

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

​object

Details of surcharge applied on this payment, if applicable

payment_type
​string · enum

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

Enum values:
normal
new_mandate
setup_mandate
recurring_mandate
installment
request_incremental_authorization
​boolean | null

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

session_expiry
​integer | null · int32 · min: 0

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

Example: 900
frm_metadata
​object | null

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

Represents external 3DS authentication data used in the payment flow.

​

Details required for recurring payment

​

Fee information for Split Payments to be charged on the payment being collected

request_extended_authorization
​boolean | null

Optional boolean value to extent authorization period of this payment

capture method must be manual or manual_multiple

Default: false
merchant_order_reference_id
​string | null · maxLength: 255

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.

Example: Custom_Order_id_123
skip_external_tax_calculation
​boolean | null

Whether to calculate tax for this payment intent

psd2_sca_exemption_type
​string · enum

SCA Exemptions types available for authentication

Enum values:
low_value
transaction_risk_analysis
​object
force_3ds_challenge
​boolean | null

Indicates if 3ds challenge is forced

threeds_method_comp_ind
​string · enum

Indicates if 3DS method data was successfully completed or not

Enum values:
Y
N
U
is_iframe_redirection_enabled
​boolean | null

Indicates if the redirection has to open in the iframe

all_keys_required
​boolean | null

If enabled, provides whole connector response

​

Describes the channel through which the payment was initiated.

tax_status
​string · enum
Enum values:
taxable
exempt
discount_amount
​integer | null · int64

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

Example: 6540
shipping_amount_tax
​integer · int64

This Unit struct represents MinorUnit in which core amount works

duty_amount
​integer · int64

This Unit struct represents MinorUnit in which core amount works

order_date
​string | null · date-time

Date the payer placed the order.

enable_partial_authorization
​boolean | null

Allow partial authorization for this payment

Default: false
enable_overcapture
​boolean | null

Boolean indicating whether to enable overcapture for this payment

Example: true
is_stored_credential
​boolean | null

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

Example: true
mit_category
​string · enum

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.

Enum values:
installment
unscheduled
recurring
resubmission
​object

Billing Descriptor information to be sent to the payment gateway

tokenization
​string · enum

The type of tokenization to use for the payment method

Enum values:
skip_psp
tokenize_at_psp
​object

Information identifying partner and merchant application initiating the request

​array | null

Installment payment options grouped by payment method. When provided, the payment is treated as an installment payment.

​object

Installment selection sent by the customer during payment confirmation.

Payments - Update › Responses

Payment updated

payment_id
​string · minLength: 30 · maxLength: 30 · required

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

Example: pay_mbabizu24mvu3mela5njyhpit4
merchant_id
​string · maxLength: 255 · required

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

Example: merchant_1668273825
status
​string · enum · 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).

Enum values:
succeeded
failed
cancelled
cancelled_post_capture
processing
requires_customer_action
requires_merchant_action
requires_payment_method
Default: requires_confirmation
amount
​integer · int64 · 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.,

Example: 6540
net_amount
​integer · int64 · 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

Example: 6540
amount_capturable
​integer · int64 · min: 100 · 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.

Example: 6540
processor_merchant_id
​string · maxLength: 255 · 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.

Example: merchant_1689512302
currency
​Currency · enum · required

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

Enum values:
AED
AFN
ALL
AMD
ANG
AOA
ARS
AUD
payment_method
​PaymentMethod · enum · required

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

Enum values:
card
card_redirect
pay_later
wallet
bank_redirect
bank_transfer
crypto
bank_debit
attempt_count
​integer · int32 · required

Total number of attempts associated with this payment

shipping_cost
​integer | null · int64

The shipping cost for the payment.

Example: 6540
amount_received
​integer | null · int64

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.

Example: 6540
initiator
​string · enum

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

Enum values:
platform
connected
sdk_authorization
​string | null

Token containing encoded information for sdk authorization.

Example: cHJvZmlsZV9pZD1wcm9mXzEyMyxwdWJsaXNoYWJsZV9rZXk9cGtfbGl2ZV8xMjM=
connector
​string | null

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

Example: stripe
​object

Additional metadata for payment intent state containing refunded and disputed amounts

client_secret
​string | null

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.

Example: pay_U42c409qyHwOkWo3vK60_secret_el9ksDkiB8hi6j9N78yo
created
​string | null · date-time

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

Example: 2022-09-10T10:11:12Z
modified_at
​string | null · date-time

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

Example: 2022-09-10T10:11:12Z
description
​string | null

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

Example: It's my first payment request
​array | null

An array of refund objects associated with this payment. Empty or null if no refunds have been processed.

​array | null

List of disputes that happened on this intent

​array | null

List of attempts that happened on this intent

​array | null

List of captures done on latest attempt

mandate_id
​string | null · maxLength: 255

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

Example: mandate_iwer89rnjef349dni3
​object

Passing this object during payments creates a mandate. The mandate_type sub object is passed by the server.

setup_future_usage
​string · enum

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.
Enum values:
off_session
on_session
off_session
​boolean | null

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. This parameter can only be used with confirm=true.

Example: true
capture_method
​string · enum

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.
Enum values:
automatic
manual
manual_multiple
scheduled
sequential_automatic
​object
payment_token
​string | null

Provide a reference to a stored payment method

Example: 187282ab-40ef-47a9-9206-5099ba31e432
​object
​object
​array | null

Information about the product , quantity and amount for connectors. (e.g. Klarna)

Example: [{ "product_name": "gillete creme", "quantity": 15, "amount" : 900 }]
return_url
​string | null

The URL to redirect after the completion of the operation

Example: https://hyperswitch.io
authentication_type
​string · enum

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.

Enum values:
three_ds
no_three_ds
Default: three_ds
statement_descriptor_name
​string | null · maxLength: 255

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.

Example: Hyperswitch Router
statement_descriptor_suffix
​string | null · maxLength: 255

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.

Example: Payment for shoes purchase
​
cancellation_reason
​string | null

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

error_code
​string | null

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

Example: E0001
error_message
​string | null

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

Example: Failed while verifying the card
​object

Complete error details for V1 PaymentsResponse containing unified, issuer, and connector-level error information.

payment_experience
​string · enum

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

Enum values:
redirect_to_url
invoke_sdk_client
display_qr_code
one_click
link_wallet
invoke_payment_app
display_wait_screen
collect_otp
payment_method_type
​string · enum

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

Enum values:
ach
affirm
afterpay_clearpay
alfamart
ali_pay
ali_pay_hk
alma
amazon_pay
connector_label
​string | null

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

Example: stripe_US_food
business_country
​string · enum
Enum values:
AF
AX
AL
DZ
AS
AD
AO
AI
business_label
​string | null

The label identifying the specific business unit or profile under which this payment was processed by the merchant.

business_sub_label
​string | null

An optional sub-label for further categorization of the business unit or profile used for this payment.

allowed_payment_method_types
​array | null

Allowed Payment Method Types for a given PaymentIntent

Enum values:
ach
affirm
afterpay_clearpay
alfamart
ali_pay
ali_pay_hk
alma
amazon_pay
manual_retry_allowed
​boolean | null

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

connector_transaction_id
​string | null

A unique identifier for a payment provided by the connector

Example: 993672945374576J
​object

frm message is an object sent inside the payments response...when frm is invoked, its value is Some(...), else its None

metadata
​object | null

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.

​object

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

​
​object

additional data that might be required by hyperswitch

reference_id
​string | null

reference(Identifier) to the payment at connector side

Example: 993672945374576J
​object
profile_id
​string | null

The business profile that is associated with this payment

​object

Details of surcharge applied on this payment, if applicable

merchant_decision
​string | null

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_id
​string | null

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

incremental_authorization_allowed
​boolean | null

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

authorization_count
​integer | null · int32

Total number of authorizations happened in an incremental_authorization payment

​array | null

List of incremental authorizations happened to the payment

​object

Details of external authentication

external_3ds_authentication_attempted
​boolean | null

Flag indicating if external 3ds authentication is made or not

expires_on
​string | null · date-time

Date Time for expiry of the payment

Example: 2022-09-10T10:11:12Z
fingerprint
​string | null

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

​object

Browser information to be used for 3DS 2.0

​

Describes the channel through which the payment was initiated.

payment_method_id
​string | null

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_id
​string | null

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

payment_method_status
​string · enum

Payment Method Status

Enum values:
active
inactive
processing
awaiting_data
new
updated
​string | null · date-time

Date time at which payment was updated

Example: 2022-09-10T10:11:12Z
​

Charge Information

frm_metadata
​object | null

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_applied
​boolean | null

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

extended_authorization_last_applied_at
​string | null · date-time

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

Example: 2022-09-10T10:11:12Z
request_extended_authorization
​boolean | null

Optional boolean value to extent authorization period of this payment

capture method must be manual or manual_multiple

Default: false
capture_before
​string | null · date-time

date and time after which this payment cannot be captured

merchant_order_reference_id
​string | null · maxLength: 255

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.

Example: Custom_Order_id_123
order_tax_amount
​integer · int64

This Unit struct represents MinorUnit in which core amount works

connector_mandate_id
​string | null

Connector Identifier for the payment method

card_discovery
​string · enum

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

Enum values:
manual
saved_card
click_to_pay
force_3ds_challenge
​boolean | null

Indicates if 3ds challenge is forced

force_3ds_challenge_trigger
​boolean | null

Indicates if 3ds challenge is triggered

issuer_error_code
​string | null

Error code received from the issuer in case of failed payments

issuer_error_message
​string | null

Error message received from the issuer in case of failed payments

is_iframe_redirection_enabled
​boolean | null

Indicates if the redirection has to open in the iframe

whole_connector_response
​string | null

Contains whole connector response

enable_partial_authorization
​boolean | null

Allow partial authorization for this payment

Default: false
enable_overcapture
​boolean | null

Bool indicating if overcapture must be requested for this payment

is_overcapture_enabled
​boolean | null

Boolean indicating whether overcapture is effectively enabled for this payment

​object
is_stored_credential
​boolean | null

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

Example: true
mit_category
​string · enum

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.

Enum values:
installment
unscheduled
recurring
resubmission
​object

Billing Descriptor information to be sent to the payment gateway

tokenization
​string · enum

The type of tokenization to use for the payment method

Enum values:
skip_psp
tokenize_at_psp
​object

Information identifying partner and merchant application initiating the request

​object
​array | null

Installment payment options associated with this payment, grouped by payment method

​object

Installment selection made by the customer during payment confirmation.

​object

Statistics for a customer within a single profile

​object

The authorized fee snapshot aggregated across a payment's capture rows.

None on the containing response means that no merchant commission snapshot exists. A calculated zero remains Some(0).


Payments - Confirm

POST
https://paysw-wiki.lab.next-on.pro/dev-router
/payments/{payment_id}/confirm
api-key (header)
or
api-key (header)

Confirms a payment intent that was previously created with confirm: false. This action attempts to authorize the payment with the payment processor.

Expected status transitions after confirmation:

  • succeeded: If authorization is successful and capture_method is automatic.
  • requires_capture: If authorization is successful and capture_method is manual.
  • failed: If authorization fails.

Payments - Confirm › path Parameters

payment_id
​string · required

The identifier for payment

Payments - Confirm › Request Body

amount
​integer | null · int64 · min: 0

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.

Example: 6540
order_tax_amount
​integer | null · int64

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

Example: 6540
currency
​string · enum

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

Enum values:
AED
AFN
ALL
AMD
ANG
AOA
ARS
AUD
amount_to_capture
​integer | null · int64

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.

Example: 6540
shipping_cost
​integer | null · int64

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

Example: 6540
payment_id
​string | null · minLength: 30 · maxLength: 30

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.

Example: pay_mbabizu24mvu3mela5njyhpit4
​
connector
​array | null

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

Enum values:
flexifai
fiftyfourpay
honeycoin
k218pay
bitex
hypergate
maguapay
payadmit
Example: ["stripe","adyen"]
capture_method
​string · enum

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.
Enum values:
automatic
manual
manual_multiple
scheduled
sequential_automatic
authentication_type
​string · enum

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.

Enum values:
three_ds
no_three_ds
Default: three_ds
​object
confirm
​boolean | null

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.

Example: true
Default: false
​object

Passing this object creates a new customer or attaches an existing customer to the payment

customer_id
​string | null · minLength: 1 · maxLength: 64

The identifier for the customer

Example: cus_y3oqhf46pyzuxjbcn2giaqnb44
​object

Merchant-provided customer statistics for advanced routing. All fields are optional.

off_session
​boolean | null

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

Example: true
description
​string | null

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

Example: It's my first payment request
return_url
​string | null · maxLength: 2048

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

Example: https://hyperswitch.io
setup_future_usage
​string · enum

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.
Enum values:
off_session
on_session
​object

The payment method information provided for making a payment

payment_method
​string · enum

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

Enum values:
card
card_redirect
pay_later
wallet
bank_redirect
bank_transfer
crypto
bank_debit
payment_token
​string | null

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.

Example: 187282ab-40ef-47a9-9206-5099ba31e432
​object
​array | 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: [{ "product_name": "Apple iPhone 16", "quantity": 1, "amount" : 69000 "product_img_link" : "https://dummy-img-link.com" }]
client_secret
​string | null

It's a token used for client side verification.

Example: pay_U42c409qyHwOkWo3vK60_secret_el9ksDkiB8hi6j9N78yo
​object

Passing this object during payments creates a mandate. The mandate_type sub object is passed by the server.

​object

This "CustomerAcceptance" object is passed during Payments-Confirm request, it enlists the type, time, and mode of acceptance properties related to an acceptance done by the customer. The customer_acceptance sub object is usually passed by the SDK or client.

mandate_id
​string | null · maxLength: 64

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

Example: mandate_iwer89rnjef349dni3
​object

Browser information to be used for 3DS 2.0

payment_experience
​string · enum

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

Enum values:
redirect_to_url
invoke_sdk_client
display_qr_code
one_click
link_wallet
invoke_payment_app
display_wait_screen
collect_otp
payment_method_type
​string · enum

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

Enum values:
ach
affirm
afterpay_clearpay
alfamart
ali_pay
ali_pay_hk
alma
amazon_pay
​object

Merchant connector details used to make payments.

allowed_payment_method_types
​array | null

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

Enum values:
ach
affirm
afterpay_clearpay
alfamart
ali_pay
ali_pay_hk
alma
amazon_pay
retry_action
​string · enum

Denotes the retry action

Enum values:
manual_retry
requeue
metadata
​object | null

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.

​object

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

payment_link
​boolean | null

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

Example: true
Default: false
​object

Configure a custom payment link for the particular payment

payment_link_config_id
​string | null

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

payment_type
​string · enum

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

Enum values:
normal
new_mandate
setup_mandate
recurring_mandate
installment
request_incremental_authorization
​boolean | null

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

session_expiry
​integer | null · int32 · min: 0

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

Example: 900
frm_metadata
​object | null

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

Represents external 3DS authentication data used in the payment flow.

​

Details required for recurring payment

​

Fee information for Split Payments to be charged on the payment being collected

request_extended_authorization
​boolean | null

Optional boolean value to extent authorization period of this payment

capture method must be manual or manual_multiple

Default: false
merchant_order_reference_id
​string | null · maxLength: 255

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.

Example: Custom_Order_id_123
skip_external_tax_calculation
​boolean | null

Whether to calculate tax for this payment intent

psd2_sca_exemption_type
​string · enum

SCA Exemptions types available for authentication

Enum values:
low_value
transaction_risk_analysis
​object
force_3ds_challenge
​boolean | null

Indicates if 3ds challenge is forced

threeds_method_comp_ind
​string · enum

Indicates if 3DS method data was successfully completed or not

Enum values:
Y
N
U
is_iframe_redirection_enabled
​boolean | null

Indicates if the redirection has to open in the iframe

all_keys_required
​boolean | null

If enabled, provides whole connector response

​

Describes the channel through which the payment was initiated.

tax_status
​string · enum
Enum values:
taxable
exempt
discount_amount
​integer | null · int64

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

Example: 6540
shipping_amount_tax
​integer · int64

This Unit struct represents MinorUnit in which core amount works

duty_amount
​integer · int64

This Unit struct represents MinorUnit in which core amount works

order_date
​string | null · date-time

Date the payer placed the order.

enable_partial_authorization
​boolean | null

Allow partial authorization for this payment

Default: false
is_stored_credential
​boolean | null

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

Example: true
mit_category
​string · enum

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.

Enum values:
installment
unscheduled
recurring
resubmission
​object

Billing Descriptor information to be sent to the payment gateway

tokenization
​string · enum

The type of tokenization to use for the payment method

Enum values:
skip_psp
tokenize_at_psp
​object

Information identifying partner and merchant application initiating the request

​array | null

Installment payment options grouped by payment method. When provided, the payment is treated as an installment payment.

​object

Installment selection sent by the customer during payment confirmation.

Payments - Confirm › Responses

Payment confirmed

payment_id
​string · minLength: 30 · maxLength: 30 · required

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

Example: pay_mbabizu24mvu3mela5njyhpit4
merchant_id
​string · maxLength: 255 · required

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

Example: merchant_1668273825
status
​string · enum · 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).

Enum values:
succeeded
failed
cancelled
cancelled_post_capture
processing
requires_customer_action
requires_merchant_action
requires_payment_method
Default: requires_confirmation
amount
​integer · int64 · 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.,

Example: 6540
net_amount
​integer · int64 · 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

Example: 6540
amount_capturable
​integer · int64 · min: 100 · 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.

Example: 6540
processor_merchant_id
​string · maxLength: 255 · 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.

Example: merchant_1689512302
currency
​Currency · enum · required

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

Enum values:
AED
AFN
ALL
AMD
ANG
AOA
ARS
AUD
payment_method
​PaymentMethod · enum · required

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

Enum values:
card
card_redirect
pay_later
wallet
bank_redirect
bank_transfer
crypto
bank_debit
attempt_count
​integer · int32 · required

Total number of attempts associated with this payment

shipping_cost
​integer | null · int64

The shipping cost for the payment.

Example: 6540
amount_received
​integer | null · int64

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.

Example: 6540
initiator
​string · enum

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

Enum values:
platform
connected
sdk_authorization
​string | null

Token containing encoded information for sdk authorization.

Example: cHJvZmlsZV9pZD1wcm9mXzEyMyxwdWJsaXNoYWJsZV9rZXk9cGtfbGl2ZV8xMjM=
connector
​string | null

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

Example: stripe
​object

Additional metadata for payment intent state containing refunded and disputed amounts

client_secret
​string | null

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.

Example: pay_U42c409qyHwOkWo3vK60_secret_el9ksDkiB8hi6j9N78yo
created
​string | null · date-time

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

Example: 2022-09-10T10:11:12Z
modified_at
​string | null · date-time

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

Example: 2022-09-10T10:11:12Z
description
​string | null

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

Example: It's my first payment request
​array | null

An array of refund objects associated with this payment. Empty or null if no refunds have been processed.

​array | null

List of disputes that happened on this intent

​array | null

List of attempts that happened on this intent

​array | null

List of captures done on latest attempt

mandate_id
​string | null · maxLength: 255

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

Example: mandate_iwer89rnjef349dni3
​object

Passing this object during payments creates a mandate. The mandate_type sub object is passed by the server.

setup_future_usage
​string · enum

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.
Enum values:
off_session
on_session
off_session
​boolean | null

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. This parameter can only be used with confirm=true.

Example: true
capture_method
​string · enum

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.
Enum values:
automatic
manual
manual_multiple
scheduled
sequential_automatic
​object
payment_token
​string | null

Provide a reference to a stored payment method

Example: 187282ab-40ef-47a9-9206-5099ba31e432
​object
​object
​array | null

Information about the product , quantity and amount for connectors. (e.g. Klarna)

Example: [{ "product_name": "gillete creme", "quantity": 15, "amount" : 900 }]
return_url
​string | null

The URL to redirect after the completion of the operation

Example: https://hyperswitch.io
authentication_type
​string · enum

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.

Enum values:
three_ds
no_three_ds
Default: three_ds
statement_descriptor_name
​string | null · maxLength: 255

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.

Example: Hyperswitch Router
statement_descriptor_suffix
​string | null · maxLength: 255

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.

Example: Payment for shoes purchase
​
cancellation_reason
​string | null

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

error_code
​string | null

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

Example: E0001
error_message
​string | null

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

Example: Failed while verifying the card
​object

Complete error details for V1 PaymentsResponse containing unified, issuer, and connector-level error information.

payment_experience
​string · enum

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

Enum values:
redirect_to_url
invoke_sdk_client
display_qr_code
one_click
link_wallet
invoke_payment_app
display_wait_screen
collect_otp
payment_method_type
​string · enum

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

Enum values:
ach
affirm
afterpay_clearpay
alfamart
ali_pay
ali_pay_hk
alma
amazon_pay
connector_label
​string | null

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

Example: stripe_US_food
business_country
​string · enum
Enum values:
AF
AX
AL
DZ
AS
AD
AO
AI
business_label
​string | null

The label identifying the specific business unit or profile under which this payment was processed by the merchant.

business_sub_label
​string | null

An optional sub-label for further categorization of the business unit or profile used for this payment.

allowed_payment_method_types
​array | null

Allowed Payment Method Types for a given PaymentIntent

Enum values:
ach
affirm
afterpay_clearpay
alfamart
ali_pay
ali_pay_hk
alma
amazon_pay
manual_retry_allowed
​boolean | null

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

connector_transaction_id
​string | null

A unique identifier for a payment provided by the connector

Example: 993672945374576J
​object

frm message is an object sent inside the payments response...when frm is invoked, its value is Some(...), else its None

metadata
​object | null

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.

​object

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

​
​object

additional data that might be required by hyperswitch

reference_id
​string | null

reference(Identifier) to the payment at connector side

Example: 993672945374576J
​object
profile_id
​string | null

The business profile that is associated with this payment

​object

Details of surcharge applied on this payment, if applicable

merchant_decision
​string | null

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_id
​string | null

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

incremental_authorization_allowed
​boolean | null

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

authorization_count
​integer | null · int32

Total number of authorizations happened in an incremental_authorization payment

​array | null

List of incremental authorizations happened to the payment

​object

Details of external authentication

external_3ds_authentication_attempted
​boolean | null

Flag indicating if external 3ds authentication is made or not

expires_on
​string | null · date-time

Date Time for expiry of the payment

Example: 2022-09-10T10:11:12Z
fingerprint
​string | null

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

​object

Browser information to be used for 3DS 2.0

​

Describes the channel through which the payment was initiated.

payment_method_id
​string | null

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_id
​string | null

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

payment_method_status
​string · enum

Payment Method Status

Enum values:
active
inactive
processing
awaiting_data
new
updated
​string | null · date-time

Date time at which payment was updated

Example: 2022-09-10T10:11:12Z
​

Charge Information

frm_metadata
​object | null

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_applied
​boolean | null

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

extended_authorization_last_applied_at
​string | null · date-time

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

Example: 2022-09-10T10:11:12Z
request_extended_authorization
​boolean | null

Optional boolean value to extent authorization period of this payment

capture method must be manual or manual_multiple

Default: false
capture_before
​string | null · date-time

date and time after which this payment cannot be captured

merchant_order_reference_id
​string | null · maxLength: 255

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.

Example: Custom_Order_id_123
order_tax_amount
​integer · int64

This Unit struct represents MinorUnit in which core amount works

connector_mandate_id
​string | null

Connector Identifier for the payment method

card_discovery
​string · enum

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

Enum values:
manual
saved_card
click_to_pay
force_3ds_challenge
​boolean | null

Indicates if 3ds challenge is forced

force_3ds_challenge_trigger
​boolean | null

Indicates if 3ds challenge is triggered

issuer_error_code
​string | null

Error code received from the issuer in case of failed payments

issuer_error_message
​string | null

Error message received from the issuer in case of failed payments

is_iframe_redirection_enabled
​boolean | null

Indicates if the redirection has to open in the iframe

whole_connector_response
​string | null

Contains whole connector response

enable_partial_authorization
​boolean | null

Allow partial authorization for this payment

Default: false
enable_overcapture
​boolean | null

Bool indicating if overcapture must be requested for this payment

is_overcapture_enabled
​boolean | null

Boolean indicating whether overcapture is effectively enabled for this payment

​object
is_stored_credential
​boolean | null

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

Example: true
mit_category
​string · enum

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.

Enum values:
installment
unscheduled
recurring
resubmission
​object

Billing Descriptor information to be sent to the payment gateway

tokenization
​string · enum

The type of tokenization to use for the payment method

Enum values:
skip_psp
tokenize_at_psp
​object

Information identifying partner and merchant application initiating the request

​object
​array | null

Installment payment options associated with this payment, grouped by payment method

​object

Installment selection made by the customer during payment confirmation.

​object

Statistics for a customer within a single profile

​object

The authorized fee snapshot aggregated across a payment's capture rows.

None on the containing response means that no merchant commission snapshot exists. A calculated zero remains Some(0).


Payments — detailed read model (OLAP)

GET
https://paysw-wiki.lab.next-on.pro/dev-router
/payments/{payment_id}/details
api-key (header)

Returns an expanded payment record: intent, attempts, refunds, disputes, webhook history, etc.

Payments — detailed read model (OLAP) › path Parameters

payment_id
​string · required

The identifier for payment

Payments — detailed read model (OLAP) › query Parameters

expand_customer_statistics
​boolean | null

When true, includes customer statistics for the payment profile (OLAP)

Payments — detailed read model (OLAP) › Responses

Payment details

Comprehensive payment details response returned by `GET /payments/{payment_id}/details`. Aggregates data from multiple sources in a single response: - Payment intent and all of its attempts fully expanded. - Full customer details and billing/shipping addresses. - All associated refunds and disputes. - Webhook execution history with per-attempt request/response payloads. - Per-field origin metadata indicating which values were supplied by the merchant versus generated by the platform.
payment_id
​string · required
merchant_id
​string · required
status
​IntentStatus · enum · 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).

Enum values:
succeeded
failed
cancelled
cancelled_post_capture
processing
requires_customer_action
requires_merchant_action
requires_payment_method
amount
​integer · int64 · required
net_amount
​integer · int64 · required

Net amount including surcharge and tax. net_amount = amount + surcharge_amount + tax_on_surcharge + shipping_cost + order_tax_amount

amount_capturable
​integer · int64 · required
currency
​string · required

Three-letter ISO 4217 currency code.

​PaymentAttemptDetailedResponse[] · required

The list is ordered by created_at ascending.

​RefundResponse[] · required
​DisputeResponsePaymentsRetrieve[] · required
​WebhookDeliveryAttemptDetail[] · required

Webhook delivery records from the Postgres events table. Each entry corresponds to one delivery attempt (including retries). Records are grouped by initial_attempt_id.

​FieldOrigins · required

A record of which top-level fields in [PaymentDetailedResponse] were merchant-provided vs. platform-generated for this specific payment intent.

Keys are field names matching [PaymentDetailedResponse]'s serde names. Any field absent from this map should be treated as GeneratedByPlatform.

shipping_cost
​integer | null · int64
amount_received
​integer | null · int64
description
​string | null

Merchant-supplied description for this payment.

metadata
​

Merchant-supplied metadata key/value pairs.

created
​string | null
modified_at
​string | null
​object

Details of customer attached to this payment

​object
​object
​object

Statistics for a customer within a single profile

​object

The authorized fee snapshot aggregated across a payment's capture rows.

None on the containing response means that no merchant commission snapshot exists. A calculated zero remains Some(0).


Payments - Capture

POST
https://paysw-wiki.lab.next-on.pro/dev-router
/payments/{payment_id}/capture
api-key (header)

Captures the funds for a previously authorized payment intent where capture_method was set to manual and the payment is in a requires_capture state.

Upon successful capture, the payment status usually transitions to succeeded. The amount_to_capture can be specified in the request body; it must be less than or equal to the payment's amount_capturable. If omitted, the full capturable amount is captured.

A payment must be in a capturable state (e.g., requires_capture). Attempting to capture an already succeeded (and fully captured) payment or one in an invalid state will lead to an error.

Payments - Capture › path Parameters

payment_id
​string · required

The identifier for payment

Payments - Capture › Request Body

merchant_id
​string | null

The unique identifier for the merchant. This is usually inferred from the API key.

amount_to_capture
​integer | null · int64

The amount to capture, in the lowest denomination of the currency. If omitted, the entire amount_capturable of the payment will be captured. Must be less than or equal to the current amount_capturable.

Example: 6540
refund_uncaptured_amount
​boolean | null

Decider to refund the uncaptured amount. (Currently not fully supported or behavior may vary by connector).

statement_descriptor_suffix
​string | null

A dynamic suffix that appears on your customer's credit card statement. This is concatenated with the (shortened) descriptor prefix set on your account to form the complete statement descriptor. The combined length should not exceed connector-specific limits (typically 22 characters).

statement_descriptor_prefix
​string | null

An optional prefix for the statement descriptor that appears on your customer's credit card statement. This can override the default prefix set on your merchant account. The combined length of prefix and suffix should not exceed connector-specific limits (typically 22 characters).

​object

Merchant connector details used to make payments.

all_keys_required
​boolean | null

If true, returns stringified connector raw response body

Payments - Capture › Responses

Payment captured

payment_id
​string · minLength: 30 · maxLength: 30 · required

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

Example: pay_mbabizu24mvu3mela5njyhpit4
merchant_id
​string · maxLength: 255 · required

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

Example: merchant_1668273825
status
​string · enum · 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).

Enum values:
succeeded
failed
cancelled
cancelled_post_capture
processing
requires_customer_action
requires_merchant_action
requires_payment_method
Default: requires_confirmation
amount
​integer · int64 · 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.,

Example: 6540
net_amount
​integer · int64 · 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

Example: 6540
amount_capturable
​integer · int64 · min: 100 · 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.

Example: 6540
processor_merchant_id
​string · maxLength: 255 · 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.

Example: merchant_1689512302
currency
​Currency · enum · required

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

Enum values:
AED
AFN
ALL
AMD
ANG
AOA
ARS
AUD
payment_method
​PaymentMethod · enum · required

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

Enum values:
card
card_redirect
pay_later
wallet
bank_redirect
bank_transfer
crypto
bank_debit
attempt_count
​integer · int32 · required

Total number of attempts associated with this payment

shipping_cost
​integer | null · int64

The shipping cost for the payment.

Example: 6540
amount_received
​integer | null · int64

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.

Example: 6540
initiator
​string · enum

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

Enum values:
platform
connected
sdk_authorization
​string | null

Token containing encoded information for sdk authorization.

Example: cHJvZmlsZV9pZD1wcm9mXzEyMyxwdWJsaXNoYWJsZV9rZXk9cGtfbGl2ZV8xMjM=
connector
​string | null

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

Example: stripe
​object

Additional metadata for payment intent state containing refunded and disputed amounts

client_secret
​string | null

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.

Example: pay_U42c409qyHwOkWo3vK60_secret_el9ksDkiB8hi6j9N78yo
created
​string | null · date-time

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

Example: 2022-09-10T10:11:12Z
modified_at
​string | null · date-time

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

Example: 2022-09-10T10:11:12Z
​object

Details of customer attached to this payment

description
​string | null

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

Example: It's my first payment request
​array | null

An array of refund objects associated with this payment. Empty or null if no refunds have been processed.

​array | null

List of disputes that happened on this intent

​array | null

List of attempts that happened on this intent

​array | null

List of captures done on latest attempt

mandate_id
​string | null · maxLength: 255

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

Example: mandate_iwer89rnjef349dni3
​object

Passing this object during payments creates a mandate. The mandate_type sub object is passed by the server.

setup_future_usage
​string · enum

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.
Enum values:
off_session
on_session
off_session
​boolean | null

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. This parameter can only be used with confirm=true.

Example: true
capture_on
​string | null · date-time

A timestamp (ISO 8601 code) that determines when the payment should be captured. Providing this field will automatically set capture to true

Example: 2022-09-10T10:11:12Z
capture_method
​string · enum

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.
Enum values:
automatic
manual
manual_multiple
scheduled
sequential_automatic
​object
payment_token
​string | null

Provide a reference to a stored payment method

Example: 187282ab-40ef-47a9-9206-5099ba31e432
​object
​object
​array | null

Information about the product , quantity and amount for connectors. (e.g. Klarna)

Example: [{ "product_name": "gillete creme", "quantity": 15, "amount" : 900 }]
return_url
​string | null

The URL to redirect after the completion of the operation

Example: https://hyperswitch.io
authentication_type
​string · enum

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.

Enum values:
three_ds
no_three_ds
Default: three_ds
statement_descriptor_name
​string | null · maxLength: 255

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.

Example: Hyperswitch Router
statement_descriptor_suffix
​string | null · maxLength: 255

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.

Example: Payment for shoes purchase
​
cancellation_reason
​string | null

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

error_code
​string | null

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

Example: E0001
error_message
​string | null

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

Example: Failed while verifying the card
unified_code
​string | null

error code unified across the connectors is received here if there was an error while calling connector

unified_message
​string | null

error message unified across the connectors is received here if there was an error while calling connector

​object

Complete error details for V1 PaymentsResponse containing unified, issuer, and connector-level error information.

payment_experience
​string · enum

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

Enum values:
redirect_to_url
invoke_sdk_client
display_qr_code
one_click
link_wallet
invoke_payment_app
display_wait_screen
collect_otp
payment_method_type
​string · enum

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

Enum values:
ach
affirm
afterpay_clearpay
alfamart
ali_pay
ali_pay_hk
alma
amazon_pay
connector_label
​string | null

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

Example: stripe_US_food
business_country
​string · enum
Enum values:
AF
AX
AL
DZ
AS
AD
AO
AI
business_label
​string | null

The label identifying the specific business unit or profile under which this payment was processed by the merchant.

business_sub_label
​string | null

An optional sub-label for further categorization of the business unit or profile used for this payment.

allowed_payment_method_types
​array | null

Allowed Payment Method Types for a given PaymentIntent

Enum values:
ach
affirm
afterpay_clearpay
alfamart
ali_pay
ali_pay_hk
alma
amazon_pay
manual_retry_allowed
​boolean | null

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

connector_transaction_id
​string | null

A unique identifier for a payment provided by the connector

Example: 993672945374576J
​object

frm message is an object sent inside the payments response...when frm is invoked, its value is Some(...), else its None

metadata
​object | null

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.

​object

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

​
​object

additional data that might be required by hyperswitch

reference_id
​string | null

reference(Identifier) to the payment at connector side

Example: 993672945374576J
​object
profile_id
​string | null

The business profile that is associated with this payment

​object

Details of surcharge applied on this payment, if applicable

merchant_decision
​string | null

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_id
​string | null

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

incremental_authorization_allowed
​boolean | null

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

authorization_count
​integer | null · int32

Total number of authorizations happened in an incremental_authorization payment

​array | null

List of incremental authorizations happened to the payment

​object

Details of external authentication

external_3ds_authentication_attempted
​boolean | null

Flag indicating if external 3ds authentication is made or not

expires_on
​string | null · date-time

Date Time for expiry of the payment

Example: 2022-09-10T10:11:12Z
fingerprint
​string | null

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

​object

Browser information to be used for 3DS 2.0

​

Describes the channel through which the payment was initiated.

payment_method_id
​string | null

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_id
​string | null

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

payment_method_status
​string · enum

Payment Method Status

Enum values:
active
inactive
processing
awaiting_data
new
updated
​string | null · date-time

Date time at which payment was updated

Example: 2022-09-10T10:11:12Z
​

Charge Information

frm_metadata
​object | null

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_applied
​boolean | null

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

extended_authorization_last_applied_at
​string | null · date-time

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

Example: 2022-09-10T10:11:12Z
request_extended_authorization
​boolean | null

Optional boolean value to extent authorization period of this payment

capture method must be manual or manual_multiple

Default: false
capture_before
​string | null · date-time

date and time after which this payment cannot be captured

merchant_order_reference_id
​string | null · maxLength: 255

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.

Example: Custom_Order_id_123
order_tax_amount
​integer · int64

This Unit struct represents MinorUnit in which core amount works

connector_mandate_id
​string | null

Connector Identifier for the payment method

card_discovery
​string · enum

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

Enum values:
manual
saved_card
click_to_pay
force_3ds_challenge
​boolean | null

Indicates if 3ds challenge is forced

force_3ds_challenge_trigger
​boolean | null

Indicates if 3ds challenge is triggered

issuer_error_code
​string | null

Error code received from the issuer in case of failed payments

issuer_error_message
​string | null

Error message received from the issuer in case of failed payments

is_iframe_redirection_enabled
​boolean | null

Indicates if the redirection has to open in the iframe

whole_connector_response
​string | null

Contains whole connector response

enable_partial_authorization
​boolean | null

Allow partial authorization for this payment

Default: false
enable_overcapture
​boolean | null

Bool indicating if overcapture must be requested for this payment

is_overcapture_enabled
​boolean | null

Boolean indicating whether overcapture is effectively enabled for this payment

​object
is_stored_credential
​boolean | null

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

Example: true
mit_category
​string · enum

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.

Enum values:
installment
unscheduled
recurring
resubmission
​object

Billing Descriptor information to be sent to the payment gateway

tokenization
​string · enum

The type of tokenization to use for the payment method

Enum values:
skip_psp
tokenize_at_psp
​object

Information identifying partner and merchant application initiating the request

​object
​array | null

Installment payment options associated with this payment, grouped by payment method

​object

Installment selection made by the customer during payment confirmation.

​object

Statistics for a customer within a single profile

​object

The authorized fee snapshot aggregated across a payment's capture rows.

None on the containing response means that no merchant commission snapshot exists. A calculated zero remains Some(0).


Payments - Session token

POST
https://paysw-wiki.lab.next-on.pro/dev-router
/payments/session_tokens
api-key (header)

Creates a session object or a session token for wallets like Apple Pay, Google Pay, etc. These tokens are used by Hyperswitch's SDK to initiate these wallets' SDK.

Payments - Session token › Request Body

payment_id
​string · required

The identifier for the payment

wallets
​PaymentMethodType[] · required

The list of the supported wallets

Enum values:
ach
affirm
afterpay_clearpay
alfamart
ali_pay
ali_pay_hk
alma
amazon_pay
client_secret
​string | null

This is a token which expires after 15 minutes, used from the client to authenticate and create sessions from the SDK

​object

Merchant connector details used to make payments.

Payments - Session token › Responses

Payment session object created or session token was retrieved from wallets

payment_id
​string · required

The identifier for the payment

client_secret
​string · required

This is a token which expires after 15 minutes, used from the client to authenticate and create sessions from the SDK

​SessionToken[] · required

The list of session token object


Payments - Cancel

POST
https://paysw-wiki.lab.next-on.pro/dev-router
/payments/{payment_id}/cancel
api-key (header)

A Payment could can be cancelled when it is in one of these statuses: requires_payment_method, requires_capture, requires_confirmation, requires_customer_action.

Payments - Cancel › path Parameters

payment_id
​string · required

The identifier for payment

Payments - Cancel › Request Body

cancellation_reason
​string | null

The reason for the payment cancel

​object

Merchant connector details used to make payments.

all_keys_required
​boolean | null

If enabled, provides whole connector response

Payments - Cancel › Responses

Payment canceled

No data returned

Payments - Cancel Post Capture

POST
https://paysw-wiki.lab.next-on.pro/dev-router
/payments/{payment_id}/cancel_post_capture
api-key (header)

A Payment could can be cancelled when it is in one of these statuses: succeeded, partially_captured, partially_captured_and_capturable.

Payments - Cancel Post Capture › path Parameters

payment_id
​string · required

The identifier for payment

Payments - Cancel Post Capture › Request Body

Request to cancel a payment when the payment is already captured
cancellation_reason
​string | null

The reason for the payment cancel

Payments - Cancel Post Capture › Responses

Payment canceled post capture

payment_id
​string · minLength: 30 · maxLength: 30 · required

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

Example: pay_mbabizu24mvu3mela5njyhpit4
merchant_id
​string · maxLength: 255 · required

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

Example: merchant_1668273825
status
​string · enum · 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).

Enum values:
succeeded
failed
cancelled
cancelled_post_capture
processing
requires_customer_action
requires_merchant_action
requires_payment_method
Default: requires_confirmation
amount
​integer · int64 · 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.,

Example: 6540
net_amount
​integer · int64 · 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

Example: 6540
amount_capturable
​integer · int64 · min: 100 · 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.

Example: 6540
processor_merchant_id
​string · maxLength: 255 · 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.

Example: merchant_1689512302
currency
​Currency · enum · required

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

Enum values:
AED
AFN
ALL
AMD
ANG
AOA
ARS
AUD
payment_method
​PaymentMethod · enum · required

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

Enum values:
card
card_redirect
pay_later
wallet
bank_redirect
bank_transfer
crypto
bank_debit
attempt_count
​integer · int32 · required

Total number of attempts associated with this payment

shipping_cost
​integer | null · int64

The shipping cost for the payment.

Example: 6540
amount_received
​integer | null · int64

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.

Example: 6540
initiator
​string · enum

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

Enum values:
platform
connected
sdk_authorization
​string | null

Token containing encoded information for sdk authorization.

Example: cHJvZmlsZV9pZD1wcm9mXzEyMyxwdWJsaXNoYWJsZV9rZXk9cGtfbGl2ZV8xMjM=
connector
​string | null

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

Example: stripe
​object

Additional metadata for payment intent state containing refunded and disputed amounts

client_secret
​string | null

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.

Example: pay_U42c409qyHwOkWo3vK60_secret_el9ksDkiB8hi6j9N78yo
created
​string | null · date-time

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

Example: 2022-09-10T10:11:12Z
modified_at
​string | null · date-time

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

Example: 2022-09-10T10:11:12Z
​object

Details of customer attached to this payment

description
​string | null

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

Example: It's my first payment request
​array | null

An array of refund objects associated with this payment. Empty or null if no refunds have been processed.

​array | null

List of disputes that happened on this intent

​array | null

List of attempts that happened on this intent

​array | null

List of captures done on latest attempt

mandate_id
​string | null · maxLength: 255

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

Example: mandate_iwer89rnjef349dni3
​object

Passing this object during payments creates a mandate. The mandate_type sub object is passed by the server.

setup_future_usage
​string · enum

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.
Enum values:
off_session
on_session
off_session
​boolean | null

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. This parameter can only be used with confirm=true.

Example: true
capture_on
​string | null · date-time

A timestamp (ISO 8601 code) that determines when the payment should be captured. Providing this field will automatically set capture to true

Example: 2022-09-10T10:11:12Z
capture_method
​string · enum

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.
Enum values:
automatic
manual
manual_multiple
scheduled
sequential_automatic
​object
payment_token
​string | null

Provide a reference to a stored payment method

Example: 187282ab-40ef-47a9-9206-5099ba31e432
​object
​object
​array | null

Information about the product , quantity and amount for connectors. (e.g. Klarna)

Example: [{ "product_name": "gillete creme", "quantity": 15, "amount" : 900 }]
return_url
​string | null

The URL to redirect after the completion of the operation

Example: https://hyperswitch.io
authentication_type
​string · enum

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.

Enum values:
three_ds
no_three_ds
Default: three_ds
statement_descriptor_name
​string | null · maxLength: 255

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.

Example: Hyperswitch Router
statement_descriptor_suffix
​string | null · maxLength: 255

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.

Example: Payment for shoes purchase
​
cancellation_reason
​string | null

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

error_code
​string | null

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

Example: E0001
error_message
​string | null

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

Example: Failed while verifying the card
unified_code
​string | null

error code unified across the connectors is received here if there was an error while calling connector

unified_message
​string | null

error message unified across the connectors is received here if there was an error while calling connector

​object

Complete error details for V1 PaymentsResponse containing unified, issuer, and connector-level error information.

payment_experience
​string · enum

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

Enum values:
redirect_to_url
invoke_sdk_client
display_qr_code
one_click
link_wallet
invoke_payment_app
display_wait_screen
collect_otp
payment_method_type
​string · enum

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

Enum values:
ach
affirm
afterpay_clearpay
alfamart
ali_pay
ali_pay_hk
alma
amazon_pay
connector_label
​string | null

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

Example: stripe_US_food
business_country
​string · enum
Enum values:
AF
AX
AL
DZ
AS
AD
AO
AI
business_label
​string | null

The label identifying the specific business unit or profile under which this payment was processed by the merchant.

business_sub_label
​string | null

An optional sub-label for further categorization of the business unit or profile used for this payment.

allowed_payment_method_types
​array | null

Allowed Payment Method Types for a given PaymentIntent

Enum values:
ach
affirm
afterpay_clearpay
alfamart
ali_pay
ali_pay_hk
alma
amazon_pay
manual_retry_allowed
​boolean | null

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

connector_transaction_id
​string | null

A unique identifier for a payment provided by the connector

Example: 993672945374576J
​object

frm message is an object sent inside the payments response...when frm is invoked, its value is Some(...), else its None

metadata
​object | null

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.

​object

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

​
​object

additional data that might be required by hyperswitch

reference_id
​string | null

reference(Identifier) to the payment at connector side

Example: 993672945374576J
​object
profile_id
​string | null

The business profile that is associated with this payment

​object

Details of surcharge applied on this payment, if applicable

merchant_decision
​string | null

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_id
​string | null

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

incremental_authorization_allowed
​boolean | null

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

authorization_count
​integer | null · int32

Total number of authorizations happened in an incremental_authorization payment

​array | null

List of incremental authorizations happened to the payment

​object

Details of external authentication

external_3ds_authentication_attempted
​boolean | null

Flag indicating if external 3ds authentication is made or not

expires_on
​string | null · date-time

Date Time for expiry of the payment

Example: 2022-09-10T10:11:12Z
fingerprint
​string | null

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

​object

Browser information to be used for 3DS 2.0

​

Describes the channel through which the payment was initiated.

payment_method_id
​string | null

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_id
​string | null

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

payment_method_status
​string · enum

Payment Method Status

Enum values:
active
inactive
processing
awaiting_data
new
updated
​string | null · date-time

Date time at which payment was updated

Example: 2022-09-10T10:11:12Z
​

Charge Information

frm_metadata
​object | null

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_applied
​boolean | null

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

extended_authorization_last_applied_at
​string | null · date-time

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

Example: 2022-09-10T10:11:12Z
request_extended_authorization
​boolean | null

Optional boolean value to extent authorization period of this payment

capture method must be manual or manual_multiple

Default: false
capture_before
​string | null · date-time

date and time after which this payment cannot be captured

merchant_order_reference_id
​string | null · maxLength: 255

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.

Example: Custom_Order_id_123
order_tax_amount
​integer · int64

This Unit struct represents MinorUnit in which core amount works

connector_mandate_id
​string | null

Connector Identifier for the payment method

card_discovery
​string · enum

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

Enum values:
manual
saved_card
click_to_pay
force_3ds_challenge
​boolean | null

Indicates if 3ds challenge is forced

force_3ds_challenge_trigger
​boolean | null

Indicates if 3ds challenge is triggered

issuer_error_code
​string | null

Error code received from the issuer in case of failed payments

issuer_error_message
​string | null

Error message received from the issuer in case of failed payments

is_iframe_redirection_enabled
​boolean | null

Indicates if the redirection has to open in the iframe

whole_connector_response
​string | null

Contains whole connector response

enable_partial_authorization
​boolean | null

Allow partial authorization for this payment

Default: false
enable_overcapture
​boolean | null

Bool indicating if overcapture must be requested for this payment

is_overcapture_enabled
​boolean | null

Boolean indicating whether overcapture is effectively enabled for this payment

​object
is_stored_credential
​boolean | null

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

Example: true
mit_category
​string · enum

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.

Enum values:
installment
unscheduled
recurring
resubmission
​object

Billing Descriptor information to be sent to the payment gateway

tokenization
​string · enum

The type of tokenization to use for the payment method

Enum values:
skip_psp
tokenize_at_psp
​object

Information identifying partner and merchant application initiating the request

​object
​array | null

Installment payment options associated with this payment, grouped by payment method

​object

Installment selection made by the customer during payment confirmation.

​object

Statistics for a customer within a single profile

​object

The authorized fee snapshot aggregated across a payment's capture rows.

None on the containing response means that no merchant commission snapshot exists. A calculated zero remains Some(0).


Payments - Extended Authorization

POST
https://paysw-wiki.lab.next-on.pro/dev-router
/payments/{payment_id}/extend_authorization
api-key (header)

Extended authorization is available for payments currently in the requires_capture status Call this endpoint to increase the authorization validity period

Payments - Extended Authorization › path Parameters

payment_id
​string · required

The identifier for payment

Payments - Extended Authorization › Responses

Extended authorization for the payment

No data returned

Payments - List

GET
https://paysw-wiki.lab.next-on.pro/dev-router
/payments/list
api-key (header)

To list the payments

Payments - List › query Parameters

customer_id
​string | null

The identifier for the customer

starting_after
​string | null

A cursor for use in pagination, fetch the next list after some object

ending_before
​string | null

A cursor for use in pagination, fetch the previous list before some object

limit
​integer | null · int64

Limit on the number of objects to return

created
​string | null · date-time

The time at which payment is created

created_lt
​string | null · date-time

Time less than the payment created time

created_gt
​string | null · date-time

Time greater than the payment created time

created_lte
​string | null · date-time

Time less than or equals to the payment created time

created_gte
​string | null · date-time

Time greater than or equals to the payment created time

Payments - List › Responses

Successfully retrieved a payment list

size
​integer · min: 0 · required

The number of payments included in the list

​PaymentsResponse[] · required

Payments - List using filters

POST
https://paysw-wiki.lab.next-on.pro/dev-router
/payments/list
api-key (header)

Lists payments with optional column operators

Payments - List using filters › Request Body

The time range for which objects are needed. TimeRange has two fields start_time and end_time from which objects can be filtered as per required scenarios (created_at, time less than, greater than etc).
payment_id
​string | null

The identifier for payment

profile_id
​string | null

The identifier for business profile

customer_id
​string | null

The identifier for customer

limit
​integer · int32 · min: 0

The limit on the number of objects. The default limit is 10 and max limit is 20

offset
​integer | null · int32 · min: 0

The starting point within a list of objects

​object
connector
​array | null

The list of connectors to filter payments list

Enum values:
flexifai
fiftyfourpay
honeycoin
k218pay
bitex
hypergate
maguapay
payadmit
currency
​array | null

The list of currencies to filter payments list

Enum values:
AED
AFN
ALL
AMD
ANG
AOA
ARS
AUD
status
​array | null

The list of payment status to filter payments list

Enum values:
succeeded
failed
cancelled
cancelled_post_capture
processing
requires_customer_action
requires_merchant_action
requires_payment_method
payment_method
​array | null

The list of payment methods to filter payments list

Enum values:
card
card_redirect
pay_later
wallet
bank_redirect
bank_transfer
crypto
bank_debit
payment_method_type
​array | null

The list of payment method types to filter payments list

Enum values:
ach
affirm
afterpay_clearpay
alfamart
ali_pay
ali_pay_hk
alma
amazon_pay
authentication_type
​array | null

The list of authentication types to filter payments list

Enum values:
three_ds
no_three_ds
merchant_connector_id
​array | null

The list of merchant connector ids to filter payments list for selected label

​Order
card_network
​array | null

The List of all the card networks to filter payments list

Enum values:
Visa
Mastercard
AmericanExpress
JCB
DinersClub
Discover
CartesBancaires
UnionPay
merchant_order_reference_id
​string | null

The identifier for merchant order reference id

card_discovery
​array | null

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

Enum values:
manual
saved_card
click_to_pay
​object[]

Column predicates. Combined with other fields using AND.

Payments - List using filters › Responses

Payments filtered

count
​integer · min: 0 · required

The number of payments included in the list for given constraints

total_count
​integer · int64 · required

The total number of available payments for given constraints

​PaymentsResponse[] · required

The list of payments response objects


Payments - Incremental Authorization

POST
https://paysw-wiki.lab.next-on.pro/dev-router
/payments/{payment_id}/incremental_authorization
api-key (header)

Authorized amount for a payment can be incremented if it is in status: requires_capture

Payments - Incremental Authorization › path Parameters

payment_id
​string · required

The identifier for payment

Payments - Incremental Authorization › Request Body

amount
​integer · int64 · required

The total amount including previously authorized amount and additional amount

Example: 6540
reason
​string | null

Reason for incremental authorization

Payments - Incremental Authorization › Responses

Payment authorized amount incremented

payment_id
​string · minLength: 30 · maxLength: 30 · required

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

Example: pay_mbabizu24mvu3mela5njyhpit4
merchant_id
​string · maxLength: 255 · required

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

Example: merchant_1668273825
status
​string · enum · 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).

Enum values:
succeeded
failed
cancelled
cancelled_post_capture
processing
requires_customer_action
requires_merchant_action
requires_payment_method
Default: requires_confirmation
amount
​integer · int64 · 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.,

Example: 6540
net_amount
​integer · int64 · 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

Example: 6540
amount_capturable
​integer · int64 · min: 100 · 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.

Example: 6540
processor_merchant_id
​string · maxLength: 255 · 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.

Example: merchant_1689512302
currency
​Currency · enum · required

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

Enum values:
AED
AFN
ALL
AMD
ANG
AOA
ARS
AUD
payment_method
​PaymentMethod · enum · required

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

Enum values:
card
card_redirect
pay_later
wallet
bank_redirect
bank_transfer
crypto
bank_debit
attempt_count
​integer · int32 · required

Total number of attempts associated with this payment

shipping_cost
​integer | null · int64

The shipping cost for the payment.

Example: 6540
amount_received
​integer | null · int64

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.

Example: 6540
initiator
​string · enum

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

Enum values:
platform
connected
sdk_authorization
​string | null

Token containing encoded information for sdk authorization.

Example: cHJvZmlsZV9pZD1wcm9mXzEyMyxwdWJsaXNoYWJsZV9rZXk9cGtfbGl2ZV8xMjM=
connector
​string | null

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

Example: stripe
​object

Additional metadata for payment intent state containing refunded and disputed amounts

client_secret
​string | null

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.

Example: pay_U42c409qyHwOkWo3vK60_secret_el9ksDkiB8hi6j9N78yo
created
​string | null · date-time

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

Example: 2022-09-10T10:11:12Z
modified_at
​string | null · date-time

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

Example: 2022-09-10T10:11:12Z
​object

Details of customer attached to this payment

description
​string | null

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

Example: It's my first payment request
​array | null

An array of refund objects associated with this payment. Empty or null if no refunds have been processed.

​array | null

List of disputes that happened on this intent

​array | null

List of attempts that happened on this intent

​array | null

List of captures done on latest attempt

mandate_id
​string | null · maxLength: 255

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

Example: mandate_iwer89rnjef349dni3
​object

Passing this object during payments creates a mandate. The mandate_type sub object is passed by the server.

setup_future_usage
​string · enum

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.
Enum values:
off_session
on_session
off_session
​boolean | null

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. This parameter can only be used with confirm=true.

Example: true
capture_on
​string | null · date-time

A timestamp (ISO 8601 code) that determines when the payment should be captured. Providing this field will automatically set capture to true

Example: 2022-09-10T10:11:12Z
capture_method
​string · enum

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.
Enum values:
automatic
manual
manual_multiple
scheduled
sequential_automatic
​object
payment_token
​string | null

Provide a reference to a stored payment method

Example: 187282ab-40ef-47a9-9206-5099ba31e432
​object
​object
​array | null

Information about the product , quantity and amount for connectors. (e.g. Klarna)

Example: [{ "product_name": "gillete creme", "quantity": 15, "amount" : 900 }]
return_url
​string | null

The URL to redirect after the completion of the operation

Example: https://hyperswitch.io
authentication_type
​string · enum

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.

Enum values:
three_ds
no_three_ds
Default: three_ds
statement_descriptor_name
​string | null · maxLength: 255

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.

Example: Hyperswitch Router
statement_descriptor_suffix
​string | null · maxLength: 255

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.

Example: Payment for shoes purchase
​
cancellation_reason
​string | null

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

error_code
​string | null

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

Example: E0001
error_message
​string | null

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

Example: Failed while verifying the card
unified_code
​string | null

error code unified across the connectors is received here if there was an error while calling connector

unified_message
​string | null

error message unified across the connectors is received here if there was an error while calling connector

​object

Complete error details for V1 PaymentsResponse containing unified, issuer, and connector-level error information.

payment_experience
​string · enum

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

Enum values:
redirect_to_url
invoke_sdk_client
display_qr_code
one_click
link_wallet
invoke_payment_app
display_wait_screen
collect_otp
payment_method_type
​string · enum

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

Enum values:
ach
affirm
afterpay_clearpay
alfamart
ali_pay
ali_pay_hk
alma
amazon_pay
connector_label
​string | null

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

Example: stripe_US_food
business_country
​string · enum
Enum values:
AF
AX
AL
DZ
AS
AD
AO
AI
business_label
​string | null

The label identifying the specific business unit or profile under which this payment was processed by the merchant.

business_sub_label
​string | null

An optional sub-label for further categorization of the business unit or profile used for this payment.

allowed_payment_method_types
​array | null

Allowed Payment Method Types for a given PaymentIntent

Enum values:
ach
affirm
afterpay_clearpay
alfamart
ali_pay
ali_pay_hk
alma
amazon_pay
manual_retry_allowed
​boolean | null

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

connector_transaction_id
​string | null

A unique identifier for a payment provided by the connector

Example: 993672945374576J
​object

frm message is an object sent inside the payments response...when frm is invoked, its value is Some(...), else its None

metadata
​object | null

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.

​object

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

​
​object

additional data that might be required by hyperswitch

reference_id
​string | null

reference(Identifier) to the payment at connector side

Example: 993672945374576J
​object
profile_id
​string | null

The business profile that is associated with this payment

​object

Details of surcharge applied on this payment, if applicable

merchant_decision
​string | null

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_id
​string | null

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

incremental_authorization_allowed
​boolean | null

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

authorization_count
​integer | null · int32

Total number of authorizations happened in an incremental_authorization payment

​array | null

List of incremental authorizations happened to the payment

​object

Details of external authentication

external_3ds_authentication_attempted
​boolean | null

Flag indicating if external 3ds authentication is made or not

expires_on
​string | null · date-time

Date Time for expiry of the payment

Example: 2022-09-10T10:11:12Z
fingerprint
​string | null

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

​object

Browser information to be used for 3DS 2.0

​

Describes the channel through which the payment was initiated.

payment_method_id
​string | null

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_id
​string | null

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

payment_method_status
​string · enum

Payment Method Status

Enum values:
active
inactive
processing
awaiting_data
new
updated
​string | null · date-time

Date time at which payment was updated

Example: 2022-09-10T10:11:12Z
​

Charge Information

frm_metadata
​object | null

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_applied
​boolean | null

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

extended_authorization_last_applied_at
​string | null · date-time

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

Example: 2022-09-10T10:11:12Z
request_extended_authorization
​boolean | null

Optional boolean value to extent authorization period of this payment

capture method must be manual or manual_multiple

Default: false
capture_before
​string | null · date-time

date and time after which this payment cannot be captured

merchant_order_reference_id
​string | null · maxLength: 255

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.

Example: Custom_Order_id_123
order_tax_amount
​integer · int64

This Unit struct represents MinorUnit in which core amount works

connector_mandate_id
​string | null

Connector Identifier for the payment method

card_discovery
​string · enum

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

Enum values:
manual
saved_card
click_to_pay
force_3ds_challenge
​boolean | null

Indicates if 3ds challenge is forced

force_3ds_challenge_trigger
​boolean | null

Indicates if 3ds challenge is triggered

issuer_error_code
​string | null

Error code received from the issuer in case of failed payments

issuer_error_message
​string | null

Error message received from the issuer in case of failed payments

is_iframe_redirection_enabled
​boolean | null

Indicates if the redirection has to open in the iframe

whole_connector_response
​string | null

Contains whole connector response

enable_partial_authorization
​boolean | null

Allow partial authorization for this payment

Default: false
enable_overcapture
​boolean | null

Bool indicating if overcapture must be requested for this payment

is_overcapture_enabled
​boolean | null

Boolean indicating whether overcapture is effectively enabled for this payment

​object
is_stored_credential
​boolean | null

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

Example: true
mit_category
​string · enum

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.

Enum values:
installment
unscheduled
recurring
resubmission
​object

Billing Descriptor information to be sent to the payment gateway

tokenization
​string · enum

The type of tokenization to use for the payment method

Enum values:
skip_psp
tokenize_at_psp
​object

Information identifying partner and merchant application initiating the request

​object
​array | null

Installment payment options associated with this payment, grouped by payment method

​object

Installment selection made by the customer during payment confirmation.

​object

Statistics for a customer within a single profile

​object

The authorized fee snapshot aggregated across a payment's capture rows.

None on the containing response means that no merchant commission snapshot exists. A calculated zero remains Some(0).


GET
https://paysw-wiki.lab.next-on.pro/dev-router
/payment_link/{payment_link_id}
api-key (header)
or
api-key (header)

To retrieve the properties of a Payment Link. This may be used to get the status of a previously initiated payment or next action for an ongoing payment

payment_link_id
​string · required

The identifier for payment link

client_secret
​string | null

This is a token which expires after 15 minutes, used from the client to authenticate and create sessions from the SDK

Gets details regarding payment link

payment_link_id
​string · required

Identifier for Payment Link

merchant_id
​string · required

Identifier for Merchant

link_to_pay
​string · required

Open payment link (without any security checks and listing SPMs)

amount
​integer · int64 · required

The payment amount. Amount for the payment in the lowest denomination of the currency

Example: 6540
created_at
​string · date-time · required

Date and time of Payment Link creation

status
​PaymentLinkStatus · enum · required

Status Of the Payment Link

Enum values:
active
expired
expiry
​string | null · date-time

Date and time of Expiration for Payment Link

description
​string | null

Description for Payment Link

currency
​string · enum

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

Enum values:
AED
AFN
ALL
AMD
ANG
AOA
ARS
AUD
secure_link
​string | null

Secure payment link (with security checks and listing saved payment methods)


Payments - External 3DS Authentication

POST
https://paysw-wiki.lab.next-on.pro/dev-router
/payments/{payment_id}/3ds/authentication
api-key (header)

External 3DS Authentication is performed and returns the AuthenticationResponse

Payments - External 3DS Authentication › path Parameters

payment_id
​string · required

The identifier for payment

Payments - External 3DS Authentication › Request Body

device_channel
​DeviceChannel · enum · required

Device Channel indicating whether request is coming from App or Browser

Enum values:
APP
BRW
threeds_method_comp_ind
​ThreeDsCompletionIndicator · enum · required

Indicates if 3DS method data was successfully completed or not

Enum values:
Y
N
U
client_secret
​string | null

Client Secret

​object

SDK Information if request is from SDK

Payments - External 3DS Authentication › Responses

Authentication created

trans_status
​TransactionStatus · enum · required

Indicates the transaction status

Enum values:
Y
N
U
A
R
C
D
I
three_ds_requestor_url
​string · required

Three DS Requestor URL

acs_url
​string | null

Access Server URL to be used for challenge submission

challenge_request
​string | null

Challenge request which should be sent to acs_url

challenge_request_key
​string | null

Challenge request key which should be set as form field name for creq

acs_reference_number
​string | null

Unique identifier assigned by the EMVCo(Europay, Mastercard and Visa)

acs_trans_id
​string | null

Unique identifier assigned by the ACS to identify a single transaction

three_dsserver_trans_id
​string | null

Unique identifier assigned by the 3DS Server to identify a single transaction

acs_signed_content
​string | null

Contains the JWS object created by the ACS for the ARes(Authentication Response) message

three_ds_requestor_app_url
​string | null

Merchant app declaring their URL within the CReq message so that the Authentication app can call the Merchant app after OOB authentication has occurred

error_message
​string | null

Error message if any


Payments - Complete Authorize

POST
https://paysw-wiki.lab.next-on.pro/dev-router
/payments/{payment_id}/complete_authorize
api-key (header)

Payments - Complete Authorize › path Parameters

payment_id
​string · required

The identifier for payment

Payments - Complete Authorize › Request Body

​object
client_secret
​string | null

Client Secret

threeds_method_comp_ind
​string · enum

Indicates if 3DS method data was successfully completed or not

Enum values:
Y
N
U

Payments - Complete Authorize › Responses

Payments Complete Authorize Success

payment_id
​string · minLength: 30 · maxLength: 30 · required

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

Example: pay_mbabizu24mvu3mela5njyhpit4
merchant_id
​string · maxLength: 255 · required

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

Example: merchant_1668273825
status
​string · enum · 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).

Enum values:
succeeded
failed
cancelled
cancelled_post_capture
processing
requires_customer_action
requires_merchant_action
requires_payment_method
Default: requires_confirmation
amount
​integer · int64 · 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.,

Example: 6540
net_amount
​integer · int64 · 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

Example: 6540
amount_capturable
​integer · int64 · min: 100 · 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.

Example: 6540
processor_merchant_id
​string · maxLength: 255 · 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.

Example: merchant_1689512302
currency
​Currency · enum · required

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

Enum values:
AED
AFN
ALL
AMD
ANG
AOA
ARS
AUD
payment_method
​PaymentMethod · enum · required

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

Enum values:
card
card_redirect
pay_later
wallet
bank_redirect
bank_transfer
crypto
bank_debit
attempt_count
​integer · int32 · required

Total number of attempts associated with this payment

shipping_cost
​integer | null · int64

The shipping cost for the payment.

Example: 6540
amount_received
​integer | null · int64

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.

Example: 6540
initiator
​string · enum

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

Enum values:
platform
connected
sdk_authorization
​string | null

Token containing encoded information for sdk authorization.

Example: cHJvZmlsZV9pZD1wcm9mXzEyMyxwdWJsaXNoYWJsZV9rZXk9cGtfbGl2ZV8xMjM=
connector
​string | null

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

Example: stripe
​object

Additional metadata for payment intent state containing refunded and disputed amounts

client_secret
​string | null

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.

Example: pay_U42c409qyHwOkWo3vK60_secret_el9ksDkiB8hi6j9N78yo
created
​string | null · date-time

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

Example: 2022-09-10T10:11:12Z
modified_at
​string | null · date-time

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

Example: 2022-09-10T10:11:12Z
​object

Details of customer attached to this payment

description
​string | null

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

Example: It's my first payment request
​array | null

An array of refund objects associated with this payment. Empty or null if no refunds have been processed.

​array | null

List of disputes that happened on this intent

​array | null

List of attempts that happened on this intent

​array | null

List of captures done on latest attempt

mandate_id
​string | null · maxLength: 255

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

Example: mandate_iwer89rnjef349dni3
​object

Passing this object during payments creates a mandate. The mandate_type sub object is passed by the server.

setup_future_usage
​string · enum

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.
Enum values:
off_session
on_session
off_session
​boolean | null

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. This parameter can only be used with confirm=true.

Example: true
capture_on
​string | null · date-time

A timestamp (ISO 8601 code) that determines when the payment should be captured. Providing this field will automatically set capture to true

Example: 2022-09-10T10:11:12Z
capture_method
​string · enum

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.
Enum values:
automatic
manual
manual_multiple
scheduled
sequential_automatic
​object
payment_token
​string | null

Provide a reference to a stored payment method

Example: 187282ab-40ef-47a9-9206-5099ba31e432
​object
​object
​array | null

Information about the product , quantity and amount for connectors. (e.g. Klarna)

Example: [{ "product_name": "gillete creme", "quantity": 15, "amount" : 900 }]
return_url
​string | null

The URL to redirect after the completion of the operation

Example: https://hyperswitch.io
authentication_type
​string · enum

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.

Enum values:
three_ds
no_three_ds
Default: three_ds
statement_descriptor_name
​string | null · maxLength: 255

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.

Example: Hyperswitch Router
statement_descriptor_suffix
​string | null · maxLength: 255

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.

Example: Payment for shoes purchase
​
cancellation_reason
​string | null

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

error_code
​string | null

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

Example: E0001
error_message
​string | null

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

Example: Failed while verifying the card
unified_code
​string | null

error code unified across the connectors is received here if there was an error while calling connector

unified_message
​string | null

error message unified across the connectors is received here if there was an error while calling connector

​object

Complete error details for V1 PaymentsResponse containing unified, issuer, and connector-level error information.

payment_experience
​string · enum

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

Enum values:
redirect_to_url
invoke_sdk_client
display_qr_code
one_click
link_wallet
invoke_payment_app
display_wait_screen
collect_otp
payment_method_type
​string · enum

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

Enum values:
ach
affirm
afterpay_clearpay
alfamart
ali_pay
ali_pay_hk
alma
amazon_pay
connector_label
​string | null

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

Example: stripe_US_food
business_country
​string · enum
Enum values:
AF
AX
AL
DZ
AS
AD
AO
AI
business_label
​string | null

The label identifying the specific business unit or profile under which this payment was processed by the merchant.

business_sub_label
​string | null

An optional sub-label for further categorization of the business unit or profile used for this payment.

allowed_payment_method_types
​array | null

Allowed Payment Method Types for a given PaymentIntent

Enum values:
ach
affirm
afterpay_clearpay
alfamart
ali_pay
ali_pay_hk
alma
amazon_pay
manual_retry_allowed
​boolean | null

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

connector_transaction_id
​string | null

A unique identifier for a payment provided by the connector

Example: 993672945374576J
​object

frm message is an object sent inside the payments response...when frm is invoked, its value is Some(...), else its None

metadata
​object | null

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.

​object

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

​
​object

additional data that might be required by hyperswitch

reference_id
​string | null

reference(Identifier) to the payment at connector side

Example: 993672945374576J
​object
profile_id
​string | null

The business profile that is associated with this payment

​object

Details of surcharge applied on this payment, if applicable

merchant_decision
​string | null

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_id
​string | null

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

incremental_authorization_allowed
​boolean | null

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

authorization_count
​integer | null · int32

Total number of authorizations happened in an incremental_authorization payment

​array | null

List of incremental authorizations happened to the payment

​object

Details of external authentication

external_3ds_authentication_attempted
​boolean | null

Flag indicating if external 3ds authentication is made or not

expires_on
​string | null · date-time

Date Time for expiry of the payment

Example: 2022-09-10T10:11:12Z
fingerprint
​string | null

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

​object

Browser information to be used for 3DS 2.0

​

Describes the channel through which the payment was initiated.

payment_method_id
​string | null

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_id
​string | null

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

payment_method_status
​string · enum

Payment Method Status

Enum values:
active
inactive
processing
awaiting_data
new
updated
​string | null · date-time

Date time at which payment was updated

Example: 2022-09-10T10:11:12Z
​

Charge Information

frm_metadata
​object | null

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_applied
​boolean | null

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

extended_authorization_last_applied_at
​string | null · date-time

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

Example: 2022-09-10T10:11:12Z
request_extended_authorization
​boolean | null

Optional boolean value to extent authorization period of this payment

capture method must be manual or manual_multiple

Default: false
capture_before
​string | null · date-time

date and time after which this payment cannot be captured

merchant_order_reference_id
​string | null · maxLength: 255

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.

Example: Custom_Order_id_123
order_tax_amount
​integer · int64

This Unit struct represents MinorUnit in which core amount works

connector_mandate_id
​string | null

Connector Identifier for the payment method

card_discovery
​string · enum

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

Enum values:
manual
saved_card
click_to_pay
force_3ds_challenge
​boolean | null

Indicates if 3ds challenge is forced

force_3ds_challenge_trigger
​boolean | null

Indicates if 3ds challenge is triggered

issuer_error_code
​string | null

Error code received from the issuer in case of failed payments

issuer_error_message
​string | null

Error message received from the issuer in case of failed payments

is_iframe_redirection_enabled
​boolean | null

Indicates if the redirection has to open in the iframe

whole_connector_response
​string | null

Contains whole connector response

enable_partial_authorization
​boolean | null

Allow partial authorization for this payment

Default: false
enable_overcapture
​boolean | null

Bool indicating if overcapture must be requested for this payment

is_overcapture_enabled
​boolean | null

Boolean indicating whether overcapture is effectively enabled for this payment

​object
is_stored_credential
​boolean | null

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

Example: true
mit_category
​string · enum

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.

Enum values:
installment
unscheduled
recurring
resubmission
​object

Billing Descriptor information to be sent to the payment gateway

tokenization
​string · enum

The type of tokenization to use for the payment method

Enum values:
skip_psp
tokenize_at_psp
​object

Information identifying partner and merchant application initiating the request

​object
​array | null

Installment payment options associated with this payment, grouped by payment method

​object

Installment selection made by the customer during payment confirmation.

​object

Statistics for a customer within a single profile

​object

The authorized fee snapshot aggregated across a payment's capture rows.

None on the containing response means that no merchant commission snapshot exists. A calculated zero remains Some(0).


Payments - Post Session Tokens

POST
https://paysw-wiki.lab.next-on.pro/dev-router
/payments/{payment_id}/post_session_tokens
api-key (header)

Payments - Post Session Tokens › path Parameters

payment_id
​string · required

The identifier for payment

Payments - Post Session Tokens › Request Body

payment_method_type
​PaymentMethodType · enum · required

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

Enum values:
ach
affirm
afterpay_clearpay
alfamart
ali_pay
ali_pay_hk
alma
amazon_pay
payment_method
​PaymentMethod · enum · required

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

Enum values:
card
card_redirect
pay_later
wallet
bank_redirect
bank_transfer
crypto
bank_debit
client_secret
​string | null

It's a token used for client side verification.

Payments - Post Session Tokens › Responses

Post Session Token is done

payment_id
​string · required

The identifier for the payment

status
​string · enum · 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).

Enum values:
succeeded
failed
cancelled
cancelled_post_capture
processing
requires_customer_action
requires_merchant_action
requires_payment_method
Default: requires_confirmation
​

Payments - Update Metadata

POST
https://paysw-wiki.lab.next-on.pro/dev-router
/payments/{payment_id}/update_metadata
api-key (header)

Payments - Update Metadata › path Parameters

payment_id
​string · required

The identifier for payment

Payments - Update Metadata › Request Body

metadata
​object · required

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

​object

additional data that might be required by hyperswitch

Payments - Update Metadata › Responses

Metadata updated successfully

payment_id
​string · required

The identifier for the payment

status
​string · enum · 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).

Enum values:
succeeded
failed
cancelled
cancelled_post_capture
processing
requires_customer_action
requires_merchant_action
requires_payment_method
Default: requires_confirmation
metadata
​object | null

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

​object

additional data that might be required by hyperswitch


Payments - Submit Eligibility Data

POST
https://paysw-wiki.lab.next-on.pro/dev-router
/payments/{payment_id}/eligibility
api-key (header)

Payments - Submit Eligibility Data › path Parameters

payment_id
​string · required

The identifier for payment

Payments - Submit Eligibility Data › Request Body

client_secret
​string · required

Token used for client side verification

Example: pay_U42c409qyHwOkWo3vK60_secret_el9ksDkiB8hi6j9N78yo
payment_method_type
​PaymentMethod · enum · required

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

Enum values:
card
card_redirect
pay_later
wallet
bank_redirect
bank_transfer
crypto
bank_debit
​EligibilityPaymentMethodDataRequest · required

Payment method data request for eligibility check

payment_method_subtype
​string · enum

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

Enum values:
ach
affirm
afterpay_clearpay
alfamart
ali_pay
ali_pay_hk
alma
amazon_pay
​object

Browser information to be used for 3DS 2.0

Payments - Submit Eligibility Data › Responses

Eligibility submit is successful

payment_id
​string · required

The identifier for the payment

​SdkNextAction · required