POST
/
payments
/
{payment_id}
/
capture
curl --request POST \
  --url https://sandbox.hyperswitch.io/payments/{payment_id}/capture \
  --header 'Content-Type: application/json' \
  --header 'api-key: <api-key>' \
  --data '{
  "amount_to_capture": 654
}'

Authorizations

api-key
string
headerrequired

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_to_capture
integer
required

The Amount to be captured/ debited from the user's payment method.

merchant_id
string | null

The unique identifier for the merchant

refund_uncaptured_amount
boolean | null

Decider to refund the uncaptured amount

statement_descriptor_suffix
string | null

Provides information about a card payment that customers see on their statements.

statement_descriptor_prefix
string | null

Concatenated with the statement descriptor suffix that’s set on the account to form the complete statement descriptor.

merchant_connector_details
object

Merchant connector details used to make payments.

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_confirmationrequired

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

Details of customer attached to this payment

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

A timestamp (ISO 8601 code) that determines when the payment should be captured. Providing this field will automatically set capture to 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
payment_method_data
object
payment_token
string | null

Provide a reference to a stored payment method

shipping
object
billing
object
order_details
object[] | null

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

email
string | null
deprecated

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

Maximum length: 255
name
string | null
deprecated

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

Maximum length: 255
phone
string | null
deprecated

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

Maximum length: 255
return_url
string | null

The URL to redirect after the completion of the operation

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
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 255 characters for the concatenated descriptor.

Maximum length: 255
next_action
object

Contains the url for redirection flow

cancellation_reason
string | null

If the payment was cancelled the reason will be provided here

error_code
string | null

If there was an error while calling the connectors the code is received here

error_message
string | null

If there was an error while calling the connector the error message is received here

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

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
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,
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
connector_label
string | null

The connector used for this payment along with the country and business details

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

The business label of merchant for this payment

business_sub_label
string | null

The business_sub_label for this payment

allowed_payment_method_types
enum<string>[] | null

Allowed Payment Method Types for a given PaymentIntent

Available options:
ach,
affirm,
afterpay_clearpay,
alfamart,
ali_pay,
ali_pay_hk,
alma,
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
ephemeral_key
object

ephemeral_key for the customer_id mentioned

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

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

connector_metadata
object

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

feature_metadata
object

additional data that might be required by hyperswitch

reference_id
string | null

reference(Identifier) to the payment at connector side

payment_link
object
profile_id
string | null

The business profile that is associated with this payment

surcharge_details
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

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

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 for expiry of the payment

fingerprint
string | null

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

browser_info
object

Browser information to be used for 3DS 2.0

payment_method_id
string | null

Identifier for Payment Method used for the payment

payment_method_status
enum<string>

Payment Method Status

Available options:
active,
inactive,
processing,
awaiting_data
updated
string | null

Date time at which payment was updated

charges
object

Fee information to be charged on the payment being collected

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.

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

This Unit struct represents MinorUnit in which core amount works

connector_mandate_id
string | null

Connector Identifier for the payment method

Payments - CancelPayments - Incremental Authorization