Payments

Payments - Create

Creates a payment object when amount and currency are passed.

This API is also used to create a mandate by passing the mandate_object.

Depending on the user journey you wish to achieve, you may opt to complete all the steps in a single request by attaching a payment method, setting confirm=true and capture_method = automatic in the Payments/Create API request.

Otherwise, To completely process a payment you will have to create a payment, attach a payment method, confirm and capture funds. For that you could use the following sequence of API requests -

Payments - Create
Payments - Update
Payments - Confirm
Payments - Capture.

You will require the ‘API - Key’ from the Hyperswitch dashboard to make the first call, and use the ‘client secret’ returned in this API along with your ‘publishable key’ to make subsequent API calls from your client.

This page lists the various combinations in which the Payments - Create API can be used and the details about the various fields in the requests and responses.

POST

payments

object

amount

integer

order_tax_amount

integer

currency

enum<string>

amount_to_capture

integer

shipping_cost

integer

payment_id

string

routing

Single · object

type

enum<string>

data

object

connector

enum<string>

merchant_connector_id

string

connector

array

capture_method

enum<string>

authentication_type

enum<string>

billing

object

address

object

city

string

country

enum<string>

line1

string

line2

string

line3

string

zip

string

state

string

first_name

string

last_name

string

phone

object

number

string

country_code

string

confirm

boolean

customer

object

string

name

string

phone

string

phone_country_code

string

customer_id

string

off_session

boolean

description

string

return_url

string

setup_future_usage

enum<string>

payment_method_data

Card · object

card

object

card_number

string

card_exp_month

string

card_exp_year

string

card_holder_name

string

card_cvc

string

card_issuer

string

card_network

enum<string>

card_type

string

card_issuing_country

string

bank_code

string

nick_name

string

billing

object

address

object

city

string

country

enum<string>

line1

string

line2

string

line3

string

zip

string

state

string

first_name

string

last_name

string

phone

object

number

string

country_code

string

payment_method

enum<string>

payment_token

string

shipping

object

address

object

city

string

country

enum<string>

line1

string

line2

string

line3

string

zip

string

state

string

first_name

string

last_name

string

phone

object

number

string

country_code

string

statement_descriptor_name

string

statement_descriptor_suffix

string

order_details

array

mandate_data

object

update_mandate_id

string

customer_acceptance

object

acceptance_type

enum<string>

accepted_at

string

online

object

ip_address

string

user_agent

string

mandate_type

Option 1 · object

single_use

object

amount

integer

currency

enum<string>

start_date

string

end_date

string

metadata

object

customer_acceptance

object

acceptance_type

enum<string>

accepted_at

string

online

object

ip_address

string

user_agent

string

mandate_id

string

browser_info

object

color_depth

integer

java_enabled

boolean

java_script_enabled

boolean

language

string

screen_height

integer

screen_width

integer

time_zone

integer

ip_address

string

accept_header

string

user_agent

string

payment_experience

enum<string>

payment_method_type

enum<string>

business_country

enum<string>

business_label

string

merchant_connector_details

object

creds_identifier

string

encoded_data

object

connector_account_details

object

metadata

object

allowed_payment_method_types

array

metadata

object

connector_metadata

object

apple_pay

object

session_token_data

Option 1 · object

payment_processing_certificate

string

payment_processing_certificate_key

string

payment_processing_details_at

enum<string>

certificate

string

certificate_keys

string

merchant_identifier

string

display_name

string

initiative

enum<string>

initiative_context

string

merchant_business_country

enum<string>

airwallex

object

payload

string

noon

object

order_category

string

payment_link

boolean

payment_link_config

object

theme

string

logo

string

seller_name

string

sdk_layout

string

display_sdk_only

boolean

enabled_saved_payment_method

boolean

hide_card_nickname_field

boolean

show_card_form_by_default

boolean

transaction_details

array

background_image

object

url

string

position

enum<string>

size

Option 1 · object

Variants

enum<string>

details_layout

enum<string>

payment_button_text

string

payment_link_config_id

string

profile_id

string

surcharge_details

object

surcharge_amount

integer

tax_amount

integer

payment_type

enum<string>

request_incremental_authorization

boolean

session_expiry

integer

frm_metadata

object

request_external_three_ds_authentication

boolean

recurring_details

Option 1 · object

type

enum<string>

data

string

split_payments

object

stripe_split_payment

object

charge_type

object

Stripe

enum<string>

application_fees

integer

transfer_account_id

string

merchant_order_reference_id

string

skip_external_tax_calculation

boolean

psd2_sca_exemption_type

enum<string>

ctp_service_details

object

merchant_transaction_id

string

correlation_id

string

x_src_flow_id

string

provider

string

curl --request POST \
  --url https://sandbox.hyperswitch.io/payments \
  --header 'Content-Type: application/json' \
  --header 'api-key: <api-key>' \
  --data '{
  "amount": 6540,
  "authentication_type": "three_ds",
  "currency": "USD"
}'

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.

Body

application/json

amount

integer

required

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

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

order_tax_amount

integer | null

Total tax amount applicable to the order

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,

iatapay,

itaubank,

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,

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

object

required

payment_method_data.billing

object

payment_method_data.billing.address

object

Address details

payment_method_data.billing.phone

object

payment_method_data.billing.email

string | null

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

mandate_data

object

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

mandate_data.update_mandate_id

string | null

A way to update the mandate's payment method details

mandate_data.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_data.mandate_type

object

customer_acceptance

object

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,

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

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

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

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,

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

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.

connector_metadata.apple_pay

object

connector_metadata.apple_pay.session_token_data

object

connector_metadata.airwallex

object

connector_metadata.noon

object

payment_link

boolean | null

default: false

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

payment_link_config

object

Configure a custom payment link for the particular payment

payment_link_config.theme

string | null

custom theme for the payment link

Maximum length: 255

payment_link_config.logo

string | null

merchant display logo

Maximum length: 255

payment_link_config.seller_name

string | null

Custom merchant name for payment link

Maximum length: 255

payment_link_config.sdk_layout

string | null

Custom layout for sdk

Maximum length: 255

payment_link_config.display_sdk_only

boolean | null

default: false

Display only the sdk for payment link

payment_link_config.enabled_saved_payment_method

boolean | null

default: false

Enable saved payment method option for payment link

payment_link_config.hide_card_nickname_field

boolean | null

default: false

Hide card nickname field option for payment link

payment_link_config.show_card_form_by_default

boolean | null

default: true

Show card form by default for payment link

payment_link_config.transaction_details

object[] | null

Dynamic details related to merchant to be rendered in payment link

payment_link_config.background_image

object

payment_link_config.details_layout

enum<string>

Available options:

layout1,

layout2

payment_link_config.payment_button_text

string | null

Text for payment link's handle confirm button

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.

surcharge_details

object

Details of surcharge applied on this payment, if applicable

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

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

refunds.refund_id

string

required

Unique Identifier for the refund

refunds.payment_id

string

required

The payment id against which refund is initiated

refunds.amount

integer

required

The refund amount, which should be less than or equal to the total 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

Required range: x > 100

refunds.currency

string

required

The three-letter ISO currency code

refunds.status

enum<string>

required

The status for refunds

Available options:

succeeded,

failed,

pending,

review

refunds.reason

string | null

An arbitrary string attached to the object. Often useful for displaying to users and your customer support executive

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

refunds.error_message

string | null

The error message

refunds.error_code

string | null

The code for the error

refunds.created_at

string | null

The timestamp at which refund is created

refunds.updated_at

string | null

The timestamp at which refund is updated

refunds.connector

string

required

The connector used for the refund and the corresponding payment

refunds.profile_id

string | null

The id of business profile for this refund

refunds.merchant_connector_id

string | null

The merchant_connector_id of the processor through which this payment went through

refunds.split_refunds

object

Charge specific fields for controlling the revert of funds from either platform or connected account. Check sub-fields for more details.

disputes

object[] | null

List of disputes that happened on this intent

attempts

object[] | null

List of attempts that happened on this intent

attempts.attempt_id

string

required

Unique identifier for the attempt

attempts.status

enum<string>

required

The status of the attempt

Available options:

started,

authentication_failed,

router_declined,

authentication_pending,

authentication_successful,

authorized,

authorization_failed,

charged,

authorizing,

cod_initiated,

voided,

void_initiated,

capture_initiated,

capture_failed,

void_failed,

auto_refunded,

partial_charged,

partial_charged_and_chargeable,

unresolved,

pending,

failure,

payment_method_awaited,

confirmation_awaited,

device_data_collection_pending

attempts.amount

integer

required

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

attempts.order_tax_amount

integer | null

The payment attempt tax_amount.

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

attempts.connector

string | null

The connector used for the payment

attempts.error_message

string | null

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

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

attempts.connector_transaction_id

string | null

A unique identifier for a payment provided by the connector

attempts.capture_method

enum<string>

Available options:

automatic,

manual,

manual_multiple,

scheduled,

sequential_automatic

attempts.authentication_type

enum<string>

default: three_ds

Available options:

three_ds,

no_three_ds

attempts.created_at

string

required

Time at which the payment attempt was created

attempts.modified_at

string

required

Time at which the payment attempt was last modified

attempts.cancellation_reason

string | null

If the payment was cancelled the reason will be provided here

attempts.mandate_id

string | null

A unique identifier to link the payment to a mandate, can be use instead of payment_method_data

attempts.error_code

string | null

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

attempts.payment_token

string | null

Provide a reference to a stored payment method

attempts.connector_metadata

any | null

Additional data related to some connectors

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

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

direct_carrier_billing

attempts.reference_id

string | null

Reference to the payment at connector side

attempts.unified_code

string | null

(This field is not live yet)Error code unified across the connectors is received here if there was an error while calling connector

attempts.unified_message

string | null

(This field is not live yet)Error message unified across the connectors is received here if there was an error while calling connector

attempts.client_source

string | null

Value passed in X-CLIENT-SOURCE header during payments confirm request by the client

attempts.client_version

string | null

Value passed in X-CLIENT-VERSION header during payments confirm request by the client

captures

object[] | null

List of captures done on latest attempt

captures.capture_id

string

required

Unique identifier for the capture

captures.status

enum<string>

required

Available options:

started,

charged,

pending,

failed

captures.amount

integer

required

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

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

captures.connector

string

required

The connector used for the payment

captures.authorized_attempt_id

string

required

Unique identifier for the parent attempt on which this capture is made

captures.connector_capture_id

string | null

A unique identifier for this capture provided by the connector

captures.capture_sequence

integer

required

Sequence number of this capture, in the series of captures made for the parent attempt

captures.error_message

string | null

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

captures.error_code

string | null

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

captures.error_reason

string | null

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

captures.reference_id

string | null

Reference to the capture at connector side

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.

mandate_data.update_mandate_id

string | null

A way to update the mandate's payment method details

mandate_data.customer_acceptance

object

mandate_data.mandate_type

object

setup_future_usage

enum<string>

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

capture_method

enum<string>

Available options:

automatic,

manual,

manual_multiple,

scheduled,

sequential_automatic

payment_method_data

object

payment_method_data.card

object

required

payment_method_data.billing

object

payment_method_data.billing.address

object

Address details

payment_method_data.billing.phone

object

payment_method_data.billing.email

string | null

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)

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

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

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

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,

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

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,

direct_carrier_billing

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.

connector_metadata.apple_pay

object

connector_metadata.apple_pay.session_token_data

object

connector_metadata.airwallex

object

connector_metadata.noon

object

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

split_payments

object

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

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

curl --request POST \
  --url https://sandbox.hyperswitch.io/payments \
  --header 'Content-Type: application/json' \
  --header 'api-key: <api-key>' \
  --data '{
  "amount": 6540,
  "authentication_type": "three_ds",
  "currency": "USD"
}'

Payments

Payment Methods

Customers

Mandates

Refunds

Disputes

Organization

Merchant Account

Business Profile

API Key

Merchant Connector Account

Payouts

Event

GSM (Global Status Mapping)

Poll

Blocklist

Routing

Relay

Schemas

Payments - Create

Authorizations

Body

Response