POST
Payments - Confirm

Authorizations

​
api-key
string
header
required

Use the API key created under your merchant account from the HyperSwitch dashboard. API key is used to authenticate API requests from your merchant server only. Don't expose this key on a website or embed it in a mobile application.

Headers

​
X-Connected-Merchant-Id
string | null

Merchant ID of the connected merchant on whose behalf the operation is performed. Required when authenticating with a platform merchant's API key. Standard and connected merchants must not send it.

Path Parameters

​
payment_id
string
required

The identifier for payment

Body

application/json
​
amount
integer<int64> | null

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.

Required range: x >= 0
Example:

6540

​
order_tax_amount
integer<int64> | null

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

Example:

6540

​
currency
enum<string> | null

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

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

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<int64> | null

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

Example:

6540

​
payment_id
string | null

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.

Required string length: 30
Example:

"pay_mbabizu24mvu3mela5njyhpit4"

​
routing
Single · object
​
connector
enum<string>[] | null

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

Available options:
absa_sanlam,
authipay,
adyenplatform,
stripe_billing_test,
phonypay,
fauxpay,
pretendpay,
stripe_test,
adyen_test,
checkout_test,
paypal_test,
aci,
adyen,
affirm,
airwallex,
amazonpay,
archipel,
authorizedotnet,
bambora,
bamboraapac,
bankofamerica,
barclaycard,
billwerk,
bitpay,
bluesnap,
blackhawknetwork,
calida,
boku,
braintree,
breadpay,
cardinal,
cashtocode,
celero,
chargebee,
checkbook,
checkout,
citigate,
coinbase,
coingate,
custombilling,
cryptopay,
ctp_mastercard,
ctp_visa,
cybersource,
cybersourcedecisionmanager,
d24,
datatrans,
deutschebank,
digitalvirgo,
dlocal,
dwolla,
ebanx,
envoy,
elavon,
etisalat,
elavon_pg,
facilitapay,
finix,
fiserv,
fiservemea,
fiservcommercehub,
fiuu,
flexiti,
forte,
getnet,
gigadat,
givepayments,
globalpay,
globalpayments_heartland,
globepay,
gocardless,
gotyme_sanlam,
gpayments,
hipay,
helcim,
hyperpg,
hyperswitch_vault,
interpayments,
inespay,
iatapay,
ilixium,
imerchantsolutions,
itaubank,
jpmorgan,
jpmorgan_orbital,
juspay,
juspaythreedsserver,
klarna,
loonio,
merchante,
mifinity,
mollie,
moneris,
multisafepay,
netcetera,
nexinets,
nexixpay,
nmi,
nomupay,
noon,
nordea,
novalnet,
nuvei,
opennode,
paybox,
paydotcom,
payload,
payme,
paynearme,
payone,
paypal,
paysafe,
paystack,
paytm,
payconex,
payu,
peachpayments,
payjustnow,
payjustnowinstore,
phonepe,
placetopay,
powertranz,
prophetpay,
rapyd,
razorpay,
recurly,
redsys,
revolv3,
saferpay,
santander,
shift4,
silverflow,
square,
stax,
stripe,
stripebilling,
taxjar,
threedsecureio,
tesouro,
tokenex,
tokenio,
trustly,
truelayer,
trustpay,
trustpayments,
tsys,
tsys_transit,
vgs,
volt,
wellsfargo,
wise,
worldline,
worldpay,
worldpayraft,
worldpayvantiv,
worldpayxml,
worldpaymodular,
signifyd,
nsure,
plaid,
riskified,
sanlam_payshield,
xendit,
zen,
zift,
zsl
Example:
​
capture_method
enum<string> | null

Specifies how the payment is captured.

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

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

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

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

Available options:
three_ds,
no_three_ds
​
billing
object | null
​
confirm
boolean | null
default:false

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

​
customer
object | null

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

​
customer_id
string | null
deprecated

The identifier for the customer

Required string length: 1 - 64
Example:

"cus_y3oqhf46pyzuxjbcn2giaqnb44"

​
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

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

Maximum string length: 2048
Example:

"https://hyperswitch.io"

​
setup_future_usage
enum<string> | null

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

  • off_session: The payment method can be used for future payments when the customer is not present.
  • on_session: The payment method is intended for use only when the customer is present during checkout. If omitted, defaults to on_session.
Available options:
off_session,
on_session
​
payment_method_data
Card · object

The payment method information provided for making a payment

​
payment_method
enum<string> | null

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

Available options:
card,
card_redirect,
pay_later,
wallet,
bank_redirect,
bank_transfer,
crypto,
bank_debit,
reward,
real_time_payment,
upi,
voucher,
gift_card,
open_banking,
mobile_payment,
network_token
​
payment_token
string | null

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"

​
shipping
object | null
​
statement_descriptor_name
string | null
deprecated

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

Maximum string length: 255
Example:

"Hyperswitch Router"

​
statement_descriptor_suffix
string | null
deprecated

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

Maximum string length: 255
Example:

"Payment for shoes purchase"

​
order_details
object[] | null

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

Example:

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

​
client_secret
string | null

It's a token used for client side verification.

Example:

"pay_U42c409qyHwOkWo3vK60_secret_el9ksDkiB8hi6j9N78yo"

​
mandate_data
object | null
deprecated

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

​
customer_acceptance
object | null

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
deprecated

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

Maximum string length: 64
Example:

"mandate_iwer89rnjef349dni3"

​
browser_info
object | null

Browser information to be used for 3DS 2.0

​
payment_experience
enum<string> | null

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

Available options:
redirect_to_url,
invoke_sdk_client,
display_qr_code,
one_click,
link_wallet,
invoke_payment_app,
display_wait_screen,
collect_otp
​
payment_method_type
enum<string> | null

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

Available options:
ach,
affirm,
afterpay_clearpay,
alfamart,
ali_pay,
ali_pay_hk,
alma,
amazon_pay,
paysera,
apple_pay,
atome,
bacs,
bancontact_card,
becs,
benefit,
bizum,
blik,
bluecode,
boleto,
bca_bank_transfer,
bni_va,
breadpay,
bri_va,
bhn_card_network,
card_redirect,
cimb_va,
classic,
credit,
crypto_currency,
cashapp,
dana,
danamon_va,
debit,
duit_now,
efecty,
eft,
eft_debit_order,
eps,
flexiti,
fps,
evoucher,
giropay,
givex,
google_pay,
go_pay,
gcash,
ideal,
interac,
indomaret,
klarna,
kakao_pay,
local_bank_redirect,
mandiri_va,
knet,
mb_way,
mobile_pay,
momo,
momo_atm,
multibanco,
neteller,
online_banking_thailand,
online_banking_czech_republic,
online_banking_finland,
online_banking_fpx,
online_banking_poland,
online_banking_slovakia,
oxxo,
pago_efectivo,
permata_bank_transfer,
open_banking_uk,
pay_bright,
payjustnow,
paypal,
paze,
pix,
pix_key,
pix_emv,
pix_qr,
pix_automatico_qr,
pix_automatico_push,
pay_safe_card,
przelewy24,
prompt_pay,
pse,
qris,
red_compra,
red_pagos,
samsung_pay,
sepa,
sepa_bank_transfer,
sepa_guarenteed_debit,
skrill,
sofort,
swish,
touch_n_go,
trustly,
twint,
upi_collect,
upi_intent,
upi_qr,
vipps,
viet_qr,
venmo,
walley,
we_chat_pay,
seven_eleven,
lawson,
mini_stop,
family_mart,
seicomart,
pay_easy,
local_bank_transfer,
mifinity,
open_banking_pis,
direct_carrier_billing,
instant_bank_transfer,
instant_bank_transfer_finland,
instant_bank_transfer_poland,
revolut_pay,
indonesian_bank_transfer,
open_banking,
network_token,
payshap,
payshap_proxy
​
merchant_connector_details
object | null

Merchant connector details used to make payments.

​
allowed_payment_method_types
enum<string>[] | null

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

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

Available options:
ach,
affirm,
afterpay_clearpay,
alfamart,
ali_pay,
ali_pay_hk,
alma,
amazon_pay,
paysera,
apple_pay,
atome,
bacs,
bancontact_card,
becs,
benefit,
bizum,
blik,
bluecode,
boleto,
bca_bank_transfer,
bni_va,
breadpay,
bri_va,
bhn_card_network,
card_redirect,
cimb_va,
classic,
credit,
crypto_currency,
cashapp,
dana,
danamon_va,
debit,
duit_now,
efecty,
eft,
eft_debit_order,
eps,
flexiti,
fps,
evoucher,
giropay,
givex,
google_pay,
go_pay,
gcash,
ideal,
interac,
indomaret,
klarna,
kakao_pay,
local_bank_redirect,
mandiri_va,
knet,
mb_way,
mobile_pay,
momo,
momo_atm,
multibanco,
neteller,
online_banking_thailand,
online_banking_czech_republic,
online_banking_finland,
online_banking_fpx,
online_banking_poland,
online_banking_slovakia,
oxxo,
pago_efectivo,
permata_bank_transfer,
open_banking_uk,
pay_bright,
payjustnow,
paypal,
paze,
pix,
pix_key,
pix_emv,
pix_qr,
pix_automatico_qr,
pix_automatico_push,
pay_safe_card,
przelewy24,
prompt_pay,
pse,
qris,
red_compra,
red_pagos,
samsung_pay,
sepa,
sepa_bank_transfer,
sepa_guarenteed_debit,
skrill,
sofort,
swish,
touch_n_go,
trustly,
twint,
upi_collect,
upi_intent,
upi_qr,
vipps,
viet_qr,
venmo,
walley,
we_chat_pay,
seven_eleven,
lawson,
mini_stop,
family_mart,
seicomart,
pay_easy,
local_bank_transfer,
mifinity,
open_banking_pis,
direct_carrier_billing,
instant_bank_transfer,
instant_bank_transfer_finland,
instant_bank_transfer_poland,
revolut_pay,
indonesian_bank_transfer,
open_banking,
network_token,
payshap,
payshap_proxy
​
retry_action
enum<string> | null

Denotes the retry action

Available options:
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.

​
connector_metadata
object | null

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
default:false

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

Example:

true

​
payment_link_config
object | null

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

​
offer_details
object | null

Offer selection sent in a confirm request to apply an offer.

​
payment_type
enum<string> | null

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

Available options:
normal,
new_mandate,
setup_mandate,
recurring_mandate,
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<int32> | null

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

Required range: x >= 0
Example:

900

​
frm_metadata
object | null

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

​
request_external_three_ds_authentication
boolean | null

Whether to perform external authentication (if applicable)

Example:

true

​
three_ds_data
object | null
​
recurring_details
object

Details required for recurring payment

​
split_payments
object

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

​
request_extended_authorization
boolean | null
default:false

Optional boolean value to extent authorization period of this payment

capture method must be manual or manual_multiple

​
merchant_order_reference_id
string | null

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.

Maximum string length: 255
Example:

"Custom_Order_id_123"

​
skip_external_tax_calculation
boolean | null

Whether to calculate tax for this payment intent

​
psd2_sca_exemption_type
enum<string> | null

SCA Exemptions types available for authentication

Available options:
low_value,
transaction_risk_analysis
​
ctp_service_details
object | null
​
force_3ds_challenge
boolean | null

Indicates if 3ds challenge is forced

​
threeds_method_comp_ind
enum<string> | null

Indicates if 3DS method data was successfully completed or not

Available options:
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

​
payment_channel

Describes the channel through which the payment was initiated.

Available options:
ecommerce
​
tax_status
enum<string> | null
Available options:
taxable,
exempt
​
discount_amount
integer<int64> | null

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

Example:

6540

​
shipping_amount_tax
integer<int64> | null

This Unit struct represents MinorUnit in which core amount works

​
duty_amount
integer<int64> | null

This Unit struct represents MinorUnit in which core amount works

​
order_date
string<date-time> | null

Date the payer placed the order.

​
enable_partial_authorization
boolean | null
default:false

Allow partial authorization for this payment

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

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.

Available options:
installment,
unscheduled,
recurring,
resubmission
​
billing_descriptor
object | null

Billing Descriptor information to be sent to the payment gateway

​
tokenization
enum<string> | null

The type of tokenization to use for the payment method

Available options:
skip_psp,
tokenize_at_psp
​
partner_merchant_identifier_details
object | null

Information identifying partner and merchant application initiating the request

​
installment_options
object[] | null

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

​
installment_data
object | null

Installment selection sent by the customer during payment confirmation.

​
profile_acquirer_id
string | null

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

​
external_surcharge_strategy
enum<string> | null

Strategy for applying external surcharge

Available options:
apply,
waive

Response

Payment confirmed

​
payment_id
string
required

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

Required string length: 30
Example:

"pay_mbabizu24mvu3mela5njyhpit4"

​
merchant_id
string
required

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

Maximum string length: 255
Example:

"merchant_1668273825"

​
status
enum<string>
default:requires_confirmation
required

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

Available options:
succeeded,
failed,
cancelled,
cancelled_post_capture,
processing,
requires_customer_action,
requires_merchant_action,
requires_payment_method,
requires_confirmation,
requires_capture,
partially_captured,
partially_captured_and_capturable,
partially_authorized_and_requires_capture,
partially_captured_and_processing,
conflicted,
expired,
review
​
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>
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.

Required range: x >= 100
Example:

6540

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

Maximum string length: 255
Example:

"merchant_1689512302"

​
currency
enum<string>
required

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

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

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

Available options:
card,
card_redirect,
pay_later,
wallet,
bank_redirect,
bank_transfer,
crypto,
bank_debit,
reward,
real_time_payment,
upi,
voucher,
gift_card,
open_banking,
mobile_payment,
network_token
​
attempt_count
integer<int32>
required

Total number of attempts associated with this payment

​
shipping_cost
integer<int64> | null

The shipping cost for the payment.

Example:

6540

​
amount_received
integer<int64> | null

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

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

Available options:
platform,
connected
​
sdk_authorization
string | null

Token containing encoded information for sdk authorization.

Example:

"cHJvZmlsZV9pZD1wcm9mXzEyMyxwdWJsaXNoYWJsZV9rZXk9cGtfbGl2ZV8xMjM="

​
payment_method_list
object

The combined payment-method list, or the error that prevented it being built.

Serialized untagged: a success is the listing object itself, a failure is { "error": {...} }. Gated on errors as well as v1: it holds [crate::errors::types::ErrorResponse], which lives behind that feature because it pulls in reqwest. euclid_wasm builds api_models/v1 without errors, and cannot take actix-web in via that feature on a wasm target, so the section types simply do not exist there.

​
session_tokens
object

Wallet session tokens, or the error that prevented them being minted.

Serialized untagged: a success is the whole PaymentsSessionResponse object, a failure is { "error": {...} }. Gated on errors as well as v1 — see [crate::payment_methods::PaymentMethodListResult].

​
connector
string | null

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

Example:

"stripe"

​
state_metadata
object | null

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<date-time> | null

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

Example:

"2022-09-10T10:11:12Z"

​
modified_at
string<date-time> | null

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

Example:

"2022-09-10T10:11:12Z"

​
connector_customer_id
string | null

A unique identifier for a customer provided by the connector.

Example:

"cus_Rnm2pDKGyQi506"

​
customer_id
string | null
deprecated

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

Required string length: 1 - 64
Example:

"cus_y3oqhf46pyzuxjbcn2giaqnb44"

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

​
refunds
object[] | null

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

​
disputes
object[] | null

List of disputes that happened on this intent

​
attempts
object[] | null

List of attempts that happened on this intent

​
captures
object[] | null

List of captures done on latest attempt

​
mandate_id
string | null
deprecated

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

Maximum string length: 255
Example:

"mandate_iwer89rnjef349dni3"

​
mandate_data
object | null
deprecated

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

​
setup_future_usage
enum<string> | null

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

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

Specifies how the payment is captured.

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

Provide a reference to a stored payment method

Example:

"187282ab-40ef-47a9-9206-5099ba31e432"

​
shipping
object | null
​
billing
object | null
​
order_details
object[] | null

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

Example:

"[{\n \"product_name\": \"gillete creme\",\n \"quantity\": 15,\n \"amount\" : 900\n }]"

​
email
string | null
deprecated

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

Maximum string length: 255
Example:

"johntest@test.com"

​
name
string | null
deprecated

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

Maximum string length: 255
Example:

"John Test"

​
phone
string | null
deprecated

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

Maximum string length: 255
Example:

"9123456789"

​
return_url
string | null

The URL to redirect after the completion of the operation

Example:

"https://hyperswitch.io"

​
authentication_type
enum<string> | null
default:three_ds

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

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

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

Available options:
three_ds,
no_three_ds
​
statement_descriptor_name
string | null
deprecated

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

Maximum string length: 255
Example:

"Hyperswitch Router"

​
statement_descriptor_suffix
string | null
deprecated

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

Maximum string length: 255
Example:

"Payment for shoes purchase"

​
next_action
object

Contains the url for redirection flow

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

​
error_details
object | null

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

​
payment_experience
enum<string> | null

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

Available options:
redirect_to_url,
invoke_sdk_client,
display_qr_code,
one_click,
link_wallet,
invoke_payment_app,
display_wait_screen,
collect_otp
​
payment_method_type
enum<string> | null

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

Available options:
ach,
affirm,
afterpay_clearpay,
alfamart,
ali_pay,
ali_pay_hk,
alma,
amazon_pay,
paysera,
apple_pay,
atome,
bacs,
bancontact_card,
becs,
benefit,
bizum,
blik,
bluecode,
boleto,
bca_bank_transfer,
bni_va,
breadpay,
bri_va,
bhn_card_network,
card_redirect,
cimb_va,
classic,
credit,
crypto_currency,
cashapp,
dana,
danamon_va,
debit,
duit_now,
efecty,
eft,
eft_debit_order,
eps,
flexiti,
fps,
evoucher,
giropay,
givex,
google_pay,
go_pay,
gcash,
ideal,
interac,
indomaret,
klarna,
kakao_pay,
local_bank_redirect,
mandiri_va,
knet,
mb_way,
mobile_pay,
momo,
momo_atm,
multibanco,
neteller,
online_banking_thailand,
online_banking_czech_republic,
online_banking_finland,
online_banking_fpx,
online_banking_poland,
online_banking_slovakia,
oxxo,
pago_efectivo,
permata_bank_transfer,
open_banking_uk,
pay_bright,
payjustnow,
paypal,
paze,
pix,
pix_key,
pix_emv,
pix_qr,
pix_automatico_qr,
pix_automatico_push,
pay_safe_card,
przelewy24,
prompt_pay,
pse,
qris,
red_compra,
red_pagos,
samsung_pay,
sepa,
sepa_bank_transfer,
sepa_guarenteed_debit,
skrill,
sofort,
swish,
touch_n_go,
trustly,
twint,
upi_collect,
upi_intent,
upi_qr,
vipps,
viet_qr,
venmo,
walley,
we_chat_pay,
seven_eleven,
lawson,
mini_stop,
family_mart,
seicomart,
pay_easy,
local_bank_transfer,
mifinity,
open_banking_pis,
direct_carrier_billing,
instant_bank_transfer,
instant_bank_transfer_finland,
instant_bank_transfer_poland,
revolut_pay,
indonesian_bank_transfer,
open_banking,
network_token,
payshap,
payshap_proxy
​
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
enum<string> | null
Available options:
AF,
AX,
AL,
DZ,
AS,
AD,
AO,
AI,
AQ,
AG,
AR,
AM,
AW,
AU,
AT,
AZ,
BS,
BH,
BD,
BB,
BY,
BE,
BZ,
BJ,
BM,
BT,
BO,
BQ,
BA,
BW,
BV,
BR,
IO,
BN,
BG,
BF,
BI,
KH,
CM,
CA,
CV,
KY,
CF,
TD,
CL,
CN,
CX,
CC,
CO,
KM,
CG,
CD,
CK,
CR,
CI,
HR,
CU,
CW,
CY,
CZ,
DK,
DJ,
DM,
DO,
EC,
EG,
SV,
GQ,
ER,
EE,
ET,
FK,
FO,
FJ,
FI,
FR,
GF,
PF,
TF,
GA,
GM,
GE,
DE,
GH,
GI,
GR,
GL,
GD,
GP,
GU,
GT,
GG,
GN,
GW,
GY,
HT,
HM,
VA,
HN,
HK,
HU,
IS,
IN,
ID,
IR,
IQ,
IE,
IM,
IL,
IT,
JM,
JP,
JE,
JO,
KZ,
KE,
KI,
KP,
KR,
KW,
KG,
LA,
LV,
LB,
LS,
LR,
LY,
LI,
LT,
LU,
MO,
MK,
MG,
MW,
MY,
MV,
ML,
MT,
MH,
MQ,
MR,
MU,
YT,
MX,
FM,
MD,
MC,
MN,
ME,
MS,
MA,
MZ,
MM,
NA,
NR,
NP,
NL,
NC,
NZ,
NI,
NE,
NG,
NU,
NF,
MP,
NO,
OM,
PK,
PW,
PS,
PA,
PG,
PY,
PE,
PH,
PN,
PL,
PT,
PR,
QA,
RE,
RO,
RU,
RW,
BL,
SH,
KN,
LC,
MF,
PM,
VC,
WS,
SM,
ST,
SA,
SN,
RS,
SC,
SL,
SG,
SX,
SK,
SI,
SB,
SO,
ZA,
GS,
SS,
ES,
LK,
SD,
SR,
SJ,
SZ,
SE,
CH,
SY,
TW,
TJ,
TZ,
TH,
TL,
TG,
TK,
TO,
TT,
TN,
TR,
TM,
TC,
TV,
UG,
UA,
AE,
GB,
UM,
UY,
UZ,
VU,
VE,
VN,
VG,
VI,
WF,
EH,
YE,
ZM,
ZW,
US
​
business_label
string | null
deprecated

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

​
business_sub_label
string | null
deprecated

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

​
allowed_payment_method_types
enum<string>[] | null

Allowed Payment Method Types for a given PaymentIntent

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

Available options:
ach,
affirm,
afterpay_clearpay,
alfamart,
ali_pay,
ali_pay_hk,
alma,
amazon_pay,
paysera,
apple_pay,
atome,
bacs,
bancontact_card,
becs,
benefit,
bizum,
blik,
bluecode,
boleto,
bca_bank_transfer,
bni_va,
breadpay,
bri_va,
bhn_card_network,
card_redirect,
cimb_va,
classic,
credit,
crypto_currency,
cashapp,
dana,
danamon_va,
debit,
duit_now,
efecty,
eft,
eft_debit_order,
eps,
flexiti,
fps,
evoucher,
giropay,
givex,
google_pay,
go_pay,
gcash,
ideal,
interac,
indomaret,
klarna,
kakao_pay,
local_bank_redirect,
mandiri_va,
knet,
mb_way,
mobile_pay,
momo,
momo_atm,
multibanco,
neteller,
online_banking_thailand,
online_banking_czech_republic,
online_banking_finland,
online_banking_fpx,
online_banking_poland,
online_banking_slovakia,
oxxo,
pago_efectivo,
permata_bank_transfer,
open_banking_uk,
pay_bright,
payjustnow,
paypal,
paze,
pix,
pix_key,
pix_emv,
pix_qr,
pix_automatico_qr,
pix_automatico_push,
pay_safe_card,
przelewy24,
prompt_pay,
pse,
qris,
red_compra,
red_pagos,
samsung_pay,
sepa,
sepa_bank_transfer,
sepa_guarenteed_debit,
skrill,
sofort,
swish,
touch_n_go,
trustly,
twint,
upi_collect,
upi_intent,
upi_qr,
vipps,
viet_qr,
venmo,
walley,
we_chat_pay,
seven_eleven,
lawson,
mini_stop,
family_mart,
seicomart,
pay_easy,
local_bank_transfer,
mifinity,
open_banking_pis,
direct_carrier_billing,
instant_bank_transfer,
instant_bank_transfer_finland,
instant_bank_transfer_poland,
revolut_pay,
indonesian_bank_transfer,
open_banking,
network_token,
payshap,
payshap_proxy
​
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"

​
frm_message
object | null

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.

​
connector_metadata
object | null

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

​
connector_response_metadata
object | null
​
feature_metadata
object | null

additional data that might be required by hyperswitch

​
reference_id
string | null

reference(Identifier) to the payment at connector side

Example:

"993672945374576J"

​
payment_link
object | null
​
profile_id
string | null

The business profile that is associated with this payment

​
surcharge_details
object | null

Details of surcharge applied on this payment, if applicable

​
applied_offer
object | null

Normalized applied-offer details exposed in payment responses.

​
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<int32> | null

Total number of authorizations happened in an incremental_authorization payment

​
incremental_authorizations
object[] | null

List of incremental authorizations happened to the payment

​
external_authentication_details
object | null

Details of external authentication

​
external_3ds_authentication_attempted
boolean | null

Flag indicating if external 3ds authentication is made or not

​
expires_on
string<date-time> | null

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.

​
fingerprint_type
enum<string> | null
Available options:
dpan,
fpan
​
browser_info
object | null

Browser information to be used for 3DS 2.0

​
payment_channel

Describes the channel through which the payment was initiated.

Available options:
ecommerce
​
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_account_reference
string | null

Payment Account Reference (PAR) returned by the connector for the underlying card, used to link tokenized and non-tokenized transactions for the same card.

Example:

"V001428640638148739"

​
network_transaction_link_id
string | null

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

​
payment_method_status
enum<string> | null

Payment Method Status

Available options:
active,
inactive,
processing,
awaiting_data,
new,
redacted
​
updated
string<date-time> | null

Date time at which payment was updated

Example:

"2022-09-10T10:11:12Z"

​
split_payments
object

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<date-time> | null

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

Example:

"2022-09-10T10:11:12Z"

​
request_extended_authorization
boolean | null
default:false

Optional boolean value to extent authorization period of this payment

capture method must be manual or manual_multiple

​
capture_before
string<date-time> | null

date and time after which this payment cannot be captured

​
merchant_order_reference_id
string | null

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.

Maximum string length: 255
Example:

"Custom_Order_id_123"

​
order_tax_amount
integer<int64> | null

This Unit struct represents MinorUnit in which core amount works

​
connector_mandate_id
string | null

Connector Identifier for the payment method

​
card_discovery
enum<string> | null

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

Available options:
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
default:false

Allow partial authorization for this payment

​
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

​
network_details
object | null
​
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
enum<string> | null

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.

Available options:
installment,
unscheduled,
recurring,
resubmission
​
billing_descriptor
object | null

Billing Descriptor information to be sent to the payment gateway

​
is_account_funded_transaction
boolean | null

Indicates whether this payment is an account funded transaction, where funds are pulled from a card account to fund another account rather than to pay for goods or services.

Example:

true

​
recipient_details
object | null

A partially masked view of RecipientDetails, safe to return in API responses.

​
tokenization
enum<string> | null

The type of tokenization to use for the payment method

Available options:
skip_psp,
tokenize_at_psp
​
partner_merchant_identifier_details
object | null

Information identifying partner and merchant application initiating the request

​
payment_method_tokenization_details
object | null
​
installment_options
object[] | null

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

​
installment_data
object | null

Installment selection made by the customer during payment confirmation.

​
sender_payment_instrument_id
string | null

A connector-specific identifier representing the stored payment instrument

Maximum string length: 255