POST
/
payments
/
{payment_id}
/
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.

Path Parameters

payment_id
string
required

The identifier for payment

Body

application/json
amount
integer | null

The payment amount. Amount for the payment in the lowest denomination of the currency, (i.e) in cents for USD denomination, in yen for JPY denomination etc. E.g., Pass 100 to charge $1.00 and 1 for 1¥ since ¥ is a zero-decimal currency. Read more about the Decimal and Non-Decimal Currencies

Required range: x > 0
order_tax_amount
integer | null

Total tax amount applicable to the order

currency
enum<string>

The three letter ISO currency code in uppercase. Eg: 'USD' for the United States Dollar.

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,
CLP,
CNY,
COP,
CRC,
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,
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 | null

The Amount to be captured / debited from the users payment method. It shall be in lowest denomination of the currency. (i.e) in cents for USD denomination, in paisa for INR denomination etc., If not provided, the default amount_to_capture will be the payment amount. Also, it must be less than or equal to the original payment account.

shipping_cost
integer | null

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

payment_id
string | null

Unique identifier for the payment. This ensures idempotency for multiple payments that have been done by a single merchant. The value for this field can be specified in the request, it will be auto generated otherwise and returned in the API response.

Required string length: 30
routing
object
connector
enum<string>[] | null

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

Available options:
adyenplatform,
phonypay,
fauxpay,
pretendpay,
stripe_test,
adyen_test,
checkout_test,
paypal_test,
aci,
adyen,
airwallex,
authorizedotnet,
bambora,
bamboraapac,
bankofamerica,
billwerk,
bitpay,
bluesnap,
boku,
braintree,
cashtocode,
checkout,
coinbase,
cryptopay,
ctp_mastercard,
cybersource,
datatrans,
deutschebank,
digitalvirgo,
dlocal,
ebanx,
elavon,
fiserv,
fiservemea,
fiuu,
forte,
globalpay,
globepay,
gocardless,
gpayments,
helcim,
inespay,
iatapay,
itaubank,
jpmorgan,
klarna,
mifinity,
mollie,
multisafepay,
netcetera,
nexinets,
nexixpay,
nmi,
noon,
novalnet,
nuvei,
opennode,
paybox,
payme,
payone,
paypal,
payu,
placetopay,
powertranz,
prophetpay,
rapyd,
razorpay,
shift4,
square,
stax,
stripe,
taxjar,
threedsecureio,
trustpay,
tsys,
volt,
wellsfargo,
wise,
worldline,
worldpay,
signifyd,
plaid,
riskified,
xendit,
zen,
zsl
capture_method
enum<string>

Default value if not passed is set to 'automatic' which results in Auth and Capture in one single API request. Pass 'manual' or 'manual_multiple' in case you want do a separate Auth and Capture by first authorizing and placing a hold on your customer's funds so that you can use the Payments/Capture endpoint later to capture the authorized amount. Pass 'manual' if you want to only capture the amount later once or 'manual_multiple' if you want to capture the funds multiple times later. Both 'manual' and 'manual_multiple' are only supported by a specific list of processors

Available options:
automatic,
manual,
manual_multiple,
scheduled,
sequential_automatic
authentication_type
enum<string>
default:
three_ds

Pass this parameter to force 3DS or non 3DS auth for this payment. Some connectors will still force 3DS auth even in case of passing 'no_three_ds' here and vice versa. Default value is 'no_three_ds' if not set

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

Whether to confirm the payment (if applicable). It can be used to completely process a payment by attaching a payment method, setting confirm=true and capture_method = automatic in the Payments/Create API request itself.

customer
object

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

customer_id
string | null

The identifier for the customer

Required string length: 1 - 64
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

description
string | null

A description for the payment

return_url
string | null

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

setup_future_usage
enum<string>

Indicates that you intend to make future payments with the payment methods used for this Payment. Providing this parameter will attach the payment method to the Customer, if present, after the Payment is confirmed and any required actions from the user are complete.

  • On_session - Payment method saved only at hyperswitch when consent is provided by the user. CVV will asked during the returning user payment
  • Off_session - Payment method saved at both hyperswitch and Processor when consent is provided by the user. No input is required during the returning user payment.
Available options:
off_session,
on_session
payment_method_data
object

The payment method information provided for making a payment

payment_method
enum<string>

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

shipping
object
statement_descriptor_name
string | null

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

Maximum length: 255
statement_descriptor_suffix
string | null

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.

Maximum length: 255
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

client_secret
string | null

It's a token used for client side verification.

mandate_data
object

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

customer_acceptance
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

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 length: 255
browser_info
object

Browser information to be used for 3DS 2.0

payment_experience
enum<string>

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>

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,
apple_pay,
atome,
bacs,
bancontact_card,
becs,
benefit,
bizum,
blik,
boleto,
bca_bank_transfer,
bni_va,
bri_va,
card_redirect,
cimb_va,
classic,
credit,
crypto_currency,
cashapp,
dana,
danamon_va,
debit,
duit_now,
efecty,
eps,
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,
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,
paypal,
paze,
pix,
pay_safe_card,
przelewy24,
prompt_pay,
pse,
red_compra,
red_pagos,
samsung_pay,
sepa,
sofort,
swish,
touch_n_go,
trustly,
twint,
upi_collect,
upi_intent,
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
merchant_connector_details
object

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

Available options:
ach,
affirm,
afterpay_clearpay,
alfamart,
ali_pay,
ali_pay_hk,
alma,
amazon_pay,
apple_pay,
atome,
bacs,
bancontact_card,
becs,
benefit,
bizum,
blik,
boleto,
bca_bank_transfer,
bni_va,
bri_va,
card_redirect,
cimb_va,
classic,
credit,
crypto_currency,
cashapp,
dana,
danamon_va,
debit,
duit_now,
efecty,
eps,
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,
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,
paypal,
paze,
pix,
pay_safe_card,
przelewy24,
prompt_pay,
pse,
red_compra,
red_pagos,
samsung_pay,
sepa,
sofort,
swish,
touch_n_go,
trustly,
twint,
upi_collect,
upi_intent,
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
retry_action
enum<string>

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

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

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

Configure a custom payment link for the particular payment

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

payment_type
enum<string>

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

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

recurring_details
object

Details required for recurring payment

split_payments
object

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

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 length: 255
skip_external_tax_calculation
boolean | null

Whether to calculate tax for this payment intent

psd2_sca_exemption_type
enum<string>

SCA Exemptions types available for authentication

Available options:
low_value,
transaction_risk_analysis
ctp_service_details
object

Response

200 - application/json
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
merchant_id
string
required

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

Maximum length: 255
status
enum<string>
default:
requires_confirmation
required

The status of the current payment that was made

Available options:
succeeded,
failed,
cancelled,
processing,
requires_customer_action,
requires_merchant_action,
requires_payment_method,
requires_confirmation,
requires_capture,
partially_captured,
partially_captured_and_capturable
amount
integer
required

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

net_amount
integer
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

amount_capturable
integer
required

The maximum amount that could be captured from the payment

Required range: x > 100
currency
enum<string>
required

The three letter ISO currency code in uppercase. Eg: 'USD' for the United States Dollar.

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,
CLP,
CNY,
COP,
CRC,
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,
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
attempt_count
integer
required

Total number of attempts associated with this payment

shipping_cost
integer | null

The shipping cost for the payment.

amount_received
integer | null

The amount which is already captured from the payment, this helps in the cases where merchants can't capture all capturable amount at once.

connector
string | null

The connector used for the payment

client_secret
string | null

It's a token used for client side verification.

created
string | null

Time when the payment was created

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

A description of the payment

refunds
object[] | null

List of refunds that happened on this intent, as same payment intent can have multiple refund requests depending on the nature of order

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

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 length: 255
mandate_data
object

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

setup_future_usage
enum<string>

Indicates that you intend to make future payments with the payment methods used for this Payment. Providing this parameter will attach the payment method to the Customer, if present, after the Payment is confirmed and any required actions from the user are complete.

  • On_session - Payment method saved only at hyperswitch when consent is provided by the user. CVV will asked during the returning user payment
  • Off_session - Payment method saved at both hyperswitch and Processor when consent is provided by the user. No input is required during the returning user payment.
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.

capture_method
enum<string>

Default value if not passed is set to 'automatic' which results in Auth and Capture in one single API request. Pass 'manual' or 'manual_multiple' in case you want do a separate Auth and Capture by first authorizing and placing a hold on your customer's funds so that you can use the Payments/Capture endpoint later to capture the authorized amount. Pass 'manual' if you want to only capture the amount later once or 'manual_multiple' if you want to capture the funds multiple times later. Both 'manual' and 'manual_multiple' are only supported by a specific list of processors

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

shipping
object
billing
object