PaySwitch
PaySwitch API Reference

AcceptanceType

string · enum
Enum values:
online
offline

This is used to indicate if the mandate was accepted online or offline

AcceptedCountries

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · type="enable_only" · requires: list
type = object · type="disable_only" · requires: list
type = object · type="all_accepted"
Properties for Variant 1:
type
​string · enum · required
Enum values:
enable_only
list
​CountryAlpha2[] · required
Enum values:
AF
AX
AL
DZ
AS
AD
AO
AI

AcceptedCurrencies

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · type="enable_only" · requires: list
type = object · type="disable_only" · requires: list
type = object · type="all_accepted"
Properties for Variant 1:
type
​string · enum · required
Enum values:
enable_only
list
​Currency[] · required
Enum values:
AED
AFN
ALL
AMD
ANG
AOA
ARS
AUD

AcceptedPaymentCurrencyLimit

currency
​Currency · enum · required

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

Enum values:
AED
AFN
ALL
AMD
ANG
AOA
ARS
AUD
min_amount
​MinorUnit · int64 · required

This Unit struct represents MinorUnit in which core amount works

max_amount
​MinorUnit · int64 · required

This Unit struct represents MinorUnit in which core amount works

AccountReceivablesHandling

string · enum
Enum values:
no_action
schedule_payment_collection
write_off

AchBankDebitAdditionalData

account_number
​string · required

Partially masked account number for ach bank debit payment

Example: 0001****3456
routing_number
​string · required

Partially masked routing number for ach bank debit payment

Example: 110***000
card_holder_name
​string | null

Card holder's name

Example: John Doe
bank_account_holder_name
​string | null

Bank account's owner name

Example: John Doe
bank_name
​string · enum

Name of banks supported by Hyperswitch

Enum values:
american_express
affin_bank
agro_bank
alliance_bank
am_bank
bank_of_america
bank_of_china
bank_islam
bank_type
​string · enum
Enum values:
checking
savings
bank_holder_type
​string · enum
Enum values:
personal
business

AchBankTransfer

bank_account_number
​string · required

Bank account number is an unique identifier assigned by a bank to a customer.

Example: 000123456
bank_routing_number
​string · required

[9 digits] Routing number - used in USA for identifying a specific bank.

Example: 110000000
bank_name
​string | null

Bank name

Example: Deutsche Bank
bank_country_code
​string · enum
Enum values:
AF
AX
AL
DZ
AS
AD
AO
AI
bank_city
​string | null

Bank city

Example: California

AchBankTransferAdditionalData

Masked payout method details for ach bank transfer payout method
bank_account_number
​string · required

Partially masked account number for ach bank debit payment

Example: 0001****3456
bank_routing_number
​string · required

Partially masked routing number for ach bank debit payment

Example: 110***000
bank_name
​string · enum

Name of banks supported by Hyperswitch

Enum values:
american_express
affin_bank
agro_bank
alliance_bank
am_bank
bank_of_america
bank_of_china
bank_islam
bank_country_code
​string · enum
Enum values:
AF
AX
AL
DZ
AS
AD
AO
AI
bank_city
​string | null

Bank city

Example: California

AchBillingDetails

email
​string | null

The Email ID for ACH billing

Example: example@me.com

AchTransfer

account_number
​string · required
bank_name
​string · required
routing_number
​string · required
swift_code
​string · required

AcquirerConfig

Acquirer configuration
acquirer_assigned_merchant_id
​string · required

The merchant id assigned by the acquirer

Example: M123456789
merchant_name
​string · required

merchant name

Example: NewAge Retailer
network
​string · required

Network provider

Example: VISA
acquirer_bin
​string · required

Acquirer bin

Example: 456789
acquirer_fraud_rate
​string · required

Fraud rate for the particular acquirer configuration

Example: 0.01
acquirer_ica
​string | null

Acquirer ica provided by acquirer

Example: 401288

AcquirerConfigMap

Acquirer configs
acquirer_assigned_merchant_id
​string · required

The merchant id assigned by the acquirer

Example: M123456789
merchant_name
​string · required

merchant name

Example: NewAge Retailer
network
​string · required

Network provider

Example: VISA
acquirer_bin
​string · required

Acquirer bin

Example: 456789
acquirer_fraud_rate
​string · required

Fraud rate for the particular acquirer configuration

Example: 0.01
acquirer_ica
​string | null

Acquirer ica provided by acquirer

Example: 401288

AcquirerData

Represents data about the acquirer used in the 3DS decision rule.
country
​Country · enum · required
Enum values:
Afghanistan
AlandIslands
Albania
Algeria
AmericanSamoa
Andorra
Angola
Anguilla
fraud_rate
​number | null · double

The fraud rate associated with the acquirer.

AcquirerDetails

acquirer_bin
​string | null

The bin of the card.

Example: 123456
acquirer_merchant_id
​string | null

The merchant id of the card.

Example: merchant_abc
merchant_country_code
​string | null

The country code of the card.

Example: US/34456

AddToBlocklistBatchRequest

​BlocklistRequest[] · required

AddToWhitelistBatchRequest

​WhitelistRequest[] · required

AdditionalMerchantData

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · requires: open_banking_recipient_data
Properties for Variant 1:
​MerchantRecipientData · required

AdditionalPayoutMethodData

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · requires: Card
type = object · requires: Bank
type = object · requires: Wallet
type = object · requires: BankRedirect
type = object · requires: Passthrough
Properties for Variant 1:
​CardAdditionalData · required

Masked payout method details for card payout method

Address

​object

Address details

​object
email
​string | null

AddressDetails

Address details
city
​string | null · maxLength: 50

The city, district, suburb, town, or village of the address.

Example: New York
country
​string · enum
Enum values:
AF
AX
AL
DZ
AS
AD
AO
AI
line1
​string | null · maxLength: 200

The first line of the street address or P.O. Box.

Example: 123, King Street
line2
​string | null · maxLength: 50

The second line of the street address or P.O. Box (e.g., apartment, suite, unit, or building).

Example: Powelson Avenue
line3
​string | null · maxLength: 50

The third line of the street address, if applicable.

Example: Bridgewater
zip
​string | null · maxLength: 50

The zip/postal code for the address

Example: 08807
state
​string | null

The address state

Example: New York
first_name
​string | null · maxLength: 255

The first name for the address

Example: John
last_name
​string | null · maxLength: 255

The last name for the address

Example: Doe
origin_zip
​string | null · maxLength: 50

The zip/postal code of the origin

Example: 08807

AdyenConnectorMetadata

​AdyenTestingData · required

AdyenSplitData

Fee information for Split Payments to be charged on the payment being collected for Adyen
​AdyenSplitItem[] · required

Data for the split items

store
​string | null

The store identifier

AdyenSplitItem

Data for the split items
amount
​integer · int64 · required

The amount of the split item

Example: 6540
split_type
​AdyenSplitType · enum · required
Enum values:
BalanceAccount
AcquiringFees
PaymentFee
AdyenFees
AdyenCommission
AdyenMarkup
Interchange
SchemeFee
reference
​string · required

Unique Identifier for the split item

account
​string | null

The unique identifier of the account to which the split amount is allocated.

description
​string | null

Description for the part of the payment that will be allocated to the specified account.

AdyenSplitType

string · enum
Enum values:
BalanceAccount
AcquiringFees
PaymentFee
AdyenFees
AdyenCommission
AdyenMarkup
Interchange
SchemeFee

AdyenTestingData

holder_name
​string · required

Holder name to be sent to Adyen for a card payment(CIT) or a generic payment(MIT). This value overrides the values for card.card_holder_name and applies during both CIT and MIT payment transactions.

AirwallexData

payload
​string | null

payload required by airwallex

AlfamartVoucherData

first_name
​string | null

The billing first name for Alfamart

Example: Jane
last_name
​string | null

The billing second name for Alfamart

Example: Doe
email
​string | null

The Email ID for Alfamart

Example: example@me.com

AliPayHkRedirection

AliPayQr

AliPayRedirection

AmazonPayDeliveryOptions

id
​string · required

Delivery Option identifier

​AmazonPayDeliveryPrice · required
​AmazonPayShippingMethod · required
is_default
​boolean · required

Specifies if this delivery option is the default

AmazonPayDeliveryPrice

amount
​MinorUnit · int64 · required

This Unit struct represents MinorUnit in which core amount works

currency_code
​Currency · enum · required

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

Enum values:
AED
AFN
ALL
AMD
ANG
AOA
ARS
AUD

AmazonPayMerchantCredentials

merchant_id
​string · required

Amazon Pay merchant account identifier

store_id
​string · required

Amazon Pay store ID

AmazonPayPaymentIntent

string · enum
Enum values:
Confirm
Authorize
AuthorizeWithCapture

AmazonPayRedirectData

AmazonPaySessionTokenData

​AmazonPayMerchantCredentials · required

AmazonPaySessionTokenResponse

merchant_id
​string · required

Amazon Pay merchant account identifier

ledger_currency
​Currency · enum · required

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

Enum values:
AED
AFN
ALL
AMD
ANG
AOA
ARS
AUD
store_id
​string · required

Amazon Pay store ID

payment_intent
​AmazonPayPaymentIntent · enum · required
Enum values:
Confirm
Authorize
AuthorizeWithCapture
total_shipping_amount
​string · required

The total shipping costs

total_tax_amount
​string · required

The total tax amount for the order

total_base_amount
​string · required

The total amount for items in the cart

​AmazonPayDeliveryOptions[] · required

The delivery options available for the provided address

AmazonPayShippingMethod

shipping_method_name
​string · required

Name of the shipping method

shipping_method_code
​string · required

Code of the shipping method

AmazonPayWalletData

checkout_session_id
​string · required

Checkout Session identifier

AmountFilter

start_amount
​integer | null · int64

The start amount to filter list of transactions which are greater than or equal to the start amount

end_amount
​integer | null · int64

The end amount to filter list of transactions which are less than or equal to the end amount

AmountInfo

label
​string · required

The label must be the name of the merchant.

amount
​string · required

The total amount for the payment in majot unit string (Ex: 38.02)

Example: 38.02
type
​string | null

A value that indicates whether the line item(Ex: total, tax, discount, or grand total) is final or pending.

ApiConnectorErrorDetails

Error details from the payment connector
code
​string | null

Connector-specific error code

message
​string | null

Connector-specific error message

reason
​string | null

Additional error reason/details

ApiIssuerErrorDetails

Error details from the card issuer
code
​string | null

Error code from the issuer

message
​string | null

Error message from the issuer

​object

Network-specific error details (e.g., Visa, Mastercard)

ApiKeyExpiration

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = string
type = string
Properties for Variant 1:
string · enum
Enum values:
never

ApiKeyPermissionGrant

One permission grant stored on an API key: same axes as [`crate::Permission`] / JWT roles.
resource
​Resource · enum · required
Enum values:
payment
refund
api_key
account
connector
routing
dispute
mandate
scope
​PermissionScope · enum · required
Enum values:
read
write
entity_type
​EntityType · enum · required
Enum values:
tenant
organization
merchant
profile

ApiKeyPermissions

JSON column value: explicit non-empty grants for the key.

One permission grant stored on an API key: same axes as [`crate::Permission`] / JWT roles.
resource
​Resource · enum · required
Enum values:
payment
refund
api_key
account
connector
routing
dispute
mandate
scope
​PermissionScope · enum · required
Enum values:
read
write
entity_type
​EntityType · enum · required
Enum values:
tenant
organization
merchant
profile

ApiNetworkErrorDetails

Network-specific error details (e.g., Visa, Mastercard)
name
​string · enum

Indicates the card network.

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

Network advice code

advice_message
​string | null

Network advice message

ApiUnifiedErrorDetails

Unified error details standardized across all payment connectors
category
​string · enum
Enum values:
UE_1000
UE_2000
UE_3000
UE_4000
UE_9000
message
​string | null

Human-readable error message

standardised_code
​string · enum
Enum values:
account_closed_or_invalid
authentication_failed
authentication_required
authorization_missing_or_revoked
card_lost_or_stolen
card_not_supported_restricted
cfg_pm_not_enabled_or_misconfigured
compliance_or_sanctions_restriction
description
​string | null

Detailed description of the error

user_guidance_message
​string | null

User-friendly guidance message

recommended_action
​string · enum
Enum values:
do_not_retry
retry_after_10_days
retry_after_1_hour
retry_after_24_hours
retry_after_2_days
retry_after_4_days
retry_after_6_days
retry_after_8_days

ApplePayAddressParameters

string · enum
Enum values:
postalAddress
phone
email

ApplePayBillingContactFields

Enum values:
postalAddress
phone
email

ApplePayCryptogramData

This struct represents the cryptogram data for Apple Pay transactions
online_payment_cryptogram
​string · required

The online payment cryptogram

Example: A1B2C3D4E5F6G7H8
eci_indicator
​string · required

The ECI (Electronic Commerce Indicator) value

Example: 05

ApplePayDecrypt

dpan
​string · required

The dpan number associated with card number

Example: 4242424242424242
expiry_month
​string · required

The card's expiry month

expiry_year
​string · required

The card's expiry year

card_holder_name
​string · required

The card holder's name

Example: John Doe
card_network
​string · enum

Indicates the card network.

Enum values:
Visa
Mastercard
AmericanExpress
JCB
DinersClub
Discover
CartesBancaires
UnionPay

ApplePayDecryptAdditionalData

Masked payout method details for Apple pay decrypt wallet payout method
card_exp_month
​string · required

Card expiry month

Example: 01
card_exp_year
​string · required

Card expiry year

Example: 2026
card_holder_name
​string · required

Card holder name

Example: John Doe

ApplePayPaymentData

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · requires: application_primary_account_number, application_expiration_month, application_expiration_year +1 more
type = string
Properties for Variant 1:
This struct represents the decrypted Apple Pay payment data
application_primary_account_number
​string · required

The primary account number

Example: 4242424242424242
application_expiration_month
​string · required

The application expiration date (PAN expiry month)

Example: 12
application_expiration_year
​string · required

The application expiration date (PAN expiry year)

Example: 24
​ApplePayCryptogramData · required

This struct represents the cryptogram data for Apple Pay transactions

ApplePayPaymentRequest

country_code
​CountryAlpha2 · enum · required
Enum values:
AF
AX
AL
DZ
AS
AD
AO
AI
currency_code
​Currency · enum · required

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

Enum values:
AED
AFN
ALL
AMD
ANG
AOA
ARS
AUD
​AmountInfo · required
merchant_capabilities
​array | null

The list of merchant capabilities(ex: whether capable of 3ds or no-3ds)

supported_networks
​array | null

The list of supported networks

merchant_identifier
​string | null
required_billing_contact_fields
​ApplePayAddressParameters[]
Enum values:
postalAddress
phone
email
required_shipping_contact_fields
​ApplePayAddressParameters[]
Enum values:
postalAddress
phone
email
​object

ApplePayPaymentTiming

string · enum
Enum values:
immediate
recurring

ApplePayPredecryptData

This struct represents the decrypted Apple Pay payment data
application_primary_account_number
​string · required

The primary account number

Example: 4242424242424242
application_expiration_month
​string · required

The application expiration date (PAN expiry month)

Example: 12
application_expiration_year
​string · required

The application expiration date (PAN expiry year)

Example: 24
​ApplePayCryptogramData · required

This struct represents the cryptogram data for Apple Pay transactions

ApplePayRecurringDetails

payment_description
​string · required

A description of the recurring payment that Apple Pay displays to the user in the payment sheet

​ApplePayRegularBillingDetails · required
management_url
​string · required

A URL to a web page where the user can update or delete the payment method for the recurring payment

Example: https://hyperswitch.io
billing_agreement
​string | null

A localized billing agreement that the payment sheet displays to the user before the user authorizes the payment

ApplePayRecurringPaymentRequest

payment_description
​string · required

A description of the recurring payment that Apple Pay displays to the user in the payment sheet

​ApplePayRegularBillingRequest · required
management_u_r_l
​string · required

A URL to a web page where the user can update or delete the payment method for the recurring payment

Example: https://hyperswitch.io
billing_agreement
​string | null

A localized billing agreement that the payment sheet displays to the user before the user authorizes the payment

ApplePayRedirectData

ApplePayRegularBillingDetails

label
​string · required

The label that Apple Pay displays to the user in the payment sheet with the recurring details

recurring_payment_start_date
​string | null · date-time

The date of the first payment

Example: 2023-09-10T23:59:59Z
recurring_payment_end_date
​string | null · date-time

The date of the final payment

Example: 2023-09-10T23:59:59Z
recurring_payment_interval_unit
​string · enum
Enum values:
year
month
day
hour
minute
recurring_payment_interval_count
​integer | null · int32

The number of interval units that make up the total payment interval

ApplePayRegularBillingRequest

amount
​string · required

The amount of the recurring payment

Example: 38.02
label
​string · required

The label that Apple Pay displays to the user in the payment sheet with the recurring details

payment_timing
​ApplePayPaymentTiming · enum · required
Enum values:
immediate
recurring
recurring_payment_start_date
​string | null · date-time

The date of the first payment

recurring_payment_end_date
​string | null · date-time

The date of the final payment

recurring_payment_interval_unit
​string · enum
Enum values:
year
month
day
hour
minute
recurring_payment_interval_count
​integer | null · int32

The number of interval units that make up the total payment interval

ApplePaySessionResponse

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · requires: secrets
type = object · requires: epoch_timestamp, expires_at, merchant_session_identifier +8 more
No specific criteria
Properties for Variant 1:

ApplePayShippingContactFields

Enum values:
postalAddress
phone
email

ApplePayThirdPartySdkData

token
​string | null

ApplePayWalletData

​ApplePayPaymentData · required

This enum is used to represent the Apple Pay payment data, which can either be encrypted or decrypted.

​ApplepayPaymentMethod · required
transaction_identifier
​string · required

The unique identifier for the transaction

ApplepayConnectorMetadataRequest

​object

ApplepayInitiative

string · enum
Enum values:
web
ios

ApplepayPaymentMethod

display_name
​string · required

The name to be displayed on Apple Pay button

network
​string · required

The network of the Apple pay payment method

type
​string · required

The type of the payment method

card_exp_month
​string | null

The card's expiry month

Example: 12
card_exp_year
​string | null

The card's expiry year

Example: 003925
auth_code
​string | null

Unique authorisation code generated for the payment

ApplepaySessionTokenResponse

connector
​string · required

The session token is w.r.t this connector

delayed_session_token
​boolean · required

Identifier for the delayed session response

​SdkNextAction · required
​
​object
connector_reference_id
​string | null

The connector transaction id

connector_sdk_public_key
​string | null

The public key id is to invoke third party sdk

connector_merchant_id
​string | null

The connector merchant id

AttemptStatus

string · enum
Enum values:
started
authentication_failed
router_declined
authentication_pending
authentication_successful
authorized
authorization_failed
charged

The status of the attempt

AuthenticationAuthenticateRequest

client_secret
​string · required

Client secret for the authentication

device_channel
​DeviceChannel · enum · required

Device Channel indicating whether request is coming from App or Browser

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

Indicates if 3DS method data was successfully completed or not

Enum values:
Y
N
U
​object

SDK Information if request is from SDK

AuthenticationAuthenticateResponse

acs_url
​string · required

Access Server URL to be used for challenge submission

Example: https://example.com/redirect
three_ds_requestor_url
​string · required

Three DS Requestor URL

error_message
​string · required

The error message for this authentication.

error_code
​string · required

The error code for this authentication.

authentication_value
​string · required

The authentication value for this authentication, only available in case of server to server request. Unavailable in case of client request due to security concern.

status
​AuthenticationStatus · enum · required
Enum values:
started
pending
success
failed
authentication_id
​AuthenticationId · required

A type for authentication_id that can be used for authentication IDs

eci
​string · required

The ECI value for this authentication.

trans_status
​string · enum

Indicates the transaction status

Enum values:
Y
N
U
A
R
C
D
I
challenge_request
​string | null

Challenge request which should be sent to acs_url

acs_reference_number
​string | null

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

acs_trans_id
​string | null

Unique identifier assigned by the ACS to identify a single transaction

three_ds_server_transaction_id
​string | null

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

acs_signed_content
​string | null

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

three_ds_requestor_app_url
​string | null

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

authentication_connector
​string · enum
Enum values:
threedsecureio
netcetera
gpayments
ctp_mastercard
unified_authentication_service
juspaythreedsserver
ctp_visa
cardinal
​object

AuthenticationConnectorDetails

authentication_connectors
​AuthenticationConnectors[] · required

List of authentication connectors

Enum values:
threedsecureio
netcetera
gpayments
ctp_mastercard
unified_authentication_service
juspaythreedsserver
ctp_visa
cardinal
three_ds_requestor_url
​string · required

URL of the (customer service) website that will be shown to the shopper in case of technical errors during the 3D Secure 2 process.

three_ds_requestor_app_url
​string | null

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

AuthenticationConnectors

string · enum
Enum values:
threedsecureio
netcetera
gpayments
ctp_mastercard
unified_authentication_service
juspaythreedsserver
ctp_visa
cardinal

AuthenticationCreateRequest

amount
​MinorUnit · int64 · required

This Unit struct represents MinorUnit in which core amount works

currency
​Currency · enum · required

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

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

The unique identifier for this authentication.

Example: auth_mbabizu24mvu3mela5njyhpit4
profile_id
​string | null

The business profile that is associated with this authentication

​object

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

authentication_connector
​string · enum
Enum values:
threedsecureio
netcetera
gpayments
ctp_mastercard
unified_authentication_service
juspaythreedsserver
ctp_visa
cardinal
return_url
​string | null

The URL to which the user should be redirected after authentication.

Example: https://example.com/redirect
force_3ds_challenge
​boolean | null

Force 3DS challenge.

psd2_sca_exemption_type
​string · enum

SCA Exemptions types available for authentication

Enum values:
low_value
transaction_risk_analysis
profile_acquirer_id
​string | null

Profile Acquirer ID get from profile acquirer configuration

​object
​object

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

AuthenticationEligibilityCheckData

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · requires: click_to_pay
Properties for Variant 1:
​ClickToPayEligibilityCheckData · required

AuthenticationEligibilityCheckRequest

​AuthenticationEligibilityCheckData · required
client_secret
​string | null

Optional secret value used to identify and authorize the client making the request. This can help ensure that the payment session is secure and valid.

AuthenticationEligibilityCheckResponse

authentication_id
​string · required

The unique identifier for this authentication.

Example: auth_mbabizu24mvu3mela5njyhpit4
​AuthenticationSdkNextAction · required

AuthenticationEligibilityCheckResponseData

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · requires: click_to_pay_enrollment_status
Properties for Variant 1:
​ClickToPayEligibilityCheckResponseData · required

AuthenticationEligibilityRequest

​PaymentMethodData · required
payment_method
​PaymentMethod · enum · required

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

Enum values:
card
card_redirect
pay_later
wallet
bank_redirect
bank_transfer
crypto
bank_debit
payment_method_type
​string · enum

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

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

Optional secret value used to identify and authorize the client making the request. This can help ensure that the payment session is secure and valid.

profile_id
​string | null

Optional identifier for the business profile associated with the payment. This determines which configurations, rules, and branding are applied to the transaction.

​object
​object
​object

Browser information to be used for 3DS 2.0

email
​string | null

Optional email address of the customer. Used for customer identification, communication, and possibly for 3DS or fraud checks.

AuthenticationEligibilityResponse

authentication_id
​string · required

The unique identifier for this authentication.

Example: auth_mbabizu24mvu3mela5njyhpit4
​NextAction · required
status
​AuthenticationStatus · enum · required
Enum values:
started
pending
success
failed
connector_metadata
​required

The metadata for this authentication.

profile_id
​string · required

The unique identifier for this authentication.

​
error_message
​string | null

The error message for this authentication.

error_code
​string | null

The error code for this authentication.

authentication_connector
​string · enum
Enum values:
threedsecureio
netcetera
gpayments
ctp_mastercard
unified_authentication_service
juspaythreedsserver
ctp_visa
cardinal
​object
​object
​object

Browser information to be used for 3DS 2.0

email
​string | null

Email

​object

AuthenticationId

string

A type for authentication_id that can be used for authentication IDs

AuthenticationPaymentMethodData

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object
Properties for Variant 1:
merchant_transaction_id
​string | null

merchant transaction id

correlation_id
​string | null

network transaction correlation id

x_src_flow_id
​string | null

session transaction flow id

provider
​string · enum
Enum values:
visa
mastercard
encrypted_payload
​string | null

Encrypted payload

AuthenticationPaymentMethodDataResponse

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · type="card_data"
type = object · type="network_token_data"
Properties for Variant 1:
type
​string · enum · required
Enum values:
card_data
card_expiry_year
​string | null

card expiry year

card_expiry_month
​string | null

card expiry month

AuthenticationPaymentMethodType

string · enum
Enum values:
ctp

AuthenticationResponse

authentication_id
​string · required

The unique identifier for this authentication.

Example: auth_mbabizu24mvu3mela5njyhpit4
merchant_id
​string · required

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

Example: merchant_abc
status
​AuthenticationStatus · enum · required
Enum values:
started
pending
success
failed
amount
​MinorUnit · int64 · required

This Unit struct represents MinorUnit in which core amount works

currency
​Currency · enum · required

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

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

The client secret for this authentication, to be used for client-side operations.

Example: auth_mbabizu24mvu3mela5njyhpit4_secret_el9ksDkiB8hi6j9N78yo
authentication_connector
​string · enum
Enum values:
threedsecureio
netcetera
gpayments
ctp_mastercard
unified_authentication_service
juspaythreedsserver
ctp_visa
cardinal
force_3ds_challenge
​boolean | null

Whether 3DS challenge was forced.

return_url
​string | null

The URL to which the user should be redirected after authentication, if provided.

created_at
​string | null · date-time
error_code
​string | null
error_message
​string | null

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

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

The business profile that is associated with this payment

psd2_sca_exemption_type
​string · enum

SCA Exemptions types available for authentication

Enum values:
low_value
transaction_risk_analysis
​object
profile_acquirer_id
​string | null

Profile Acquirer ID get from profile acquirer configuration

​object

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

AuthenticationRetrieveEligibilityCheckRequest

AuthenticationRetrieveEligibilityCheckResponse

​AuthenticationEligibilityCheckResponseData · required

AuthenticationSdkNextAction

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = string
type = object · requires: deny
type = string
Properties for Variant 1:
string · enum
Enum values:
await_merchant_callback

The next action is to await for a merchant callback

AuthenticationSessionResponse

authentication_id
​string · required

The identifier for the payment

​AuthenticationSessionToken[] · required

The list of session token object

AuthenticationSessionToken

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · wallet_name="click_to_pay" · requires: dpa_id, dpa_name, locale +6 more
type = object · wallet_name="no_session_token_received"
Properties for Variant 1:
dpa_id
​string · required
dpa_name
​string · required
locale
​string · required
card_brands
​CardNetwork[] · required
Enum values:
Visa
Mastercard
AmericanExpress
JCB
DinersClub
Discover
CartesBancaires
UnionPay
Example: [Visa, Mastercard]
acquirer_bin
​string · required
acquirer_merchant_id
​string · required
merchant_country_code
​string · required
transaction_amount
​string · required
transaction_currency_code
​Currency · enum · required

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

Enum values:
AED
AFN
ALL
AMD
ANG
AOA
ARS
AUD
wallet_name
​string · enum · required
Enum values:
click_to_pay
merchant_category_code
​string | null
phone_number
​string | null · maxLength: 255
email
​string | null · maxLength: 255
phone_country_code
​string | null
provider
​string · enum
Enum values:
visa
mastercard
dpa_client_id
​string | null

AuthenticationSessionTokenRequest

client_secret
​string · required

Client Secret for the authentication

AuthenticationStatus

string · enum
Enum values:
started
pending
success
failed

AuthenticationSyncPostUpdateRequest

AuthenticationSyncRequest

client_secret
​string · required

The client secret for this authentication.

​object

AuthenticationSyncResponse

authentication_id
​string · required

The unique identifier for this authentication.

Example: auth_mbabizu24mvu3mela5njyhpit4
merchant_id
​string · required

This is an identifier for the merchant account.

Example: merchant_abc
status
​AuthenticationStatus · enum · required
Enum values:
started
pending
success
failed
amount
​MinorUnit · int64 · required

This Unit struct represents MinorUnit in which core amount works

currency
​Currency · enum · required

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

Enum values:
AED
AFN
ALL
AMD
ANG
AOA
ARS
AUD
created_at
​string · date-time · required
profile_id
​string · required

The business profile that is associated with this authentication.

client_secret
​string | null

The client secret for this authentication.

authentication_connector
​string · enum
Enum values:
threedsecureio
netcetera
gpayments
ctp_mastercard
unified_authentication_service
juspaythreedsserver
ctp_visa
cardinal
force_3ds_challenge
​boolean | null

Whether 3DS challenge was forced.

return_url
​string | null

The URL to which the user should be redirected after authentication.

psd2_sca_exemption_type
​string · enum

SCA Exemptions types available for authentication

Enum values:
low_value
transaction_risk_analysis
​object
threeds_server_transaction_id
​string | null

The unique identifier from the 3DS server.

maximum_supported_3ds_version
​string | null

The maximum supported 3DS version.

connector_authentication_id
​string | null

The unique identifier from the connector.

three_ds_method_data
​string | null

The data required to perform the 3DS method.

three_ds_method_url
​string | null

The URL for the 3DS method.

message_version
​string | null

The version of the message.

connector_metadata
​

The metadata for this authentication.

directory_server_id
​string | null

The unique identifier for the directory server.

​
​
​object
​object
​object

Browser information to be used for 3DS 2.0

email
​string | null

Email.

trans_status
​string · enum

Indicates the transaction status

Enum values:
Y
N
U
A
R
C
D
I
acs_url
​string | null

Access Server URL for challenge submission.

challenge_request
​string | null

Challenge request to be sent to acs_url.

acs_reference_number
​string | null

Unique identifier assigned by EMVCo.

acs_trans_id
​string | null

Unique identifier assigned by the ACS.

acs_signed_content
​string | null

JWS object created by the ACS for the ARes message.

three_ds_requestor_url
​string | null

Three DS Requestor URL.

three_ds_requestor_app_url
​string | null

Merchant app URL for OOB authentication.

eci
​string | null

ECI value for this authentication, only available in case of server to server request. Unavailable in case of client request due to security concern.

error_message
​string | null

Error message if any.

error_code
​string | null

Error code if any.

profile_acquirer_id
​string | null

Profile Acquirer ID

AuthenticationType

string · enum
Enum values:
three_ds
no_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.

AuthenticationVaultTokenData

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · type="card_data"
type = object · type="network_token_data"
Properties for Variant 1:
type
​string · enum · required
Enum values:
card_data
card_number
​string | null

token representing card_number

card_expiry_year
​string | null

token representing card_expiry_year

card_expiry_month
​string | null

token representing card_expiry_month

card_cvc
​string | null

token representing card_cvc

AuthorizationStatus

string · enum
Enum values:
success
failure
processing
unresolved

BHNGiftCardDetails

account_number
​string · required

The gift card or account number

pin
​string · required

The security PIN for gift cards requiring it

cvv2
​string · required

The CVV2 code for Open Loop/VPLN products

expiration_date
​string · required

The expiration date in MMYYYY format for Open Loop/VPLN products

BacsBankDebitAdditionalData

account_number
​string · required

Partially masked account number for Bacs payment method

Example: 0001****3456
sort_code
​string · required

Partially masked sort code for Bacs payment method

Example: 108800
bank_account_holder_name
​string | null

Bank account's owner name

Example: John Doe

BacsBankTransfer

bank_account_number
​string · required

Bank account number is an unique identifier assigned by a bank to a customer.

Example: 000123456
bank_sort_code
​string · required

[6 digits] Sort Code - used in UK and Ireland for identifying a bank and it's branches.

Example: 98-76-54
bank_name
​string | null

Bank name

Example: Deutsche Bank
bank_country_code
​string · enum
Enum values:
AF
AX
AL
DZ
AS
AD
AO
AI
bank_city
​string | null

Bank city

Example: California

BacsBankTransferAdditionalData

Masked payout method details for bacs bank transfer payout method
bank_sort_code
​string · required

Partially masked sort code for Bacs payment method

Example: 108800
bank_account_number
​string · required

Bank account's owner name

Example: 0001****3456
bank_name
​string | null

Bank name

Example: Deutsche Bank
bank_country_code
​string · enum
Enum values:
AF
AX
AL
DZ
AS
AD
AO
AI
bank_city
​string | null

Bank city

Example: California

BacsBankTransferInstructions

account_holder_name
​string · required
account_number
​string · required
sort_code
​string · required

BancontactBankRedirectAdditionalData

last4
​string | null

Last 4 digits of the card number

Example: 4242
card_exp_month
​string | null

The card's expiry month

Example: 12
card_exp_year
​string | null

The card's expiry year

Example: 24
card_holder_name
​string | null

The card holder's name

Example: John Test

Bank

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · requires: bank_account_number, bank_routing_number
type = object · requires: bank_account_number, bank_sort_code
type = object · requires: iban, bic
type = object · requires: bank_account_number, pix_key
Properties for Variant 1:
bank_account_number
​string · required

Bank account number is an unique identifier assigned by a bank to a customer.

Example: 000123456
bank_routing_number
​string · required

[9 digits] Routing number - used in USA for identifying a specific bank.

Example: 110000000
bank_name
​string | null

Bank name

Example: Deutsche Bank
bank_country_code
​string · enum
Enum values:
AF
AX
AL
DZ
AS
AD
AO
AI
bank_city
​string | null

Bank city

Example: California

BankAdditionalData

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · requires: bank_account_number, bank_routing_number
type = object · requires: bank_sort_code, bank_account_number
type = object · requires: iban
type = object
Properties for Variant 1:
Masked payout method details for ach bank transfer payout method
bank_account_number
​string · required

Partially masked account number for ach bank debit payment

Example: 0001****3456
bank_routing_number
​string · required

Partially masked routing number for ach bank debit payment

Example: 110***000
bank_name
​string · enum

Name of banks supported by Hyperswitch

Enum values:
american_express
affin_bank
agro_bank
alliance_bank
am_bank
bank_of_america
bank_of_china
bank_islam
bank_country_code
​string · enum
Enum values:
AF
AX
AL
DZ
AS
AD
AO
AI
bank_city
​string | null

Bank city

Example: California

BankCodeResponse

bank_name
​BankNames[] · required
Enum values:
american_express
affin_bank
agro_bank
alliance_bank
am_bank
bank_of_america
bank_of_china
bank_islam
eligible_connectors
​string[] · required

BankDebitAdditionalData

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · requires: ach
type = object · requires: bacs
type = object · requires: becs
type = object · requires: sepa
type = object · requires: sepa_guarenteed_debit
Properties for Variant 1:
​AchBankDebitAdditionalData · required

BankDebitBilling

name
​string | null

The billing name for bank debits

Example: John Doe
email
​string | null

The billing email for bank debits

Example: example@example.com
​object

Address details

BankDebitData

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · requires: ach_bank_debit
type = object · requires: sepa_bank_debit
type = object · requires: sepa_guarenteed_bank_debit
type = object · requires: becs_bank_debit
type = object · requires: bacs_bank_debit
Properties for Variant 1:
​object · required

Payment Method data for Ach bank debit

BankDebitDetail

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · requires: ach
Properties for Variant 1:
​object · required

BankDebitResponse

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · requires: ach
type = object · requires: bacs
type = object · requires: becs
type = object · requires: sepa
type = object · requires: sepa_guarenteed_debit
Properties for Variant 1:
​AchBankDebitAdditionalData · required

BankDebitTypes

eligible_connectors
​string[] · required

BankHolderType

string · enum
Enum values:
personal
business

BankNames

string · enum
Enum values:
american_express
affin_bank
agro_bank
alliance_bank
am_bank
bank_of_america
bank_of_china
bank_islam

Name of banks supported by Hyperswitch

BankRedirect

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · requires: interac
type = object · requires: open_banking_uk
Properties for Variant 1:
​Interac · required

BankRedirectAdditionalData

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · requires: account_holder_name, iban
type = object
Properties for Variant 1:
Masked payout method details for OpenBankingUK bank redirect payout method
account_holder_name
​string · required

Account holder name

Example: John Doe
iban
​string · required

International Bank Account Number (iban) - used in many countries for identifying a bank along with it's customer.

Example: DE89370400440532013000

BankRedirectBilling

billing_name
​string · required

The name for which billing is issued

Example: John Doe
email
​string · required

The billing email for bank redirect

Example: example@example.com

BankRedirectData

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · requires: bancontact_card
type = object · requires: bizum
type = object · requires: blik
type = object · requires: eps
type = object · requires: giropay
type = object · requires: ideal
type = object · requires: interac
type = object · requires: online_banking_czech_republic
type = object · requires: online_banking_finland
type = object · requires: online_banking_poland
type = object · requires: online_banking_slovakia
type = object · requires: open_banking_uk
type = object · requires: przelewy24
type = object · requires: sofort
type = object · requires: trustly
type = object · requires: online_banking_fpx
type = object · requires: online_banking_thailand
type = object · requires: local_bank_redirect
type = object · requires: eft
type = object · requires: open_banking
Properties for Variant 1:
​object · required

BankRedirectDetails

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · requires: BancontactCard
type = object · requires: Blik
type = object · requires: Giropay
Properties for Variant 1:
​BancontactBankRedirectAdditionalData · required

BankRedirectResponse

bank_name
​string · enum

Name of banks supported by Hyperswitch

Enum values:
american_express
affin_bank
agro_bank
alliance_bank
am_bank
bank_of_america
bank_of_china
bank_islam
​object
oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · requires: BancontactCard
type = object · requires: Blik
type = object · requires: Giropay
Properties for Variant 1:
​BancontactBankRedirectAdditionalData · required

BankTransferAdditionalData

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · requires: ach
type = object · requires: sepa
type = object · requires: bacs
type = object · requires: multibanco
type = object · requires: permata
type = object · requires: bca
type = object · requires: bni_va
type = object · requires: bri_va
type = object · requires: cimb_va
type = object · requires: danamon_va
type = object · requires: mandiri_va
type = object · requires: pix
type = object · requires: pse
type = object · requires: local_bank_transfer
type = object · requires: instant_bank_transfer
type = object · requires: instant_bank_transfer_finland
type = object · requires: instant_bank_transfer_poland
type = object · requires: indonesian_bank_transfer
Properties for Variant 1:
ach
​object · required

BankTransferData

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · requires: ach_bank_transfer
type = object · requires: sepa_bank_transfer
type = object · requires: bacs_bank_transfer
type = object · requires: multibanco_bank_transfer
type = object · requires: permata_bank_transfer
type = object · requires: bca_bank_transfer
type = object · requires: bni_va_bank_transfer
type = object · requires: bri_va_bank_transfer
type = object · requires: cimb_va_bank_transfer
type = object · requires: danamon_va_bank_transfer
type = object · requires: mandiri_va_bank_transfer
type = object · requires: pix
type = object · requires: pse
type = object · requires: local_bank_transfer
type = object · requires: instant_bank_transfer
type = object · requires: instant_bank_transfer_finland
type = object · requires: instant_bank_transfer_poland
type = object · requires: indonesian_bank_transfer
Properties for Variant 1:
​object · required

BankTransferInstructions

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · requires: doku_bank_transfer_instructions
type = object · requires: ach_credit_transfer
type = object · requires: sepa_bank_instructions
type = object · requires: bacs_bank_instructions
type = object · requires: multibanco
Properties for Variant 1:
​DokuBankTransferInstructions · required

BankTransferNextStepsData

​object
oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · requires: doku_bank_transfer_instructions
type = object · requires: ach_credit_transfer
type = object · requires: sepa_bank_instructions
type = object · requires: bacs_bank_instructions
type = object · requires: multibanco
Properties for Variant 1:
​DokuBankTransferInstructions · required

BankTransferResponse

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · requires: ach
type = object · requires: sepa
type = object · requires: bacs
type = object · requires: multibanco
type = object · requires: permata
type = object · requires: bca
type = object · requires: bni_va
type = object · requires: bri_va
type = object · requires: cimb_va
type = object · requires: danamon_va
type = object · requires: mandiri_va
type = object · requires: pix
type = object · requires: pse
type = object · requires: local_bank_transfer
type = object · requires: instant_bank_transfer
type = object · requires: instant_bank_transfer_finland
type = object · requires: instant_bank_transfer_poland
type = object · requires: indonesian_bank_transfer
Properties for Variant 1:
ach
​object · required

BankTransferTypes

eligible_connectors
​string[] · required

The list of eligible connectors for a given payment experience

Example: ["stripe","adyen"]

BankType

string · enum
Enum values:
checking
savings

BecsBankDebitAdditionalData

account_number
​string · required

Partially masked account number for Becs payment method

Example: 0001****3456
bsb_number
​string · required

Bank-State-Branch (bsb) number

Example: 000000
bank_account_holder_name
​string | null

Bank account's owner name

Example: John Doe

BillingDescriptor

Billing Descriptor information to be sent to the payment gateway
name
​string | null

name to be put in billing description

Example: The Online Retailer
city
​string | null

city to be put in billing description

Example: San Francisco
phone
​string | null

phone to be put in billing description

Example: 9123456789
statement_descriptor
​string | null

a short description for the payment

statement_descriptor_suffix
​string | null

Concatenated with the prefix (shortened descriptor) or statement descriptor that’s set on the account to form the complete statement descriptor.

reference
​string | null

A reference to be shown on billing description

BillingFrequency

string · enum
Enum values:
month

Billing frequency for a card installment plan

BinGroupCreate

name
​string · required
bins
​string[] · required
description
​string | null

BinGroupDeleteResponse

id
​string · required
deleted
​boolean · required

BinGroupResponse

id
​string · required
organization_id
​string · required
name
​string · required
bins
​string[] · required
bin_count
​integer · int64 · required
created_at
​string · date-time · required
modified_at
​string · date-time · required
description
​string | null

BinGroupUpdate

name
​string | null
description
​string | null
bins
​array | null

BlikBankRedirectAdditionalData

blik_code
​string | null

BlocklistCardNumberPayload

card_number
​string · required
description
​string | null

BlocklistCardPanMaskedPayload

card_pan_bin
​string · required
card_pan_suffix
​string · required
description
​string | null

BlocklistDataKind

string · enum
Enum values:
payment_method
card_bin
extended_card_bin
email
card_number
card_pan_masked
phone

BlocklistEmailPayload

email
​string · required
description
​string | null

BlocklistPhonePayload

phone
​string · required
description
​string | null

BlocklistRequest

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · type="card_bin" · requires: data
type = object · type="fingerprint" · requires: data
type = object · type="extended_card_bin" · requires: data
type = object · type="email" · requires: data
type = object · type="card_number" · requires: data
type = object · type="card_pan_masked" · requires: data
type = object · type="phone" · requires: data
Properties for Variant 1:
type
​string · enum · required
Enum values:
card_bin
data
​string · required

BlocklistResponse

fingerprint_id
​string · required
data_kind
​BlocklistDataKind · enum · required
Enum values:
payment_method
card_bin
extended_card_bin
email
card_number
card_pan_masked
phone
created_at
​string · date-time · required
scope
​BlocklistScope · enum

Ownership scope for a blocklist entry (org / merchant / connector MCA).

Enum values:
organization
merchant
connector
merchant_connector_id
​string | null

Present only for connector scoped entries.

added_by
​string | null
description
​string | null
card_pan_bin
​string | null
card_pan_suffix
​string | null

BlocklistScope

string · enum
Enum values:
organization
merchant
connector

Ownership scope for a blocklist entry (org / merchant / connector MCA).

BlocklistScopeQuery

Query parameters carrying the ownership scope for blocklist write/read routes whose bodies are shared across scopes (create/delete/batch).
scope
​BlocklistScope · enum

Ownership scope for a blocklist entry (org / merchant / connector MCA).

Enum values:
organization
merchant
connector
merchant_connector_id
​string | null

Required when scope is connector.

BoletoAdditionalDetails

due_date
​string | null

Due Date for the Boleto

Example: 2026-12-31
document_kind
​string · enum
Enum values:
commercial_invoice
service_invoice
promissory_note
rural_promissory_note
receipt
insurance_policy
credit_card_invoice
proposal
payment_type
​string · enum
Enum values:
fixed_amount
flexible_amount
installment
covenant_code
​string | null
​

BoletoDocumentKind

string · enum
Enum values:
commercial_invoice
service_invoice
promissory_note
rural_promissory_note
receipt
insurance_policy
credit_card_invoice
proposal

BoletoPaymentType

string · enum
Enum values:
fixed_amount
flexible_amount
installment

BoletoVoucherData

social_security_number
​string | null

The shopper's social security number (CPF or CNPJ)

bank_number
​string | null

The shopper's bank account number associated with the boleto

document_type
​string · enum

Represents the type of identification document used for validation.

Enum values:
cpf
cnpj
fine_percentage
​string | null

The fine percentage charged if payment is overdue

fine_quantity_days
​string | null

The number of days after the due date when the fine is applied

interest_percentage
​string | null

The interest percentage charged on late payments

write_off_quantity_days
​string | null

The number of days after which the boleto is written off (canceled)

messages
​array | null

Custom messages or instructions to display on the boleto

due_date
​string | null · date

BraintreeData

merchant_account_id
​string · required

Information about the merchant_account_id that merchant wants to specify at connector level.

merchant_config_currency
​string · required

Information about the merchant_config_currency that merchant wants to specify at connector level.

BrowserInformation

Browser information to be used for 3DS 2.0
color_depth
​integer | null · int32 · min: 0

Color depth supported by the browser

java_enabled
​boolean | null

Whether java is enabled in the browser

java_script_enabled
​boolean | null

Whether javascript is enabled in the browser

language
​string | null

Language supported

screen_height
​integer | null · int32 · min: 0

The screen height in pixels

screen_width
​integer | null · int32 · min: 0

The screen width in pixels

time_zone
​integer | null · int32

Time zone of the client

ip_address
​string | null

Ip address of the client

accept_header
​string | null

List of headers that are accepted

Example: text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8
user_agent
​string | null

User-agent of the browser

os_type
​string | null

The os type of the client device

os_version
​string | null

The os version of the client device

device_model
​string | null

The device model of the client

accept_language
​string | null

Accept-language of the browser

referer
​string | null

Identifier of the source that initiated the request.

BusinessCollectLinkConfig

Object for GenericLinkUiConfig
allowed_domains
​string[] · unique · required

A list of allowed domains (glob patterns) where this link can be embedded / opened from

​EnabledPaymentMethod[] · required

List of payment methods shown on collect UI

Example: [{"payment_method": "bank_transfer", "payment_method_types": ["ach", "bacs", "sepa"]}]
logo
​string | null · maxLength: 255

Merchant's display logo

Example: https://hyperswitch.io/favicon.ico
merchant_name
​string | null · maxLength: 255

Custom merchant name for the link

Example: Hyperswitch
theme
​string | null · maxLength: 255

Primary color to be used in the form represented in hex format

Example: #4285F4
domain_name
​string | null

Custom domain name to be used for hosting the link

BusinessGenericLinkConfig

Object for GenericLinkUiConfig
allowed_domains
​string[] · unique · required

A list of allowed domains (glob patterns) where this link can be embedded / opened from

logo
​string | null · maxLength: 255

Merchant's display logo

Example: https://hyperswitch.io/favicon.ico
merchant_name
​string | null · maxLength: 255

Custom merchant name for the link

Example: Hyperswitch
theme
​string | null · maxLength: 255

Primary color to be used in the form represented in hex format

Example: #4285F4
domain_name
​string | null

Custom domain name to be used for hosting the link

BusinessPaymentLinkConfig

theme
​string | null · maxLength: 255

custom theme for the payment link

Example: #4E6ADD
logo
​string | null · maxLength: 255

merchant display logo

Example: https://i.pinimg.com/736x/4d/83/5c/4d835ca8aafbbb15f84d07d926fda473.jpg
seller_name
​string | null · maxLength: 255

Custom merchant name for payment link

Example: hyperswitch
sdk_layout
​string | null · maxLength: 255

Custom layout for sdk

Example: accordion
display_sdk_only
​boolean | null

Display only the sdk for payment link

Example: true
Default: false
enabled_saved_payment_method
​boolean | null

Enable saved payment method option for payment link

Example: true
Default: false
hide_card_nickname_field
​boolean | null

Hide card nickname field option for payment link

Example: true
Default: false
show_card_form_by_default
​boolean | null

Show card form by default for payment link

Example: true
Default: true
​array | null

Dynamic details related to merchant to be rendered in payment link

​object
details_layout
​string · enum
Enum values:
layout1
layout2
payment_button_text
​string | null

Text for payment link's handle confirm button

custom_message_for_card_terms
​string | null

Text for customizing message for card terms

​PaymentMethodConfig[]

List of custom T&C messages grouped by payment method

payment_button_colour
​string | null

Custom background colour for payment link's handle confirm button

skip_status_screen
​boolean | null

Skip the status screen after payment completion

payment_button_text_colour
​string | null

Custom text colour for payment link's handle confirm button

background_colour
​string | null

Custom background colour for the payment link

​object | null

SDK configuration rules

​object | null

Payment link configuration rules

enable_button_only_on_form_ready
​boolean | null

Flag to enable the button only when the payment form is ready for submission

payment_form_header_text
​string | null

Optional header for the SDK's payment form

payment_form_label_type
​string · enum
Enum values:
above
floating
never
show_card_terms
​string · enum
Enum values:
always
auto
never
is_setup_mandate_flow
​boolean | null

Boolean to control payment button text for setup mandate calls

color_icon_card_cvc_error
​string | null

Hex color for the CVC icon during error state

domain_name
​string | null

Custom domain name to be used for hosting the link in your own domain

​object | null

list of configs for multi theme setup

allowed_domains
​array | null · unique

A list of allowed domains (glob patterns) where this link can be embedded / opened from

branding_visibility
​boolean | null

Toggle for HyperSwitch branding visibility

BusinessPayoutLinkConfig

Object for GenericLinkUiConfig
allowed_domains
​string[] · unique · required

A list of allowed domains (glob patterns) where this link can be embedded / opened from

logo
​string | null · maxLength: 255

Merchant's display logo

Example: https://hyperswitch.io/favicon.ico
merchant_name
​string | null · maxLength: 255

Custom merchant name for the link

Example: Hyperswitch
theme
​string | null · maxLength: 255

Primary color to be used in the form represented in hex format

Example: #4285F4
domain_name
​string | null

Custom domain name to be used for hosting the link

form_layout
​string · enum
Enum values:
tabs
journey
payout_test_mode
​boolean | null

Allows for removing any validations / pre-requisites which are necessary in a production environment

Default: false

CancelOption

string · enum
Enum values:
immediately
end_of_term
specific_date

CancelSubscriptionRequest

Request payload for cancelling a subscription.
cancel_option
​string · enum
Enum values:
immediately
end_of_term
specific_date
cancel_at
​string | null

Optional date when the subscription should be cancelled (if not provided, cancels immediately)

unbilled_charges_option
​string · enum
Enum values:
invoice
delete
credit_option_for_current_term_charges
​string · enum
Enum values:
none
prorate
full
account_receivables_handling
​string · enum
Enum values:
no_action
schedule_payment_collection
write_off
refundable_credits_handling
​string · enum
Enum values:
no_action
schedule_refund
cancel_reason_code
​string | null

Reason code for canceling the subscription

CancelSubscriptionResponse

Response payload returned after successfully cancelling a subscription.
id
​SubscriptionId · required

A type for subscription_id that can be used for subscription ids

status
​SubscriptionStatus · enum · required

Possible states of a subscription lifecycle.

  • Created: Subscription was created but not yet activated.
  • Active: Subscription is currently active.
  • InActive: Subscription is inactive.
  • Pending: Subscription is pending activation.
  • Trial: Subscription is in a trial period.
  • Paused: Subscription is paused.
  • Unpaid: Subscription is unpaid.
  • Onetime: Subscription is a one-time payment.
  • Cancelled: Subscription has been cancelled.
  • Failed: Subscription has failed.
Enum values:
active
created
in_active
pending
trial
paused
unpaid
onetime
profile_id
​ProfileId · required

A type for profile_id that can be used for business profile ids

merchant_id
​MerchantId · required

A type for merchant_id that can be used for merchant ids

customer_id
​CustomerId · required

A type for customer_id that can be used for customer ids

merchant_reference_id
​string | null

Merchant specific Unique identifier.

cancelled_at
​string | null

Date when the subscription was cancelled

CaptureMethod

string · enum
Enum values:
automatic
manual
manual_multiple
scheduled
sequential_automatic

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.

CaptureResponse

capture_id
​string · required

A unique identifier for this specific capture operation.

status
​CaptureStatus · enum · required
Enum values:
started
charged
pending
failed
amount
​integer · int64 · 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.,

Example: 6540
connector
​string · required

The name of the payment connector that processed this capture.

authorized_attempt_id
​string · required

The ID of the payment attempt that was successfully authorized and subsequently captured by this operation.

capture_sequence
​integer · int32 · required

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

currency
​string · enum

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

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

A unique identifier for this capture provided by the connector

error_message
​string | null

A human-readable message from the connector explaining why this capture operation failed, if applicable.

error_code
​string | null

The error code returned by the connector if this capture operation failed. This code is connector-specific.

error_reason
​string | null

A more detailed reason from the connector explaining the capture failure, if available.

reference_id
​string | null

The connector's own reference or transaction ID for this specific capture operation. Useful for reconciliation.

CaptureStatus

string · enum
Enum values:
started
charged
pending
failed

Card

card_number
​string · required

The card number

Example: 4242424242424242
card_exp_month
​string · required

The card's expiry month

Example: 24
card_exp_year
​string · required

The card's expiry year

Example: 24
card_holder_name
​string · required

The card holder's name

Example: John Test
card_cvc
​string · required

The CVC number for the card

Example: 242
card_issuer
​string | null

The name of the issuer of card

Example: chase
card_network
​string · enum

Indicates the card network.

Enum values:
Visa
Mastercard
AmericanExpress
JCB
DinersClub
Discover
CartesBancaires
UnionPay
card_type
​string | null
card_issuing_country
​string | null
card_issuing_country_code
​string | null
bank_code
​string | null
nick_name
​string | null

The card holder's nick name

Example: John Test

CardAdditionalData

Masked payout method details for card payout method
card_exp_month
​string · required

Card expiry month

Example: 01
card_exp_year
​string · required

Card expiry year

Example: 2026
card_holder_name
​string · required

Card holder name

Example: John Doe
card_issuer
​string | null

Issuer of the card

card_network
​string · enum

Indicates the card network.

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

Card type, can be either credit or debit

card_issuing_country
​string | null

Card issuing country

bank_code
​string | null

Code for Card issuing bank

last4
​string | null

Last 4 digits of the card number

card_isin
​string | null

The ISIN of the card

card_extended_bin
​string | null

Extended bin of card, contains the first 8 digits of card number

CardBlockingConfig

Card-specific blocking configuration
issuing_country
​array | null

Set of issuing countries to block using ISO 3166-1 alpha-2 codes (e.g., ["IN", "US"])

Enum values:
AF
AX
AL
DZ
AS
AD
AO
AI
card_types
​array | null

Set of card types to block (e.g., ["Credit", "Debit"])

Enum values:
credit
debit
card_subtypes
​array | null

Set of card subtypes to block

Enum values:
aarp
airmilespremier
atmcard
atmonly
atmonly_cashlinecard
best_price_save_max
best_price_save_smart
bharat
issuers
​array | null · unique

Set of card issuer IDs to block

block_if_bin_info_unavailable
​boolean | null

Whether to block if BIN is provided but no matching record found in cards_info table. Defaults to false (allow payment if BIN not found in database).

CardDetail

card_number
​string · required

Card Number

Example: 4111111145551142
card_exp_month
​string · required

Card Expiry Month

Example: 10
card_exp_year
​string · required

Card Expiry Year

Example: 25
card_holder_name
​string · required

Card Holder Name

Example: John Doe
card_cvc
​string | null

Card CVC for Volatile Storage

Example: 123
nick_name
​string | null

Card Holder's Nick Name

Example: John Doe
card_issuing_country
​string | null

Card Issuing Country

card_issuing_country_code
​string | null

Card Issuing Country Code

card_network
​string · enum

Indicates the card network.

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

Issuer Bank for Card

card_type
​string | null

Card Type

CardDetailFromLocker

saved_to_locker
​boolean · required
scheme
​string | null
issuer_country
​string | null
issuer_country_code
​string | null
last4_digits
​string | null
expiry_month
​string | null
expiry_year
​string | null
card_token
​string | null
card_holder_name
​string | null
card_fingerprint
​string | null
nick_name
​string | null
card_network
​string · enum

Indicates the card network.

Enum values:
Visa
Mastercard
AmericanExpress
JCB
DinersClub
Discover
CartesBancaires
UnionPay
card_isin
​string | null
card_issuer
​string | null
card_type
​string | null

CardDetailUpdate

card_exp_month
​string · required

Card Expiry Month

Example: 10
card_exp_year
​string · required

Card Expiry Year

Example: 25
card_holder_name
​string · required

Card Holder Name

Example: John Doe
nick_name
​string | null

Card Holder's Nick Name

Example: John Doe
last4_digits
​string | null

Card's Last 4 Digits

Example: 1111
card_issuer
​string | null

Issuing Bank of the Particular Card

Example: Bank of America
issuer_country
​string | null

The country where that particular card was issued

Example: US
issuer_country_code
​string | null

The country code where that particular card was issued

Example: US
card_network
​string | null

The card network

Example: VISA

CardDiscovery

string · enum
Enum values:
manual
saved_card
click_to_pay

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

CardIssuerListQuery

query
​string | null

Optional search term to filter issuers by name (case-insensitive prefix match)

Example: hdfc
limit
​integer · int32 · min: 0 · max: 255

Maximum number of results to return (default: 30, max: 255)

Example: 30
Default: 30

CardIssuerListResponse

​CardIssuerResponse[] · required

CardIssuerRequest

issuer_name
​string · required

The name of the card issuer to add

Example: STATE BANK OF INDIA

CardIssuerResponse

id
​string · required
issuer_name
​string · required

CardIssuerUpdateRequest

issuer_name
​string · required

The new name for the card issuer

Example: STATE BANK OF INDIA UPDATED

CardNetwork

string · enum
Enum values:
Visa
Mastercard
AmericanExpress
JCB
DinersClub
Discover
CartesBancaires
UnionPay

Indicates the card network.

CardNetworkTokenizeRequest

merchant_id
​string · required

Merchant ID associated with the tokenization request

Example: merchant_1671528864
​CustomerDetails · required

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

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

payment_method_issuer
​string | null

The name of the bank/ provider issuing the payment method to the end user

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · requires: card
type = object · requires: existing_payment_method
Properties for Variant 1:
​TokenizeCardRequest · required

CardNetworkTokenizeResponse

​CustomerDetails · required

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

card_tokenized
​boolean · required

Card network tokenization status

​object
error_code
​string | null

Error code

error_message
​string | null

Error message

​

CardNetworkTypes

eligible_connectors
​string[] · required

The list of eligible connectors for a given card network

Example: ["stripe","adyen"]
card_network
​string · enum

Indicates the card network.

Enum values:
Visa
Mastercard
AmericanExpress
JCB
DinersClub
Discover
CartesBancaires
UnionPay
​object

CardPayout

card_number
​string · required

The card number

Example: 4242424242424242
expiry_month
​string · required

The card's expiry month

expiry_year
​string · required

The card's expiry year

card_holder_name
​string · required

The card holder's name

Example: John Doe
card_network
​string · enum

Indicates the card network.

Enum values:
Visa
Mastercard
AmericanExpress
JCB
DinersClub
Discover
CartesBancaires
UnionPay

CardRedirectData

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · requires: knet
type = object · requires: benefit
type = object · requires: momo_atm
type = object · requires: card_redirect
Properties for Variant 1:
knet
​object · required

CardRedirectResponse

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · requires: knet
type = object · requires: benefit
type = object · requires: momo_atm
type = object · requires: card_redirect
Properties for Variant 1:
knet
​object · required

CardResponse

last4
​string | null
card_type
​string | null
card_network
​string · enum

Indicates the card network.

Enum values:
Visa
Mastercard
AmericanExpress
JCB
DinersClub
Discover
CartesBancaires
UnionPay
card_issuer
​string | null
card_issuing_country
​string | null
card_isin
​string | null
card_extended_bin
​string | null
card_exp_month
​string | null
card_exp_year
​string | null
card_holder_name
​string | null
payment_checks
​
authentication_data
​
auth_code
​string | null

CardSpecificFeatures

three_ds
​FeatureStatus · enum · required

The status of the feature

Enum values:
not_supported
supported
no_three_ds
​FeatureStatus · enum · required

The status of the feature

Enum values:
not_supported
supported
supported_card_networks
​CardNetwork[] · required

List of supported card networks

Enum values:
Visa
Mastercard
AmericanExpress
JCB
DinersClub
Discover
CartesBancaires
UnionPay

CardSubtype

string · enum
Enum values:
aarp
airmilespremier
atmcard
atmonly
atmonly_cashlinecard
best_price_save_max
best_price_save_smart
bharat

CardTestingGuardConfig

card_ip_blocking_status
​CardTestingGuardStatus · enum · required
Enum values:
enabled
disabled
card_ip_blocking_threshold
​integer · int32 · required

Determines the unsuccessful payment threshold for Card IP Blocking for profile

guest_user_card_blocking_status
​CardTestingGuardStatus · enum · required
Enum values:
enabled
disabled
guest_user_card_blocking_threshold
​integer · int32 · required

Determines the unsuccessful payment threshold for Guest User Card Blocking for profile

customer_id_blocking_status
​CardTestingGuardStatus · enum · required
Enum values:
enabled
disabled
customer_id_blocking_threshold
​integer · int32 · required

Determines the unsuccessful payment threshold for Customer Id Blocking for profile

card_testing_guard_expiry
​integer · int32 · required

Determines Redis Expiry for Card Testing Guard for profile

​VelocityRule[]

Rule-list driven velocity checks for profile and terminal scopes.

​object
ip_mask_v4
​integer | null · int32 · min: 0

IPv4 prefix bits kept before the address enters any key. Defaults to 32.

ip_mask_v6
​integer | null · int32 · min: 0

IPv6 prefix bits kept. Defaults to 64.

CardTestingGuardStatus

string · enum
Enum values:
enabled
disabled

CardToken

card_holder_name
​string · required

The card holder's name

Example: John Test
card_cvc
​string | null

The CVC number for the card

CardTokenAdditionalData

card_holder_name
​string · required

The card holder's name

Example: John Test

CardTokenResponse

card_holder_name
​string · required

The card holder's name

Example: John Test

CardType

string · enum
Enum values:
credit
debit

CardWithLimitedData

card_number
​string · required

The card number

Example: 4242424242424242
card_exp_month
​string | null

The card's expiry month

Example: 24
card_exp_year
​string | null

The card's expiry year

Example: 24
card_holder_name
​string | null

The card holder's name

Example: John Test
eci
​string | null

The ECI(Electronic Commerce Indicator) value for this authentication.

CartesBancairesParams

Represents network-specific parameters for the Cartes Bancaires 3DS process.
cb_exemption
​string · required

Exemption indicator specific to Cartes Bancaires network (e.g., "low_value", "trusted_merchant")

cb_score
​integer · int32 · required

Cartes Bancaires risk score assigned during 3DS authentication.

cavv_algorithm
​string · enum

This is typically provided by the card network or Access Control Server (ACS)

Enum values:
00
01
02
03
04
A

CashappQr

CavvAlgorithm

string · enum
Enum values:
00
01
02
03
04
A

This is typically provided by the card network or Access Control Server (ACS)

ChargeRefunds

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

Identifier for charge created for the payment

revert_platform_fee
​boolean | null

Toggle for reverting the application fee that was collected for the payment. If set to false, the funds are pulled from the destination account.

revert_transfer
​boolean | null

Toggle for reverting the transfer that was made during the charge. If set to false, the funds are pulled from the main platform's account.

ChargesHandling

string · enum
Enum values:
invoice_immediately
add_to_unbilled_charges

ClickToPayDetails

merchant_transaction_id
​string | null

merchant transaction id

correlation_id
​string | null

network transaction correlation id

x_src_flow_id
​string | null

session transaction flow id

provider
​string · enum
Enum values:
visa
mastercard
encrypted_payload
​string | null

Encrypted payload

ClickToPayEligibilityCheckData

​object
​object

ClickToPayEligibilityCheckResponseData

visa
​boolean | null
mastercard
​boolean | null

ClickToPaySessionResponse

dpa_id
​string · required
dpa_name
​string · required
locale
​string · required
card_brands
​CardNetwork[] · required
Enum values:
Visa
Mastercard
AmericanExpress
JCB
DinersClub
Discover
CartesBancaires
UnionPay
Example: [Visa, Mastercard]
acquirer_bin
​string · required
acquirer_merchant_id
​string · required
merchant_country_code
​string · required
transaction_amount
​string · required
transaction_currency_code
​Currency · enum · required

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

Enum values:
AED
AFN
ALL
AMD
ANG
AOA
ARS
AUD
merchant_category_code
​string | null
phone_number
​string | null · maxLength: 255
email
​string | null · maxLength: 255
phone_country_code
​string | null
provider
​string · enum
Enum values:
visa
mastercard
dpa_client_id
​string | null

ClientSecret

string

For Client based calls, SDK will use the client_secret\nin order to call /payment_methods\nClient secret will be generated whenever a new\npayment method is created

CommissionRate

Tariff primitive: `fee = MAX(min, ceil(pct * base / 100) + fixed)`. `fixed` and `min` are minor units. JSON must keep both >= 0: a negative addend or floor credits the merchant instead of charging a fee. Percentage already rejects values outside 0–100; this type applies the same gate to the minor-unit fields so the API matches the dashboard form.
percentage
​string · required
fixed
​MinorUnit · int64 · required

This Unit struct represents MinorUnit in which core amount works

min
​MinorUnit · int64 · required

This Unit struct represents MinorUnit in which core amount works

Comparison

Represents a single comparison condition.
lhs
​string · required

The left hand side which will always be a domain input identifier like "payment.method.cardtype"

comparison
​ComparisonType · enum · required

Conditional comparison type

Enum values:
equal
not_equal
less_than
less_than_equal
greater_than
greater_than_equal
​ValueType · required

Represents a value in the DSL

​object · required

Additional metadata that the Static Analyzer and Backend does not touch. This can be used to store useful information for the frontend and is required for communication between the static analyzer and the frontend.

ComparisonType

string · enum
Enum values:
equal
not_equal
less_than
less_than_equal
greater_than
greater_than_equal

Conditional comparison type

ConfirmSubscriptionPaymentDetails

payment_method
​PaymentMethod · enum · required

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

Enum values:
card
card_redirect
pay_later
wallet
bank_redirect
bank_transfer
crypto
bank_debit
​object
​object
payment_method_type
​string · enum

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

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

The payment method information provided for making a payment

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

payment_type
​string · enum

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

Enum values:
normal
new_mandate
setup_mandate
recurring_mandate
installment
payment_token
​string | null

ConfirmSubscriptionRequest

​ConfirmSubscriptionPaymentDetails · required
client_secret
​string | null

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

ConfirmSubscriptionResponse

id
​SubscriptionId · required

A type for subscription_id that can be used for subscription ids

status
​SubscriptionStatus · enum · required

Possible states of a subscription lifecycle.

  • Created: Subscription was created but not yet activated.
  • Active: Subscription is currently active.
  • InActive: Subscription is inactive.
  • Pending: Subscription is pending activation.
  • Trial: Subscription is in a trial period.
  • Paused: Subscription is paused.
  • Unpaid: Subscription is unpaid.
  • Onetime: Subscription is a one-time payment.
  • Cancelled: Subscription has been cancelled.
  • Failed: Subscription has failed.
Enum values:
active
created
in_active
pending
trial
paused
unpaid
onetime
profile_id
​ProfileId · required

A type for profile_id that can be used for business profile ids

merchant_reference_id
​string | null

Merchant specific Unique identifier.

plan_id
​string | null

Identifier for the associated subscription plan.

item_price_id
​string | null

Identifier for the associated item_price_id for the subscription.

coupon
​string | null

Optional coupon code applied to this subscription.

​object
customer_id
​string

A type for customer_id that can be used for customer ids

​object
billing_processor_subscription_id
​string | null

Billing Processor subscription ID.

Connector

string · enum
Enum values:
flexifai
fiftyfourpay
honeycoin
k218pay
bitex
hypergate
maguapay
payadmit

ConnectorChargeResponseData

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · requires: stripe_split_payment
type = object · requires: adyen_split_payment
type = object · requires: xendit_split_payment
Properties for Variant 1:
​StripeChargeResponseData · required

Fee information to be charged on the payment being collected via Stripe

ConnectorCostConfigs

​object

Tariff primitive: fee = MAX(min, ceil(pct * base / 100) + fixed).

fixed and min are minor units. JSON must keep both >= 0: a negative addend or floor credits the merchant instead of charging a fee. Percentage already rejects values outside 0–100; this type applies the same gate to the minor-unit fields so the API matches the dashboard form.

ConnectorCostDecisionConfigReq

​ConnectorCostConfigs · required
name
​string | null
​object

ConnectorCostDecisionManagerRecord

name
​string · required
​ConnectorCostConfigs · required
​ProgramConnectorCostConfigs · required
created_at
​integer · int64 · required
modified_at
​integer · int64 · required

ConnectorFeatureMatrixResponse

name
​string · required

The name of the connector

display_name
​string · required

The display name of the connector

description
​string · required

The description of the connector

category
​HyperswitchConnectorCategory · enum · required

Connector Access Method

Enum values:
payment_gateway
alternative_payment_method
bank_acquirer
payout_processor
authentication_provider
fraud_and_risk_management_provider
tax_calculation_provider
revenue_growth_management_platform
integration_status
​ConnectorIntegrationStatus · enum · required

Connector Integration Status

Enum values:
live
sandbox
beta
alpha
base_url
​string | null

The base url of the connector

​array | null

The list of payment methods supported by the connector

supported_webhook_flows
​array | null

The list of webhook flows supported by the connector

Enum values:
payments
refunds
disputes
mandates
payouts
subscriptions

ConnectorIntegrationStatus

string · enum
Enum values:
live
sandbox
beta
alpha

Connector Integration Status

ConnectorMetadata

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

ConnectorMetadataResponse

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · requires: santander
Properties for Variant 1:
​SantanderData · required

ConnectorSelection

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · type="priority" · requires: data
type = object · type="volume_split" · requires: data
Properties for Variant 1:
type
​string · enum · required
Enum values:
priority
​RoutableConnectorChoice[] · required

ConnectorStatus

string · enum
Enum values:
inactive
active

ConnectorType

string · enum
Enum values:
payment_processor
payment_vas
fin_operations
fiz_operations
networks
banking_entities
non_banking_finance
payout_processor

Type of the Connector for the financial use case. Could range from Payments to Accounting to Banking.

ConnectorVolumeSplit

​RoutableConnectorChoice · required

Routable Connector chosen for a payment

split
​integer · int32 · min: 0 · required

ConnectorWalletDetails

apple_pay_combined
​object | null

This field contains the Apple Pay certificates and credentials for iOS and Web Apple Pay flow

apple_pay
​object | null

This field is for our legacy Apple Pay flow that contains the Apple Pay certificates and credentials for only iOS Apple Pay flow

amazon_pay
​object | null

This field contains the Amazon Pay certificates and credentials

samsung_pay
​object | null

This field contains the Samsung Pay certificates and credentials

paze
​object | null

This field contains the Paze certificates and credentials

google_pay
​object | null

This field contains the Google Pay certificates and credentials

ConnectorWebhookEventType

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = string
type = object · requires: specific_event
Properties for Variant 1:
string · enum
Enum values:
all_events

ConnectorWebhookRegisterRequest

Register a webhook at the connector
​

ContractBasedRoutingConfig

​object
​array | null

ContractBasedRoutingConfigBody

constants
​array | null
time_scale
​string · enum
Enum values:
day
month

ContractBasedTimeScale

string · enum
Enum values:
day
month

Country

string · enum
Enum values:
Afghanistan
AlandIslands
Albania
Algeria
AmericanSamoa
Andorra
Angola
Anguilla

CountryAlpha2

string · enum
Enum values:
AF
AX
AL
DZ
AS
AD
AO
AI

CountryAlpha3

string · enum
Enum values:
AFG
ALA
ALB
DZA
ASM
AND
AGO
AIA

CountryGroupCreate

name
​string · required
countries
​string[] · required
description
​string | null

CountryGroupDeleteResponse

id
​string · required
deleted
​boolean · required

CountryGroupResponse

id
​string · required
organization_id
​string · required
name
​string · required
countries
​string[] · required
country_count
​integer · int64 · required
created_at
​string · date-time · required
modified_at
​string · date-time · required
description
​string | null

CountryGroupUpdate

name
​string | null
description
​string | null
countries
​array | null

CreateAndConfirmSubscriptionRequest

item_price_id
​string · required

Identifier for the associated item_price_id for the subscription.

customer_id
​CustomerId · required

A type for customer_id that can be used for customer ids

​PaymentDetails · required
plan_id
​string | null

Identifier for the associated plan_id.

coupon_code
​string | null

Identifier for the coupon code for the subscription.

​object
​object
merchant_reference_id
​string | null

Merchant specific Unique identifier.

CreateApiKeyRequest

The request body for creating an API Key.
name
​string · maxLength: 64 · required

A unique name for the API Key to help you identify it.

Example: Sandbox integration key
​ApiKeyExpiration · required
​ApiKeyPermissionGrant[] · required

JSON column value: explicit non-empty grants for the key.

description
​string | null · maxLength: 256

A description to provide more context about the API Key.

Example: Key used by our developers to integrate with the sandbox environment
organization_id
​string | null

Create an organization-owned API key instead of a merchant-owned key.

tenant_id
​string | null

Create a tenant-owned API key instead of a merchant-owned key.

whitelisted_ips
​array | null

Whitelisted IP addresses for this key. Omit or pass an empty list to allow all IPs.

CreateApiKeyResponse

The response body for creating an API Key.
key_id
​string · maxLength: 64 · required

The identifier for the API Key.

Example: 5hEEqkgJUyuxgSKGArHA4mWSnX
name
​string · maxLength: 64 · required

The unique name for the API Key to help you identify it.

Example: Sandbox integration key
api_key
​string · maxLength: 128 · required

The plaintext API Key used for server-side API access. Ensure you store the API Key securely as you will not be able to see it again.

created
​string · date-time · required

The time at which the API Key was created.

Example: 2022-09-10T10:11:12Z
​ApiKeyExpiration · required
​ApiKeyPermissionGrant[] · required

JSON column value: explicit non-empty grants for the key.

merchant_id
​string | null · maxLength: 64

The identifier for the Merchant Account.

Example: y3oqhf46pyzuxjbcn2giaqnb44
organization_id
​string | null

The identifier for the Organization Account.

tenant_id
​string | null

The identifier for the Tenant.

description
​string | null · maxLength: 256

The description to provide more context about the API Key.

Example: Key used by our developers to integrate with the sandbox environment
whitelisted_ips
​array | null

Whitelisted IP addresses for this key. Empty or absent means all IPs are allowed.

CreateDisputeRequest

payment_id
​string · required

The payment against which the dispute is raised

amount
​MinorUnit · int64 · required

This Unit struct represents MinorUnit in which core amount works

connector_dispute_id
​string | null

External reference for the dispute (e.g. bank chargeback id). Generated if omitted.

dispute_stage
​string · enum

Stage of the dispute

Enum values:
pre_dispute
dispute
pre_arbitration
arbitration
dispute_reversal
connector_reason
​string | null

Reason of dispute

connector_reason_code
​string | null

Reason code of dispute

challenge_required_by
​string | null · date-time

Evidence deadline

CreateSubscriptionPaymentDetails

return_url
​string · required

The url to which user must be redirected to after completion of the purchase

setup_future_usage
​string · enum

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

  • off_session: The payment method can be used for future payments when the customer is not present.
  • on_session: The payment method is intended for use only when the customer is present during checkout. If omitted, defaults to on_session.
Enum values:
off_session
on_session
capture_method
​string · enum

Specifies how the payment is captured.

  • automatic: Funds are captured immediately after successful authorization. This is the default behavior if the field is omitted.
  • manual: Funds are authorized but not captured. A separate request to the /payments/{payment_id}/capture endpoint is required to capture the funds.
Enum values:
automatic
manual
manual_multiple
scheduled
sequential_automatic
authentication_type
​string · enum

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

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

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

Enum values:
three_ds
no_three_ds
payment_type
​string · enum

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

Enum values:
normal
new_mandate
setup_mandate
recurring_mandate
installment

CreateSubscriptionRequest

Request payload for creating a subscription. This struct captures details required to create a subscription, including plan, profile, merchant connector, and optional customer info.
item_price_id
​string · required

Identifier for the associated item_price_id for the subscription.

customer_id
​CustomerId · required

A type for customer_id that can be used for customer ids

​CreateSubscriptionPaymentDetails · required
merchant_reference_id
​string | null

Merchant specific Unique identifier.

plan_id
​string | null

Identifier for the subscription plan.

coupon_code
​string | null

Optional coupon code applied to the subscription.

​object
​object

CreditOption

string · enum
Enum values:
none
prorate
full

CryptoData

pay_currency
​string | null
network
​string | null

CryptoResponse

pay_currency
​string | null
network
​string | null

Cryptogram

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · requires: cavv
Properties for Variant 1:
​object · required

Cardholder Authentication Verification Value (CAVV) cryptogram.

CtpServiceDetails

merchant_transaction_id
​string | null

merchant transaction id

correlation_id
​string | null

network transaction correlation id

x_src_flow_id
​string | null

session transaction flow id

provider
​string · enum
Enum values:
visa
mastercard
encrypted_payload
​string | null

Encrypted payload

CtpServiceProvider

string · enum
Enum values:
visa
mastercard

Currency

string · enum
Enum values:
AED
AFN
ALL
AMD
ANG
AOA
ARS
AUD

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

CurrentBlockThreshold

duration_in_mins
​integer | null · int64 · min: 0
max_total_count
​integer | null · int64 · min: 0

CustomMessage

Custom T&C message content and display mode
value
​string · required

The text to be shown per payment method type

Example: I authorize Novalnet AG to debit my account.
display_mode
​SdkDisplayMode · enum

Display mode options for controlling how messages are shown.

Enum values:
default_sdk_message
custom_message
hidden

CustomTerms

Custom T&C message for a specific payment method type
payment_method_type
​PaymentMethodType · enum · required

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

Enum values:
ach
affirm
afterpay_clearpay
alfamart
ali_pay
ali_pay_hk
alma
amazon_pay
​CustomMessage · required

Custom T&C message content and display mode

CustomerAcceptance

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.
acceptance_type
​AcceptanceType · enum · required

This is used to indicate if the mandate was accepted online or offline

Enum values:
online
offline
accepted_at
​string | null · date-time

Specifying when the customer acceptance was provided

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

Details of online mandate

CustomerDefaultPaymentMethodResponse

customer_id
​string · minLength: 1 · maxLength: 64 · required

The unique identifier of the customer.

Example: cus_y3oqhf46pyzuxjbcn2giaqnb44
payment_method
​PaymentMethod · enum · required

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

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

The unique identifier of the Payment method

Example: card_rGK4Vi5iSW70MY7J2mIg
payment_method_type
​string · enum

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

Enum values:
ach
affirm
afterpay_clearpay
alfamart
ali_pay
ali_pay_hk
alma
amazon_pay

CustomerDeleteResponse

customer_id
​string · maxLength: 255 · required

The identifier for the customer object

Example: cus_y3oqhf46pyzuxjbcn2giaqnb44
customer_deleted
​boolean · required

Whether customer was deleted or not

Example: false
address_deleted
​boolean · required

Whether address was deleted or not

Example: false
payment_methods_deleted
​boolean · required

Whether payment methods deleted or not

Example: false

CustomerDetails

Passing this object creates a new customer or attaches an existing customer to the payment
id
​string | null · minLength: 1 · maxLength: 64

The identifier for the customer.

Example: cus_y3oqhf46pyzuxjbcn2giaqnb44
name
​string | null · maxLength: 255

The customer's name

Example: John Doe
email
​string | null · maxLength: 255

The customer's email address

Example: johntest@test.com
phone
​string | null · maxLength: 10

The customer's phone number

Example: 9123456789
phone_country_code
​string | null · maxLength: 2

The country code for the customer's phone number

Example: +1
tax_registration_id
​string | null · maxLength: 255

The tax registration identifier of the customer.

​object

CustomerDetailsResponse

Details of customer attached to this payment
id
​string | null · minLength: 1 · maxLength: 64

The identifier for the customer.

Example: cus_y3oqhf46pyzuxjbcn2giaqnb44
name
​string | null · maxLength: 255

The customer's name

Example: John Doe
email
​string | null · maxLength: 255

The customer's email address

Example: johntest@test.com
phone
​string | null · maxLength: 10

The customer's phone number

Example: 9123456789
phone_country_code
​string | null · maxLength: 2

The country code for the customer's phone number

Example: +1
​object

CustomerDeviceData

Represents data about the customer's device used in the 3DS decision rule.
platform
​string · enum
Enum values:
web
android
ios
device_type
​string · enum
Enum values:
mobile
tablet
desktop
gaming_console
display_size
​string · enum
Enum values:
size320x568
size375x667
size390x844
size414x896
size428x926
size768x1024
size834x1112
size834x1194

CustomerDeviceDisplaySize

string · enum
Enum values:
size320x568
size375x667
size390x844
size414x896
size428x926
size768x1024
size834x1112
size834x1194

CustomerDevicePlatform

string · enum
Enum values:
web
android
ios

CustomerDeviceType

string · enum
Enum values:
mobile
tablet
desktop
gaming_console

CustomerDocumentDetails

document_type
​DocumentKind · enum · required

Represents the type of identification document used for validation.

Enum values:
cpf
cnpj
document_number
​string · maxLength: 255 · required

The customer's document number Length of the document number depends upon the document_type. For CPF/CNPJ it is typically 11/14 digits long

Example: 12345678911

CustomerExternalStats

Merchant-provided customer statistics for advanced routing. All fields are optional.
date_of_first_deposit
​string | null · date

First deposit date in the merchant's system (ISO 8601 date, e.g. YYYY-MM-DD).

Example: 2024-03-15
deposits_cnt
​integer | null · int64 · min: 0
deposits_amount
​integer | null · int64
withdrawals_cnt
​integer | null · int64 · min: 0
withdrawals_amount
​integer | null · int64
kyc_status
​string · enum

KYC level provided by the merchant for external customer statistics (routing).

Enum values:
none
partial
complete

CustomerId

string

A type for customer_id that can be used for customer ids

CustomerPaymentMethod

payment_token
​string · required

Token for payment method in temporary card locker which gets refreshed often

Example: 7ebf443f-a050-4067-84e5-e6f6d4800aef
payment_method_id
​string · required

The unique identifier of the customer.

Example: pm_iouuy468iyuowqs
customer_id
​string · minLength: 1 · maxLength: 64 · required

The unique identifier of the customer.

Example: cus_y3oqhf46pyzuxjbcn2giaqnb44
payment_method
​PaymentMethod · enum · required

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

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

Whether this payment method requires CVV to be collected

Example: true
default_payment_method_set
​boolean · required

Indicates if the payment method has been set to default or not

Example: true
payment_method_type
​string · enum

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

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

The name of the bank/ provider issuing the payment method to the end user

Example: Citibank
payment_method_issuer_code
​string · enum
Enum values:
jp_hdfc
jp_icici
jp_googlepay
jp_applepay
jp_phonepay
jp_wechat
jp_sofort
jp_giropay
recurring_enabled
​boolean | null

Indicates whether the payment method supports recurring payments. Optional.

Example: true
installment_payment_enabled
​boolean | null

Indicates whether the payment method is eligible for installment payments (e.g., EMI, BNPL). Optional.

Example: true
payment_experience
​array | null

Type of payment experience enabled with the connector

Enum values:
redirect_to_url
invoke_sdk_client
display_qr_code
one_click
link_wallet
invoke_payment_app
display_wait_screen
collect_otp
Example: ["redirect_to_url"]
​object
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.

created
​string | null · date-time

A timestamp (ISO 8601 code) that determines when the payment method was created

Example: 2023-01-18T11:04:09.922Z
​
​object
​object
last_used_at
​string | null · date-time

A timestamp (ISO 8601 code) that determines when the payment method was last used

Example: 2024-02-24T11:04:09.922Z
​object

CustomerPaymentMethodUpdateResponse

merchant_id
​string · required

Unique identifier for a merchant

Example: merchant_1671528864
payment_method_id
​string · required

The unique identifier of the Payment method

Example: card_rGK4Vi5iSW70MY7J2mIg
payment_method
​PaymentMethod · enum · required

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

Enum values:
card
card_redirect
pay_later
wallet
bank_redirect
bank_transfer
crypto
bank_debit
customer_id
​string | null · minLength: 1 · maxLength: 64

The unique identifier of the customer.

Example: cus_y3oqhf46pyzuxjbcn2giaqnb44
payment_method_type
​string · enum

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

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

Indicates whether the payment method supports recurring payments. Optional.

Example: true
installment_payment_enabled
​boolean | null

Indicates whether the payment method is eligible for installment payments (e.g., EMI, BNPL). Optional.

Example: true
payment_experience
​array | null

Type of payment experience enabled with the connector

Enum values:
redirect_to_url
invoke_sdk_client
display_qr_code
one_click
link_wallet
invoke_payment_app
display_wait_screen
collect_otp
Example: ["redirect_to_url"]
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.

created
​string | null · date-time

A timestamp (ISO 8601 code) that determines when the payment method was created

Example: 2023-01-18T11:04:09.922Z
​
last_used_at
​string | null · date-time
client_secret
​string | null

For Client based calls

CustomerPaymentMethodsListResponse

​CustomerPaymentMethod[] · required

List of payment methods for customer

is_guest_customer
​boolean | null

Returns whether a customer id is not tied to a payment intent (only when the request is made against a client secret)

CustomerRequest

The customer details
customer_id
​string | null · minLength: 1 · maxLength: 64

The identifier for the customer object. If not provided the customer ID will be autogenerated.

Example: cus_y3oqhf46pyzuxjbcn2giaqnb44
name
​string | null · maxLength: 255

The customer's name

Example: Jon Test
email
​string | null · maxLength: 255

The customer's email address

Example: JonTest@test.com
phone
​string | null · maxLength: 255

The customer's phone number

Example: 9123456789
description
​string | null · maxLength: 255

An arbitrary string that you can attach to a customer object.

Example: First Customer
phone_country_code
​string | null · maxLength: 255

The country code for the customer phone number

Example: +65
​object

Address details

metadata
​object | null

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

tax_registration_id
​string | null · maxLength: 255

Customer's tax registration ID

Example: 123456789
​object

CustomerResponse

customer_id
​string · minLength: 1 · maxLength: 64 · required

The identifier for the customer object

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

A timestamp (ISO 8601 code) that determines when the customer was created

Example: 2023-01-18T11:04:09.922Z
name
​string | null · maxLength: 255

The customer's name

Example: Jon Test
email
​string | null · maxLength: 255

The customer's email address

Example: JonTest@test.com
phone
​string | null · maxLength: 255

The customer's phone number

Example: 9123456789
phone_country_code
​string | null · maxLength: 255

The country code for the customer phone number

Example: +65
description
​string | null · maxLength: 255

An arbitrary string that you can attach to a customer object.

Example: First Customer
​object

Address details

metadata
​object | null

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

default_payment_method_id
​string | null · maxLength: 64

The identifier for the default payment method.

Example: pm_djh2837dwduh890123
tax_registration_id
​string | null · maxLength: 255

The customer's tax registration number.

Example: 123456789
​object

CustomerStatisticsItem

Statistics for a customer within a single profile
profile_id
​string · required

Profile identifier

payments_count
​integer · int64 · required

Total number of payments (deposits)

payments_amount
​integer · int64 · required

Total amount of payments (in smallest currency unit)

refunds_count
​integer · int64 · required

Total number of refunds

refunds_amount
​integer · int64 · required

Total amount of refunds (in smallest currency unit)

payouts_count
​integer · int64 · required

Total number of successful payouts (withdrawals)

payouts_amount
​integer · int64 · required

Total amount of successful payouts (in smallest currency unit)

profile_name
​string | null

Profile name (human-readable)

first_successful_payment_at
​string | null

Timestamp of the first successful payment (deposit)

currency
​string · enum

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

Enum values:
AED
AFN
ALL
AMD
ANG
AOA
ARS
AUD

CustomerStatisticsResponse

Statistics for a customer aggregated per profile
​CustomerStatisticsItem[] · required

List of statistics items per profile

forex_available
​boolean · required

Whether forex rates were available for currency conversion. When false, amounts are in original currencies and cannot be summed correctly across currencies.

CustomerUpdateRequest

The identifier for the customer object. If not provided the customer ID will be autogenerated.
name
​string | null · maxLength: 255

The customer's name

Example: Jon Test
email
​string | null · maxLength: 255

The customer's email address

Example: JonTest@test.com
phone
​string | null · maxLength: 255

The customer's phone number

Example: 9123456789
description
​string | null · maxLength: 255

An arbitrary string that you can attach to a customer object.

Example: First Customer
phone_country_code
​string | null · maxLength: 255

The country code for the customer phone number

Example: +65
​object

Address details

metadata
​object | null

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

tax_registration_id
​string | null · maxLength: 255

Customer's tax registration ID

Example: 123456789
​object

DeRoutableConnectorChoice

Connector representation used in API request/response. Represents a Merchant Connector Account.
gateway_name
​RoutableConnectors · enum · required

RoutableConnectors are the subset of Connectors that are eligible for payments routing

Enum values:
flexifai
fiftyfourpay
k218pay
bitex
hypergate
maguapay
payadmit
milkypay
gateway_id
​string · required

Merchant Connector Account ID.

Example:

JSONCode
"mca_ExbsYfO1xFErhNtwY1PX"
Example: authipay_1705

DecideGatewayResponse

decided_gateway
​string | null

The gateway decided by the routing engine

Example: stripe:mca1
​object | null

Map of gateways with their priority scores

Example: {"adyen:mca2":1,"stripe:mca1":1}
filter_wise_gateways
​object | null

Gateways organized by filter criteria

priority_logic_tag
​string | null

Tag identifying the priority logic used

routing_approach
​string | null

The routing approach used for decision making

Example: SR_SELECTION_V3_ROUTING
gateway_before_evaluation
​string | null

The gateway that was evaluated before the final decision

Example: adyen:mca2
​object
reset_approach
​string | null

The reset approach applied during routing

Example: NO_RESET
routing_dimension
​string | null

Dimensions used for routing decision (payment type, method, etc.)

Example: ORDER_PAYMENT, UPI, upi
routing_dimension_level
​string | null

Level at which routing dimension is evaluated

Example: PM_LEVEL
is_scheduled_outage
​boolean | null

Indicates if routing decision was affected by scheduled outage

Example: false
is_dynamic_mga_enabled
​boolean | null

Indicates if dynamic merchant gateway account is enabled

Example: false
gateway_mga_id_map
​object | null

Map of gateways to their MGA IDs

DecisionEngineEliminationData

threshold
​number · double · required

Threshold for elimination logic in gateway selection

Example: 0.3

DecisionEngineGatewayWiseExtraScore

gatewayName
​string · required
gatewaySigmaFactor
​number · double · required

DecisionEngineSRSubLevelInputConfig

Payment method level configuration for success rate based routing
paymentMethodType
​string | null

Payment method type (e.g., "card", "wallet")

Example: card
paymentMethod
​string | null

Specific payment method (e.g., "credit", "debit")

Example: credit
latencyThreshold
​number | null · double

Latency threshold in percentile for this payment method

Example: 90
bucketSize
​integer | null · int32

Number of transactions to consider for this payment method

Example: 100
hedgingPercent
​number | null · double

Percentage of traffic to route for exploration for this payment method

Example: 5
lowerResetFactor
​number | null · double

Lower reset factor for this payment method

Example: 0.5
upperResetFactor
​number | null · double

Upper reset factor for this payment method

Example: 1.5
​array | null

Gateway-specific extra scoring factors for this payment method

DecisionEngineSuccessRateData

Configuration for Decision Engine success rate based routing
defaultLatencyThreshold
​number | null · double

Default latency threshold in percentile for gateway selection

Example: 90
defaultBucketSize
​integer | null · int32

Default number of transactions to consider for success rate calculation

Example: 100
defaultHedgingPercent
​number | null · double

Default percentage of traffic to route for exploration/hedging

Example: 5
defaultLowerResetFactor
​number | null · double

Lower reset factor for adjusting gateway scores

Example: 0.5
defaultUpperResetFactor
​number | null · double

Upper reset factor for adjusting gateway scores

Example: 1.5
​array | null

Gateway-specific extra scoring factors

​array | null

Payment method level specific configurations

DecoupledAuthenticationType

string · enum
Enum values:
challenge
frictionless

DefaultPaymentMethod

customer_id
​string · minLength: 1 · maxLength: 64 · required
payment_method_id
​string · required

DeleteFromBlocklistBatchRequest

​DeleteFromBlocklistRequest[] · required

DeleteFromBlocklistRequest

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · type="card_bin" · requires: data
type = object · type="fingerprint" · requires: data
type = object · type="extended_card_bin" · requires: data
type = object · type="email" · requires: data
type = object · type="card_number" · requires: data
type = object · type="card_pan_masked" · requires: data
type = object · type="phone" · requires: data
Properties for Variant 1:
type
​string · enum · required
Enum values:
card_bin
data
​string · required

DeleteFromWhitelistBatchRequest

​DeleteFromWhitelistRequest[] · required

DeleteFromWhitelistRequest

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · type="card_bin" · requires: data
type = object · type="fingerprint" · requires: data
type = object · type="extended_card_bin" · requires: data
type = object · type="email" · requires: data
type = object · type="card_number" · requires: data
type = object · type="card_pan_masked" · requires: data
type = object · type="phone" · requires: data
Properties for Variant 1:
type
​string · enum · required
Enum values:
card_bin
data
​string · required

DeviceChannel

string · enum
Enum values:
APP
BRW

Device Channel indicating whether request is coming from App or Browser

DeviceDetails

Device details for collecting Device information
device_type
​string | null

Device type

device_brand
​string | null

Device brand

device_os
​string | null

Device OS

device_display
​string | null

Device display

DisplayAmountOnSdk

net_amount
​string · required

net amount = amount + order_tax_amount + shipping_cost

order_tax_amount
​string · required

order tax amount calculated by tax connectors

shipping_cost
​string · required

shipping cost for the order

DisputeListFilterConstraints

A type representing a range of time for filtering, including a mandatory start time and an optional end time.
start_time
​string · date-time · required

The start time to filter payments list or to get list of filters. To get list of filters start time is needed to be passed

end_time
​string | null · date-time

The end time to filter payments list or to get list of filters. If not passed the default time is now

dispute_id
​string | null

The identifier for dispute

payment_id
​string

A type for payment_id that can be used for payment ids

limit
​integer | null · int32 · min: 0

Limit on the number of objects to return

offset
​integer | null · int32 · min: 0

The starting point within a list of object

profile_id
​string | null

The identifier for business profile

dispute_status
​array | null

The list of status of the disputes

Enum values:
dispute_opened
dispute_expired
dispute_accepted
dispute_cancelled
dispute_challenged
dispute_won
dispute_lost
dispute_stage
​array | null

The list of stages of the disputes

Enum values:
pre_dispute
dispute
pre_arbitration
arbitration
dispute_reversal
reason
​string | null

Reason for the dispute

connector
​array | null

The list of connectors linked to disputes

currency
​array | null

The list of currencies of the disputes

Enum values:
AED
AFN
ALL
AMD
ANG
AOA
ARS
AUD
merchant_connector_id
​string

A type for merchant_connector_id that can be used for merchant_connector_account ids

​object[]

Column predicates. Combined with other fields using AND.

DisputeListResponse

count
​integer · min: 0 · required

The number of disputes included in the current response

total_count
​integer · int64 · required

The total number of available disputes for given constraints

​DisputeResponse[] · required

The list of dispute response objects

DisputeManualUpdateRequest

dispute_status
​DisputeStatus · enum · required

Status of the dispute

Enum values:
dispute_opened
dispute_expired
dispute_accepted
dispute_cancelled
dispute_challenged
dispute_won
dispute_lost
dispute_stage
​string · enum

Stage of the dispute

Enum values:
pre_dispute
dispute
pre_arbitration
arbitration
dispute_reversal
transition_reason
​string | null

Human-readable reason for the manual transition (stored in transition_reason column)

DisputeManualUpdateResponse

dispute_id
​string · required

The identifier for dispute

payment_id
​string · required

The identifier for payment_intent

dispute_stage
​DisputeStage · enum · required

Stage of the dispute

Enum values:
pre_dispute
dispute
pre_arbitration
arbitration
dispute_reversal
dispute_status
​DisputeStatus · enum · required

Status of the dispute

Enum values:
dispute_opened
dispute_expired
dispute_accepted
dispute_cancelled
dispute_challenged
dispute_won
dispute_lost
transition_reason
​string | null

Human-readable reason for the manual transition

DisputeResponse

dispute_id
​string · required

The identifier for dispute

payment_id
​string · required

The identifier for payment_intent

attempt_id
​string · required

The identifier for payment_attempt

amount
​StringMinorUnit · required

Connector specific types to send

currency
​Currency · enum · required

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

Enum values:
AED
AFN
ALL
AMD
ANG
AOA
ARS
AUD
dispute_stage
​DisputeStage · enum · required

Stage of the dispute

Enum values:
pre_dispute
dispute
pre_arbitration
arbitration
dispute_reversal
dispute_status
​DisputeStatus · enum · required

Status of the dispute

Enum values:
dispute_opened
dispute_expired
dispute_accepted
dispute_cancelled
dispute_challenged
dispute_won
dispute_lost
connector
​string · required

connector to which dispute is associated with

connector_status
​string · required

Status of the dispute sent by connector

connector_dispute_id
​string · required

Dispute id sent by connector

created_at
​string · date-time · required

Time at which dispute is received

is_already_refunded
​boolean · required

Shows if the disputed amount(dispute_lost statuses only) + refunded amount is greater than captured amount

is_manual
​boolean · required

Whether the dispute was created manually through the dashboard or API

connector_reason
​string | null

Reason of dispute sent by connector

connector_reason_code
​string | null

Reason code of dispute sent by connector

challenge_required_by
​string | null · date-time

Evidence deadline of dispute sent by connector

connector_created_at
​string | null · date-time

Dispute created time sent by connector

connector_updated_at
​string | null · date-time

Dispute updated time sent by connector

profile_id
​string | null

The profile_id associated with the dispute

merchant_connector_id
​string | null

The merchant_connector_id of the connector / processor through which the dispute was processed

DisputeResponsePaymentsRetrieve

dispute_id
​string · required

The identifier for dispute

amount
​StringMinorUnit · required

Connector specific types to send

dispute_stage
​DisputeStage · enum · required

Stage of the dispute

Enum values:
pre_dispute
dispute
pre_arbitration
arbitration
dispute_reversal
dispute_status
​DisputeStatus · enum · required

Status of the dispute

Enum values:
dispute_opened
dispute_expired
dispute_accepted
dispute_cancelled
dispute_challenged
dispute_won
dispute_lost
connector_status
​string · required

Status of the dispute sent by connector

connector_dispute_id
​string · required

Dispute id sent by connector

created_at
​string · date-time · required

Time at which dispute is received

connector_reason
​string | null

Reason of dispute sent by connector

connector_reason_code
​string | null

Reason code of dispute sent by connector

challenge_required_by
​string | null · date-time

Evidence deadline of dispute sent by connector

connector_created_at
​string | null · date-time

Dispute created time sent by connector

connector_updated_at
​string | null · date-time

Dispute updated time sent by connector

DisputeStage

string · enum
Enum values:
pre_dispute
dispute
pre_arbitration
arbitration
dispute_reversal

Stage of the dispute

DisputeStatus

string · enum
Enum values:
dispute_opened
dispute_expired
dispute_accepted
dispute_cancelled
dispute_challenged
dispute_won
dispute_lost

Status of the dispute

DisputeTableField

string · enum
Enum values:
dispute_id
payment_id
amount
currency
dispute_stage
dispute_status
connector
connector_status

Dispute table columns.

DocumentDetails

document_number
​string · required

Cpf or Cnpj number

Example: 20201210000155
document_type
​string · enum

Represents the type of identification document used for validation.

Enum values:
cpf
cnpj

DocumentKind

string · enum
Enum values:
cpf
cnpj

Represents the type of identification document used for validation.

DokuBankTransferInstructions

expires_at
​string · required
reference
​string · required
instructions_url
​string · required

DokuBillingDetails

first_name
​string | null

The billing first name for Doku

Example: Jane
last_name
​string | null

The billing second name for Doku

Example: Doe
email
​string | null

The Email ID for Doku billing

Example: example@me.com

DynamicRoutingAlgorithm

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · requires: decision_engine_configs
type = object · requires: decision_engine_configs
type = object
Properties for Variant 1:
​DecisionEngineEliminationData · required
​object

DynamicRoutingConfigParams

string · enum
Enum values:
PaymentMethod
PaymentMethodType
AuthenticationType
Currency
Country
CardNetwork
CardBin

DynamicRoutingFeatures

string · enum
Enum values:
metrics
dynamic_connector_selection
none

ElementPosition

string · enum
Enum values:
left
top left
top
top right
right
bottom right
bottom
bottom left

ElementSize

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · requires: Variants
type = object · requires: Percentage
type = object · requires: Pixels
Properties for Variant 1:
Variants
​SizeVariants · enum · required
Enum values:
cover
contain

EligibilityCard

Card data for eligibility check — only card_number is required, no CVV needed
card_number
​string · required

The card number

Example: 4242424242424242
card_exp_month
​string | null

The card's expiry month

Example: 24
card_exp_year
​string | null

The card's expiry year

Example: 24
card_cvc
​string | null

The card's CVC/CVV

Example: 123
card_holder_name
​string | null

The card holder's name

Example: John Test
card_issuer
​string | null

The name of the issuer of card

Example: chase
card_network
​string · enum

Indicates the card network.

Enum values:
Visa
Mastercard
AmericanExpress
JCB
DinersClub
Discover
CartesBancaires
UnionPay
card_type
​string | null
card_issuing_country
​string | null
card_issuing_country_code
​string | null
bank_code
​string | null
nick_name
​string | null

The card holder's nick name

Example: John Test

EligibilityPaymentMethodData

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · requires: card
type = object · requires: card_redirect
type = object · requires: wallet
type = object · requires: pay_later
type = object · requires: bank_redirect
type = object · requires: bank_debit
type = object · requires: bank_transfer
type = object · requires: real_time_payment
type = object · requires: crypto
type = string
type = string
type = object · requires: upi
type = object · requires: voucher
type = object · requires: gift_card
type = object · requires: card_token
type = object · requires: open_banking
type = object · requires: mobile_payment
type = object · requires: network_token
Properties for EligibilityCard:
​EligibilityCard · required

Card data for eligibility check — only card_number is required, no CVV needed

EligibilityPaymentMethodDataRequest

Payment method data request for eligibility check
​object
oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · requires: card
type = object · requires: card_redirect
type = object · requires: wallet
type = object · requires: pay_later
type = object · requires: bank_redirect
type = object · requires: bank_debit
type = object · requires: bank_transfer
type = object · requires: real_time_payment
type = object · requires: crypto
type = string
type = string
type = object · requires: upi
type = object · requires: voucher
type = object · requires: gift_card
type = object · requires: card_token
type = object · requires: open_banking
type = object · requires: mobile_payment
type = object · requires: network_token
Properties for EligibilityCard:
​EligibilityCard · required

Card data for eligibility check — only card_number is required, no CVV needed

EligibilityResponseParams

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · requires: ThreeDsData
Properties for Variant 1:
​ThreeDsData · required

EliminationAnalyserConfig

bucket_size
​integer | null · int64 · min: 0
bucket_leak_interval_in_secs
​integer | null · int64 · min: 0

EliminationRoutingConfig

​DecisionEngineEliminationData · required
​object

EnabledPaymentMethod

Object for EnabledPaymentMethod
payment_method
​PaymentMethod · enum · required

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

Enum values:
card
card_redirect
pay_later
wallet
bank_redirect
bank_transfer
crypto
bank_debit
payment_method_types
​PaymentMethodType[] · unique · required

An array of associated payment method types

Enum values:
ach
affirm
afterpay_clearpay
alfamart
ali_pay
ali_pay_hk
alma
amazon_pay

EntityType

string · enum
Enum values:
tenant
organization
merchant
profile

EphemeralKeyCreateResponse

ephemeral_key for the customer_id mentioned
customer_id
​string · minLength: 1 · maxLength: 64 · required

customer_id to which this ephemeral key belongs to

Example: cus_y3oqhf46pyzuxjbcn2giaqnb44
created_at
​integer · int64 · required

time at which this ephemeral key was created

expires
​integer · int64 · required

time at which this ephemeral key would expire

secret
​string · required

ephemeral key

ErrorCategory

string · enum
Enum values:
frm_decline
processor_downtime
processor_decline_unauthorized
issue_with_payment_method
processor_decline_incorrect_data
hard_decline
soft_decline

EstimateSubscriptionQuery

item_price_id
​string · required

Identifier for the associated item_price_id for the subscription.

plan_id
​string | null

Identifier for the associated subscription plan.

coupon_code
​string | null

Identifier for the coupon code for the subscription.

EstimateSubscriptionResponse

amount
​MinorUnit · int64 · required

This Unit struct represents MinorUnit in which core amount works

currency
​Currency · enum · required

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

Enum values:
AED
AFN
ALL
AMD
ANG
AOA
ARS
AUD
​SubscriptionLineItem[] · required
plan_id
​string | null

Identifier for the associated plan_id.

item_price_id
​string | null

Identifier for the associated item_price_id for the subscription.

coupon_code
​string | null

Identifier for the coupon code for the subscription.

customer_id
​string

A type for customer_id that can be used for customer ids

EventClass

string · enum
Enum values:
payments
refunds
disputes
mandates
payouts
subscriptions

EventListConstraints

The constraints to apply when filtering events.
created_after
​string | null · date-time

Filter events created after the specified time.

created_before
​string | null · date-time

Filter events created before the specified time.

limit
​integer | null · int32 · min: 0

Include at most the specified number of events.

offset
​integer | null · int32 · min: 0

Include events after the specified offset.

object_id
​string | null

Filter all events associated with the specified object identifier (Payment Intent ID, Refund ID, etc.)

event_id
​string | null

Filter all events associated with the specified Event_id

profile_id
​string | null

Filter all events associated with the specified business profile ID.

event_classes
​array | null · unique

Filter events by their class.

Enum values:
payments
refunds
disputes
mandates
payouts
subscriptions
event_types
​array | null · unique

Filter events by their type.

Enum values:
payment_succeeded
payment_failed
payment_processing
payment_cancelled
payment_cancelled_post_capture
payment_authorized
payment_partially_authorized
payment_captured
is_delivered
​boolean | null

Filter all events by is_overall_delivery_successful field of the event.

EventListItemResponse

The response body for each item when listing events.
event_id
​string · maxLength: 64 · required

The identifier for the Event.

Example: evt_018e31720d1b7a2b82677d3032cab959
merchant_id
​string · maxLength: 64 · required

The identifier for the Merchant Account.

Example: y3oqhf46pyzuxjbcn2giaqnb44
profile_id
​string · maxLength: 64 · required

The identifier for the Business Profile.

Example: SqB0zwDGR5wHppWf0bx7GKr1f2
object_id
​string · maxLength: 64 · required

The identifier for the object (Payment Intent ID, Refund ID, etc.)

Example: QHrfd5LUDdZaKtAjdJmMu0dMa1
event_type
​EventType · enum · required
Enum values:
payment_succeeded
payment_failed
payment_processing
payment_cancelled
payment_cancelled_post_capture
payment_authorized
payment_partially_authorized
payment_captured
event_class
​EventClass · enum · required
Enum values:
payments
refunds
disputes
mandates
payouts
subscriptions
initial_attempt_id
​string · maxLength: 64 · required

The identifier for the initial delivery attempt. This will be the same as event_id for the initial delivery attempt.

Example: evt_018e31720d1b7a2b82677d3032cab959
created
​string · date-time · required

Time at which the event was created.

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

Indicates whether the webhook was ultimately delivered or not.

EventRetrieveResponse

The response body for retrieving an event.
event_id
​string · maxLength: 64 · required

The identifier for the Event.

Example: evt_018e31720d1b7a2b82677d3032cab959
merchant_id
​string · maxLength: 64 · required

The identifier for the Merchant Account.

Example: y3oqhf46pyzuxjbcn2giaqnb44
profile_id
​string · maxLength: 64 · required

The identifier for the Business Profile.

Example: SqB0zwDGR5wHppWf0bx7GKr1f2
object_id
​string · maxLength: 64 · required

The identifier for the object (Payment Intent ID, Refund ID, etc.)

Example: QHrfd5LUDdZaKtAjdJmMu0dMa1
event_type
​EventType · enum · required
Enum values:
payment_succeeded
payment_failed
payment_processing
payment_cancelled
payment_cancelled_post_capture
payment_authorized
payment_partially_authorized
payment_captured
event_class
​EventClass · enum · required
Enum values:
payments
refunds
disputes
mandates
payouts
subscriptions
initial_attempt_id
​string · maxLength: 64 · required

The identifier for the initial delivery attempt. This will be the same as event_id for the initial delivery attempt.

Example: evt_018e31720d1b7a2b82677d3032cab959
created
​string · date-time · required

Time at which the event was created.

Example: 2022-09-10T10:11:12Z
​OutgoingWebhookRequestContent · required

The request information (headers and body) sent in the webhook.

​OutgoingWebhookResponseContent · required

The response information (headers, body and status code) received for the webhook sent.

is_delivery_successful
​boolean | null

Indicates whether the webhook was ultimately delivered or not.

delivery_attempt
​string · enum
Enum values:
initial_attempt
automatic_retry
manual_retry

EventType

string · enum
Enum values:
payment_succeeded
payment_failed
payment_processing
payment_cancelled
payment_cancelled_post_capture
payment_authorized
payment_partially_authorized
payment_captured

ExemptionIndicator

string · enum
Enum values:
low_value
secure_corporate_payment
trusted_listing
transaction_risk_assessment
three_ds_outage
sca_delegation
out_of_sca_scope
other

Represents the exemption indicator used in a transaction under PSD2 SCA (Strong Customer Authentication) rules.

ExtendedCardInfo

card_number
​string · required

The card number

Example: 4242424242424242
card_exp_month
​string · required

The card's expiry month

Example: 24
card_exp_year
​string · required

The card's expiry year

Example: 24
card_holder_name
​string · required

The card holder's name

Example: John Test
card_cvc
​string · required

The CVC number for the card

Example: 242
card_issuer
​string | null

The name of the issuer of card

Example: chase
card_network
​string · enum

Indicates the card network.

Enum values:
Visa
Mastercard
AmericanExpress
JCB
DinersClub
Discover
CartesBancaires
UnionPay
card_type
​string | null
card_issuing_country
​string | null
bank_code
​string | null

ExtendedCardInfoConfig

public_key
​string · required

Merchant public key

ttl_in_secs
​integer · int32 · min: 0 · max: 7200

TTL for extended card info

Default: 900

ExtendedCardInfoResponse

payload
​string · required

ExternalAuthenticationDetailsResponse

Details of external authentication
status
​AuthenticationStatus · enum · required
Enum values:
started
pending
success
failed
authentication_flow
​string · enum
Enum values:
challenge
frictionless
electronic_commerce_indicator
​string | null

Electronic Commerce Indicator (eci)

ds_transaction_id
​string | null

DS Transaction ID

version
​string | null

Message Version

error_code
​string | null

Error Code

error_message
​string | null

Error Message

ExternalThreeDsData

Represents external 3DS authentication data used in the payment flow.
​Cryptogram · required

Represents the 3DS cryptogram data returned after authentication.

ds_trans_id
​string · required

Directory Server Transaction ID generated during the 3DS process.

version
​string · required

The version of the 3DS protocol used (e.g., "2.1.0" or "2.2.0").

eci
​string · required

Electronic Commerce Indicator (ECI) value representing the 3DS authentication result.

transaction_status
​TransactionStatus · enum · required

Indicates the transaction status

Enum values:
Y
N
U
A
R
C
D
I
exemption_indicator
​string · enum

Represents the exemption indicator used in a transaction under PSD2 SCA (Strong Customer Authentication) rules.

Enum values:
low_value
secure_corporate_payment
trusted_listing
transaction_risk_assessment
three_ds_outage
sca_delegation
out_of_sca_scope
other
​object

Represents additional network-level parameters for 3DS processing.

ExternalVaultConnectorDetails

vault_connector_id
​string | null

Merchant Connector id to be stored for vault connector

vault_sdk
​string · enum
Enum values:
vgs_sdk
hyperswitch_sdk
​array | null

Fields to tokenization in vault

ExternalVaultEnabled

string · enum
Enum values:
enable
skip

FeatureMatrixListResponse

connector_count
​integer · min: 0 · required

The number of connectors included in the response

​ConnectorFeatureMatrixResponse[] · required

FeatureMatrixRequest

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

FeatureMetadata

additional data that might be required by hyperswitch
​object
search_tags
​array | null

Additional tags to be used for global search

​object
​
​object

FeatureStatus

string · enum
Enum values:
not_supported
supported

The status of the feature

FeeDetail

One fee snapshot keyed by a refund or payout-attempt reference.
reference_id
​string · required
created_at
​string · required
currency
​string · required
base_amount
​integer · int64 · required
merchant_commission_amount
​integer | null · int64
provider_cost
​integer | null · int64
margin
​integer | null · int64
merchant_commission_rate
​
provider_cost_rate
​
merchant_commission_rule
​string | null
provider_cost_rule
​string | null

FeeSummary

A fee snapshot summary for one business transaction.
currency
​string · required
base_amount
​integer · int64 · required
merchant_commission_amount
​integer · int64 · required
provider_cost
​integer | null · int64
margin
​integer | null · int64
merchant_commission_rate
​
provider_cost_rate
​
merchant_commission_rule
​string | null
provider_cost_rule
​string | null

FieldOrigin

string · enum
Enum values:
passed_by_merchant
generated_by_platform

Origin of a field in [PaymentDetailedResponse] Binary: either was suppliedby the merchant in the original request, or generated by the platform.

FieldOrigins

A record of which top-level fields in [`PaymentDetailedResponse`] were merchant-provided vs. platform-generated for this specific payment intent. Keys are field names matching [`PaymentDetailedResponse`]'s serde names. Any field absent from this map should be treated as `GeneratedByPlatform`.
FieldOrigin · enum
Enum values:
passed_by_merchant
generated_by_platform

Origin of a field in [PaymentDetailedResponse] Binary: either was suppliedby the merchant in the original request, or generated by the platform.

FieldType

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = string
type = string
type = string
type = string
type = string
type = string
type = string
type = string
type = string
type = string
type = string
type = object · requires: user_country
type = object · requires: user_currency
type = string
type = string
type = string
type = string
type = string
type = string
type = string
type = object · requires: user_address_country
type = string
type = string
type = string
type = string
type = string
type = string
type = object · requires: user_shipping_address_country
type = object · requires: user_document_type
type = string
type = string
type = string
type = object · requires: user_bank_options
type = string
type = string
type = string
type = string
type = object · requires: drop_down
type = string
type = string
type = object · requires: language_preference
type = string
type = string
type = string
type = string
type = string
type = string
type = string
type = object · requires: user_bank_type
type = string
type = string
type = string
type = string
Properties for Variant 1:
string · enum
Enum values:
user_card_number

FilterOperator

string · enum
Enum values:
eq
neq
is_null
is_not_null
like
not_like
in
not_in

Comparison operator for one column predicate.

FilterValue

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = boolean
type = integer
type = array
type = string
type = array
Properties for Variant 1:
boolean

JSON boolean.

FrmAction

string · enum
Enum values:
cancel_txn
auto_refund
manual_review

FrmConfigs

Details of FrmConfigs are mentioned here... it should be passed in payment connector create api call, and stored in merchant_connector_table
gateway
​ConnectorType · enum · required

Type of the Connector for the financial use case. Could range from Payments to Accounting to Banking.

Enum values:
payment_processor
payment_vas
fin_operations
fiz_operations
networks
banking_entities
non_banking_finance
payout_processor
​FrmPaymentMethod[] · required

payment methods that can be used in the payment

FrmMessage

frm message is an object sent inside the payments response...when frm is invoked, its value is Some(...), else its None
frm_name
​string · required
frm_transaction_id
​string | null
frm_transaction_type
​string | null
frm_status
​string | null
frm_score
​integer | null · int32
frm_reason
​
frm_error
​string | null

FrmPaymentMethod

Details of FrmPaymentMethod are mentioned here... it should be passed in payment connector create api call, and stored in merchant_connector_table
payment_method
​PaymentMethod · enum · required

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

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

payment method types(credit, debit) that can be used in the payment. This field is deprecated. It has not been removed to provide backward compatibility.

flow
​string · enum
Enum values:
pre
post

FrmPaymentMethodType

Details of FrmPaymentMethodType are mentioned here... it should be passed in payment connector create api call, and stored in merchant_connector_table
payment_method_type
​PaymentMethodType · enum · required

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

Enum values:
ach
affirm
afterpay_clearpay
alfamart
ali_pay
ali_pay_hk
alma
amazon_pay
card_networks
​CardNetwork · enum · required

Indicates the card network.

Enum values:
Visa
Mastercard
AmericanExpress
JCB
DinersClub
Discover
CartesBancaires
UnionPay
flow
​FrmPreferredFlowTypes · enum · required
Enum values:
pre
post
action
​FrmAction · enum · required
Enum values:
cancel_txn
auto_refund
manual_review

FrmPreferredFlowTypes

string · enum
Enum values:
pre
post

FutureUsage

string · enum
Enum values:
off_session
on_session

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.

GPayPredecryptData

This struct represents the decrypted Google Pay payment data
card_exp_month
​string · required

The card's expiry month

card_exp_year
​string · required

The card's expiry year

application_primary_account_number
​string · required

The Primary Account Number (PAN) of the card

Example: 4242424242424242
cryptogram
​string · required

Cryptogram generated by the Network

Example: AgAAAAAAAIR8CQrXcIhbQAAAAAA
eci_indicator
​string · required

Electronic Commerce Indicator

Example: 07

GcashRedirection

GenericErrorResponseOpenApi

error_type
​string · required
message
​string · required
code
​string · required

GenericLinkUiConfig

Object for GenericLinkUiConfig
logo
​string | null · maxLength: 255

Merchant's display logo

Example: https://hyperswitch.io/favicon.ico
merchant_name
​string | null · maxLength: 255

Custom merchant name for the link

Example: Hyperswitch
theme
​string | null · maxLength: 255

Primary color to be used in the form represented in hex format

Example: #4285F4

GetSubscriptionItemsQuery

item_type
​SubscriptionItemType · enum · required
Enum values:
plan
addon
client_secret
​string | null

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

limit
​integer | null · int32 · min: 0
offset
​integer | null · int32 · min: 0

GetSubscriptionItemsResponse

item_id
​string · required
name
​string · required
​SubscriptionItemPrices[] · required
description
​string | null

GiftCardAdditionalData

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · requires: givex
type = object · requires: pay_safe_card
type = object · requires: bhn_card_network
Properties for Variant 1:
​GivexGiftCardAdditionalData · required

GiftCardData

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · requires: givex
type = object · requires: pay_safe_card
type = object · requires: bhn_card_network
Properties for Variant 1:
​GiftCardDetails · required

GiftCardDetails

number
​string · required

The gift card number

cvc
​string · required

The card verification code.

GiftCardResponse

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · requires: givex
type = object · requires: pay_safe_card
type = object · requires: bhn_card_network
Properties for Variant 1:
​GivexGiftCardAdditionalData · required

GiropayBankRedirectAdditionalData

bic
​string | null

Masked bank account bic code

iban
​string | null

Partially masked international bank account number (iban) for SEPA

country
​string · enum
Enum values:
AF
AX
AL
DZ
AS
AD
AO
AI

GivexGiftCardAdditionalData

last4
​string · required

Last 4 digits of the gift card number

Example: 4242

GoPayRedirection

GooglePayAssuranceDetails

card_holder_authenticated
​boolean · required

indicates that Cardholder possession validation has been performed

account_verified
​boolean · required

indicates that identification and verifications (ID&V) was performed

GooglePayCardFundingSource

string · enum
Enum values:
CREDIT
DEBIT
PREPAID
UNKNOWN

GooglePayPaymentMethodInfo

card_network
​string · required

The name of the card network

card_details
​string · required

The details of the card

​object
card_funding_source
​string · enum
Enum values:
CREDIT
DEBIT
PREPAID
UNKNOWN

GooglePayRedirectData

GooglePaySessionResponse

​GpayMerchantInfo · required
shipping_address_required
​boolean · required

Is shipping address required

email_required
​boolean · required

Is email required

​GpayShippingAddressParameters · required
​GpayAllowedPaymentMethods[] · required

List of the allowed payment methods

​GpayTransactionInfo · required
delayed_session_token
​boolean · required

Identifier for the delayed session response

connector
​string · required

The name of the connector

​SdkNextAction · required
​object

GooglePayThirdPartySdk

delayed_session_token
​boolean · required

Identifier for the delayed session response

connector
​string · required

The name of the connector

​SdkNextAction · required

GooglePayThirdPartySdkData

token
​string | null

GooglePayWalletData

type
​string · required

The type of payment method

description
​string · required

User-facing message to describe the payment method that funds this transaction.

​GooglePayPaymentMethodInfo · required
​GpayTokenizationData · required

This enum is used to represent the Gpay payment data, which can either be encrypted or decrypted.

GpayAllowedMethodsParameters

allowed_auth_methods
​string[] · required

The list of allowed auth methods (ex: 3DS, No3DS, PAN_ONLY etc)

allowed_card_networks
​string[] · required

The list of allowed card networks (ex: AMEX,JCB etc)

billing_address_required
​boolean | null

Is billing address required

​object
assurance_details_required
​boolean | null

Whether assurance details are required

GpayAllowedPaymentMethods

type
​string · required

The type of payment method

​GpayAllowedMethodsParameters · required
​GpayTokenizationSpecification · required

GpayBillingAddressFormat

string · enum
Enum values:
FULL
MIN

GpayBillingAddressParameters

phone_number_required
​boolean · required

Is billing phone number required

format
​GpayBillingAddressFormat · enum · required
Enum values:
FULL
MIN

GpayEcryptedTokenizationData

This struct represents the encrypted Gpay payment data
type
​string · required

The type of the token

token
​string · required

Token generated for the wallet

GpayMerchantInfo

merchant_name
​string · required

The name of the merchant that needs to be displayed on Gpay PopUp

merchant_id
​string | null

The merchant Identifier that needs to be passed while invoking Gpay SDK

GpaySessionTokenResponse

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · requires: delayed_session_token, connector, sdk_next_action
type = object · requires: merchant_info, shipping_address_required, email_required +6 more
Properties for Variant 1:
delayed_session_token
​boolean · required

Identifier for the delayed session response

connector
​string · required

The name of the connector

​SdkNextAction · required

GpayShippingAddressParameters

phone_number_required
​boolean · required

Is shipping phone number required

GpayTokenParameters

gateway
​string | null

The name of the connector

gateway_merchant_id
​string | null

The merchant ID registered in the connector associated

stripe:version
​string | null
stripe:publishableKey
​string | null
protocol_version
​string | null

The protocol version for encryption

public_key
​string | null

The public key provided by the merchant

GpayTokenizationData

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · requires: card_exp_month, card_exp_year, application_primary_account_number +2 more
type = object · requires: type, token
Properties for Variant 1:
This struct represents the decrypted Google Pay payment data
card_exp_month
​string · required

The card's expiry month

card_exp_year
​string · required

The card's expiry year

application_primary_account_number
​string · required

The Primary Account Number (PAN) of the card

Example: 4242424242424242
cryptogram
​string · required

Cryptogram generated by the Network

Example: AgAAAAAAAIR8CQrXcIhbQAAAAAA
eci_indicator
​string · required

Electronic Commerce Indicator

Example: 07

GpayTokenizationSpecification

type
​string · required

The token specification type(ex: PAYMENT_GATEWAY)

​GpayTokenParameters · required

GpayTransactionInfo

country_code
​CountryAlpha2 · enum · required
Enum values:
AF
AX
AL
DZ
AS
AD
AO
AI
currency_code
​Currency · enum · required

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

Enum values:
AED
AFN
ALL
AMD
ANG
AOA
ARS
AUD
total_price_status
​string · required

The total price status (ex: 'FINAL')

total_price
​string · required

The total price

Example: 38.02

GsmCreateRequest

connector
​Connector · enum · required
Enum values:
flexifai
fiftyfourpay
honeycoin
k218pay
bitex
hypergate
maguapay
payadmit
flow
​string · required

The flow in which the code and message occurred for a connector

sub_flow
​string · required

The sub_flow in which the code and message occurred for a connector

code
​string · required

code received from the connector

message
​string · required

message received from the connector

status
​string · required

status provided by the router

decision
​GsmDecision · enum · required
Enum values:
retry
do_default
router_error
​string | null

optional error provided by the router

unified_code
​string | null

error code unified across the connectors

unified_message
​string | null

error message unified across the connectors

error_category
​string · enum
Enum values:
frm_decline
processor_downtime
processor_decline_unauthorized
issue_with_payment_method
processor_decline_incorrect_data
hard_decline
soft_decline
feature
​string · enum
Enum values:
retry
​

Contains the data relevant to the specified GSM feature, if applicable. For example, if the feature is Retry, this will include configuration details specific to the retry behavior.

standardised_code
​string · enum
Enum values:
account_closed_or_invalid
authentication_failed
authentication_required
authorization_missing_or_revoked
card_lost_or_stolen
card_not_supported_restricted
cfg_pm_not_enabled_or_misconfigured
compliance_or_sanctions_restriction
description
​string | null

A detailed description of the error intended for debugging, analytics, and support teams.

user_guidance_message
​string | null

A user-friendly message that can be safely displayed to the customer. This message provides guidance on what the user should do to resolve the issue.

GsmDecision

string · enum
Enum values:
retry
do_default

GsmDeleteRequest

connector
​string · required

The connector through which payment has gone through

flow
​string · required

The flow in which the code and message occurred for a connector

sub_flow
​string · required

The sub_flow in which the code and message occurred for a connector

code
​string · required

code received from the connector

message
​string · required

message received from the connector

GsmDeleteResponse

gsm_rule_delete
​boolean · required
connector
​string · required

The connector through which payment has gone through

flow
​string · required

The flow in which the code and message occurred for a connector

sub_flow
​string · required

The sub_flow in which the code and message occurred for a connector

code
​string · required

code received from the connector

GsmFeature

string · enum
Enum values:
retry

GsmFeatureData

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · requires: retry
Properties for Variant 1:
​RetryFeatureData · required

Represents the data associated with a retry feature in GSM.

GsmResponse

connector
​string · required

The connector through which payment has gone through

flow
​string · required

The flow in which the code and message occurred for a connector

sub_flow
​string · required

The sub_flow in which the code and message occurred for a connector

code
​string · required

code received from the connector

message
​string · required

message received from the connector

status
​string · required

status provided by the router

decision
​GsmDecision · enum · required
Enum values:
retry
do_default
feature
​GsmFeature · enum · required
Enum values:
retry
​GsmFeatureData · required

Contains the data relevant to the specified GSM feature, if applicable. For example, if the feature is Retry, this will include configuration details specific to the retry behavior.

router_error
​string | null

optional error provided by the router

unified_code
​string | null

error code unified across the connectors

unified_message
​string | null

error message unified across the connectors

error_category
​string · enum
Enum values:
frm_decline
processor_downtime
processor_decline_unauthorized
issue_with_payment_method
processor_decline_incorrect_data
hard_decline
soft_decline
standardised_code
​string · enum
Enum values:
account_closed_or_invalid
authentication_failed
authentication_required
authorization_missing_or_revoked
card_lost_or_stolen
card_not_supported_restricted
cfg_pm_not_enabled_or_misconfigured
compliance_or_sanctions_restriction
description
​string | null

A detailed description of the error intended for debugging, analytics, and support teams.

user_guidance_message
​string | null

A user-friendly message that can be safely displayed to the customer. This message provides guidance on what the user should do to resolve the issue.

GsmRetrieveRequest

connector
​Connector · enum · required
Enum values:
flexifai
fiftyfourpay
honeycoin
k218pay
bitex
hypergate
maguapay
payadmit
flow
​string · required

The flow in which the code and message occurred for a connector

sub_flow
​string · required

The sub_flow in which the code and message occurred for a connector

code
​string · required

code received from the connector

message
​string · required

message received from the connector

GsmUpdateRequest

connector
​string · required

The connector through which payment has gone through

flow
​string · required

The flow in which the code and message occurred for a connector

sub_flow
​string · required

The sub_flow in which the code and message occurred for a connector

code
​string · required

code received from the connector

message
​string · required

message received from the connector

status
​string | null

status provided by the router

router_error
​string | null

optional error provided by the router

decision
​string · enum
Enum values:
retry
do_default
unified_code
​string | null

error code unified across the connectors

unified_message
​string | null

error message unified across the connectors

error_category
​string · enum
Enum values:
frm_decline
processor_downtime
processor_decline_unauthorized
issue_with_payment_method
processor_decline_incorrect_data
hard_decline
soft_decline
feature
​string · enum
Enum values:
retry
​

Contains the data relevant to the specified GSM feature, if applicable. For example, if the feature is Retry, this will include configuration details specific to the retry behavior.

standardised_code
​string · enum
Enum values:
account_closed_or_invalid
authentication_failed
authentication_required
authorization_missing_or_revoked
card_lost_or_stolen
card_not_supported_restricted
cfg_pm_not_enabled_or_misconfigured
compliance_or_sanctions_restriction
description
​string | null

A detailed description of the error intended for debugging, analytics, and support teams.

user_guidance_message
​string | null

A user-friendly message that can be safely displayed to the customer. This message provides guidance on what the user should do to resolve the issue.

HyperswitchConnectorCategory

string · enum
Enum values:
payment_gateway
alternative_payment_method
bank_acquirer
payout_processor
authentication_provider
fraud_and_risk_management_provider
tax_calculation_provider
revenue_growth_management_platform

Connector Access Method

IfStatement

Represents an IF statement with conditions and optional nested IF statements ```text payment.method = card { payment.method.cardtype = (credit, debit) { payment.method.network = (amex, rupay, diners) } } ```
​Comparison[] · required
​array | null

IframeData

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · method_key="threeDSMethodData" · requires: three_ds_method_url, three_ds_method_data_submission, directory_server_id
Properties for Variant 1:
three_ds_method_url
​string · required

ThreeDS method url

three_ds_method_data_submission
​boolean · required

Whether ThreeDS method data submission is required

directory_server_id
​string · required

ThreeDS Server ID

method_key
​string · enum · required
Enum values:
threeDSMethodData
three_ds_method_data
​string | null

ThreeDS method data

message_version
​string | null

ThreeDS Protocol version

ImmediateExpirationTime

time
​integer · int32 · min: 0 · required

Expiration time in seconds

​

IncrementalAuthorizationResponse

authorization_id
​string · required

The unique identifier of authorization

amount
​integer · int64 · required

Amount the authorization has been made for

Example: 6540
status
​AuthorizationStatus · enum · required
Enum values:
success
failure
processing
unresolved
previously_authorized_amount
​MinorUnit · int64 · required

This Unit struct represents MinorUnit in which core amount works

error_code
​string | null

Error code sent by the connector for authorization

error_message
​string | null

Error message sent by the connector for authorization

IndomaretVoucherData

first_name
​string | null

The billing first name for Alfamart

Example: Jane
last_name
​string | null

The billing second name for Alfamart

Example: Doe
email
​string | null

The Email ID for Alfamart

Example: example@me.com

Initiator

string · enum
Enum values:
platform
connected

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

InstallmentData

Installment selection made by the customer during payment confirmation.
number_of_installments
​integer · int32 · min: 0 · required

Number of installments chosen by the customer

billing_frequency
​BillingFrequency · enum · required

Billing frequency for a card installment plan

Enum values:
month
installment_interest
​integer · int64

This Unit struct represents MinorUnit in which core amount works

InstallmentOption

Installment options grouped by payment method
payment_method
​PaymentMethod · enum · required

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

Enum values:
card
card_redirect
pay_later
wallet
bank_redirect
bank_transfer
crypto
bank_debit
​InstallmentOptionData[] · required

List of available installment configurations

InstallmentOptionData

A single installment plan option accepted in request payloads
number_of_installments
​string · required

Number of installments (e.g., [3, 6, 12])

billing_frequency
​BillingFrequency · enum · required

Billing frequency for a card installment plan

Enum values:
month
interest_rate
​number · double · required

Interest rate per installment as a percentage max 2 decimal places

InstallmentRequest

Installment selection sent by the customer during payment confirmation.
number_of_installments
​integer · int32 · min: 0 · required

Number of installments chosen by the customer

billing_frequency
​BillingFrequency · enum · required

Billing frequency for a card installment plan

Enum values:
month

IntentStatus

string · enum
Enum values:
succeeded
failed
cancelled
cancelled_post_capture
processing
requires_customer_action
requires_merchant_action
requires_payment_method

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

Interac

email
​string · required

Customer email linked with interac account

Example: john.doe@example.com

InteracAdditionalData

Masked payout method details for interac bank redirect payout method
email
​string | null

Email linked with interac account

Example: john.doe@example.com

InteracPaymentMethod

customer_info
​object | null

Invoice

id
​InvoiceId · required

A type for invoice_id that can be used for invoice ids

subscription_id
​SubscriptionId · required

A type for subscription_id that can be used for subscription ids

merchant_id
​MerchantId · required

A type for merchant_id that can be used for merchant ids

profile_id
​ProfileId · required

A type for profile_id that can be used for business profile ids

merchant_connector_id
​MerchantConnectorAccountId · required

A type for merchant_connector_id that can be used for merchant_connector_account ids

customer_id
​CustomerId · required

A type for customer_id that can be used for customer ids

amount
​MinorUnit · int64 · required

This Unit struct represents MinorUnit in which core amount works

currency
​Currency · enum · required

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

Enum values:
AED
AFN
ALL
AMD
ANG
AOA
ARS
AUD
status
​InvoiceStatus · enum · required
Enum values:
invoice_created
payment_pending
payment_pending_timeout
payment_succeeded
payment_failed
payment_canceled
invoice_paid
manual_review
payment_intent_id
​string

A type for payment_id that can be used for payment ids

payment_method_id
​string | null

Identifier for Payment Method

Example: pm_01926c58bc6e77c09e809964e72af8c8
billing_processor_invoice_id
​string | null

billing processor invoice id

InvoiceId

string

A type for invoice_id that can be used for invoice ids

InvoiceStatus

string · enum
Enum values:
invoice_created
payment_pending
payment_pending_timeout
payment_succeeded
payment_failed
payment_canceled
invoice_paid
manual_review

IssuerData

Represents data about the issuer used in the 3DS decision rule.
country
​Country · enum · required
Enum values:
Afghanistan
AlandIslands
Albania
Algeria
AmericanSamoa
Andorra
Angola
Anguilla
name
​string | null

The name of the issuer.

JCSVoucherData

first_name
​string | null

The billing first name for Japanese convenience stores

Example: Jane
last_name
​string | null

The billing second name Japanese convenience stores

Example: Doe
email
​string | null

The Email ID for Japanese convenience stores

Example: example@me.com
phone_number
​string | null

The telephone number for Japanese convenience stores

Example: 9123456789

KakaoPayRedirection

KlarnaSdkPaymentMethodResponse

payment_type
​string | null

KlarnaSessionTokenResponse

session_token
​string · required

The session token for Klarna

session_id
​string · required

The identifier for the session

KycStatus

string · enum
Enum values:
none
partial
complete

KYC level provided by the merchant for external customer statistics (routing).

LabelInformation

label
​string · required
target_count
​integer · int64 · min: 0 · required
target_time
​integer · int64 · min: 0 · required
mca_id
​string · required

LinkedRoutingConfigRetrieveResponse

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object
type = array
Properties for Variant 1:
Response returned when retrieving routing configuration for a merchant account.
​object

Routing algorithm configuration created for a merchant.

Represents a fully defined routing strategy scoped to a profile and transaction type.

ListBlocklistQuery

data_kind
​BlocklistDataKind · enum · required
Enum values:
payment_method
card_bin
extended_card_bin
email
card_number
card_pan_masked
phone
limit
​integer · int32 · min: 0
offset
​integer · int32 · min: 0
client_secret
​string | null
scope
​BlocklistScope · enum

Ownership scope for a blocklist entry (org / merchant / connector MCA).

Enum values:
organization
merchant
connector
merchant_connector_id
​string | null

Required when scope is connector.

ListWhitelistQuery

data_kind
​BlocklistDataKind · enum · required
Enum values:
payment_method
card_bin
extended_card_bin
email
card_number
card_pan_masked
phone
merchant_connector_id
​string · required
limit
​integer · int32 · min: 0
offset
​integer · int32 · min: 0

LocalBankTransferAdditionalData

bank_code
​string | null

Partially masked bank code

Example: **** OA2312

MandateAmountData

amount
​integer · int64 · required

The maximum amount to be debited for the mandate transaction

Example: 6540
currency
​Currency · enum · required

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

Enum values:
AED
AFN
ALL
AMD
ANG
AOA
ARS
AUD
start_date
​string | null · date-time

Specifying start date of the mandate

Example: 2022-09-10T00:00:00Z
end_date
​string | null · date-time

Specifying end date of the mandate

Example: 2023-09-10T23:59:59Z
metadata
​object | null

Additional details required by mandate

MandateCardDetails

last4_digits
​string | null

The last 4 digits of card

card_exp_month
​string | null

The expiry month of card

card_exp_year
​string | null

The expiry year of card

card_holder_name
​string | null

The card holder name

card_token
​string | null

The token from card locker

scheme
​string | null

The card scheme network for the particular card

issuer_country
​string | null

The country code in in which the card was issued

card_fingerprint
​string | null

A unique identifier alias to identify a particular card

card_isin
​string | null

The first 6 digits of card

card_issuer
​string | null

The bank that issued the card

card_network
​string · enum

Indicates the card network.

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

The type of the payment card

nick_name
​string | null

The nick_name of the card holder

MandateData

Passing this object during payments creates a mandate. The mandate_type sub object is passed by the server.
update_mandate_id
​string | null

A way to update the mandate's payment method details

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

​

MandateResponse

mandate_id
​string · required

The identifier for mandate

status
​MandateStatus · enum · required

The status of the mandate, which indicates whether it can be used to initiate a payment.

Enum values:
active
inactive
pending
revoked
payment_method_id
​string · required

The identifier for payment method

payment_method
​string · required

The payment method

payment_method_type
​string | null

The payment method type

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

MandateRevokedResponse

mandate_id
​string · required

The identifier for mandate

status
​MandateStatus · enum · required

The status of the mandate, which indicates whether it can be used to initiate a payment.

Enum values:
active
inactive
pending
revoked
error_code
​string | null

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

Example: E0001
error_message
​string | null

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

Example: Failed while verifying the card

MandateStatus

string · enum
Enum values:
active
inactive
pending
revoked

The status of the mandate, which indicates whether it can be used to initiate a payment.

MandateType

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · requires: single_use
type = object · requires: multi_use
Properties for Variant 1:
​MandateAmountData · required

MaskedBankDetails

mask
​string · required

MasterCardEligibilityCheckData

consumerPresent
​boolean · required
idLookupSessionId
​string | null
lastUsedCardTimestamp
​string | null

MbWayRedirection

telephone_number
​string · required

Telephone number of the shopper. Should be Portuguese phone number.

MerchantAccountCreate

merchant_id
​string · minLength: 1 · maxLength: 64 · required

The identifier for the Merchant Account

Example: y3oqhf46pyzuxjbcn2giaqnb44
merchant_name
​string | null

Name of the Merchant Account

Example: NewAge Retailer
​object
return_url
​string | null · maxLength: 255

The URL to redirect after the completion of the operation

Example: https://www.example.com/success
​object
​
sub_merchants_enabled
​boolean | null

A boolean value to indicate if the merchant is a sub-merchant under a master or a parent merchant. By default, its value is false.

Example: false
Default: false
parent_merchant_id
​string | null · maxLength: 255

Refers to the Parent Merchant ID if the merchant being created is a sub-merchant

Example: xkkdf909012sdjki2dkh5sdf
enable_payment_response_hash
​boolean | null

A boolean value to indicate if payment response hash needs to be enabled

Example: true
Default: false
payment_response_hash_key
​string | null

Refers to the hash key used for calculating the signature for webhooks and redirect response. If the value is not provided, a value is automatically generated.

redirect_to_merchant_with_http_post
​boolean | null

A boolean value to indicate if redirect to merchant with http post needs to be enabled.

Example: true
Default: false
metadata
​object | null

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

publishable_key
​string | null

API key that will be used for client side API access. A publishable key has to be always paired with a client_secret. A client_secret can be obtained by creating a payment with confirm set to false

Example: AH3423bkjbkjdsfbkj
locker_id
​string | null

An identifier for the vault used to store payment method information.

Example: locker_abc123
​object
frm_routing_algorithm
​object | null

The frm routing algorithm to be used for routing payments to desired FRM's

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

The id of the organization to which the merchant belongs to, if not passed an organization is created

Example: org_q98uSGAYbjEwqs0mJwnz
​object

Object for GenericLinkUiConfig

product_type
​string · enum
Enum values:
orchestration
vault
recon
recovery
cost_observability
dynamic_routing
merchant_account_type
​string · enum
Enum values:
standard
platform
connected

MerchantAccountData

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · requires: iban
type = object · requires: bacs
type = object · requires: faster_payments
type = object · requires: sepa
type = object · requires: sepa_instant
type = object · requires: elixir
type = object · requires: bankgiro
type = object · requires: plusgiro
Properties for Variant 1:
​object · required

IBAN-based account for international transfers

MerchantAccountDeleteResponse

merchant_id
​string · maxLength: 255 · required

The identifier for the Merchant Account

Example: y3oqhf46pyzuxjbcn2giaqnb44
deleted
​boolean · required

If the connector is deleted or not

Example: false

MerchantAccountRequestType

string · enum
Enum values:
standard
connected

MerchantAccountResponse

merchant_id
​string · maxLength: 64 · required

The identifier for the Merchant Account

Example: y3oqhf46pyzuxjbcn2giaqnb44
enable_payment_response_hash
​boolean · required

A boolean value to indicate if payment response hash needs to be enabled

Example: true
Default: false
redirect_to_merchant_with_http_post
​boolean · required

A boolean value to indicate if redirect to merchant with http post needs to be enabled

Example: true
Default: false
​PrimaryBusinessDetails[] · required

Details about the primary business unit of the merchant account

organization_id
​string · minLength: 1 · maxLength: 64 · required

The organization id merchant is associated with

Example: org_q98uSGAYbjEwqs0mJwnz
is_recon_enabled
​boolean · required

A boolean value to indicate if the merchant has recon service is enabled or not, by default value is false

recon_status
​ReconStatus · enum · required
Enum values:
not_requested
requested
active
disabled
merchant_account_type
​MerchantAccountType · enum · required
Enum values:
standard
platform
connected
merchant_name
​string | null

Name of the Merchant Account

Example: NewAge Retailer
return_url
​string | null · maxLength: 255

The URL to redirect after completion of the payment

Example: https://www.example.com/success
payment_response_hash_key
​string | null · maxLength: 255

Refers to the hash key used for calculating the signature for webhooks and redirect response. If the value is not provided, a value is automatically generated.

Example: xkkdf909012sdjki2dkh5sdf
​object
​object
​
sub_merchants_enabled
​boolean | null

A boolean value to indicate if the merchant is a sub-merchant under a master or a parent merchant. By default, its value is false.

Example: false
Default: false
parent_merchant_id
​string | null · maxLength: 255

Refers to the Parent Merchant ID if the merchant being created is a sub-merchant

Example: xkkdf909012sdjki2dkh5sdf
publishable_key
​string | null

API key that will be used for server side API access

Example: AH3423bkjbkjdsfbkj
metadata
​object | null

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

locker_id
​string | null

An identifier for the vault used to store payment method information.

Example: locker_abc123
​
default_profile
​string | null · maxLength: 64

The default profile that must be used for creating merchant accounts and payments

​object

Object for GenericLinkUiConfig

product_type
​string · enum
Enum values:
orchestration
vault
recon
recovery
cost_observability
dynamic_routing

MerchantAccountType

string · enum
Enum values:
standard
platform
connected

MerchantAccountUpdate

merchant_id
​string · maxLength: 64 · required

The identifier for the Merchant Account

Example: y3oqhf46pyzuxjbcn2giaqnb44
merchant_name
​string | null

Name of the Merchant Account

Example: NewAge Retailer
​object
return_url
​string | null · maxLength: 255

The URL to redirect after the completion of the operation

Example: https://www.example.com/success
​object
​
sub_merchants_enabled
​boolean | null

A boolean value to indicate if the merchant is a sub-merchant under a master or a parent merchant. By default, its value is false.

Example: false
Default: false
parent_merchant_id
​string | null · maxLength: 255

Refers to the Parent Merchant ID if the merchant being created is a sub-merchant

Example: xkkdf909012sdjki2dkh5sdf
enable_payment_response_hash
​boolean | null

A boolean value to indicate if payment response hash needs to be enabled

Example: true
Default: false
payment_response_hash_key
​string | null

Refers to the hash key used for calculating the signature for webhooks and redirect response.

redirect_to_merchant_with_http_post
​boolean | null

A boolean value to indicate if redirect to merchant with http post needs to be enabled

Example: true
Default: false
metadata
​object | null

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

publishable_key
​string | null

API key that will be used for server side API access

Example: AH3423bkjbkjdsfbkj
locker_id
​string | null

An identifier for the vault used to store payment method information.

Example: locker_abc123
​array | null

Details about the primary business unit of the merchant account

frm_routing_algorithm
​object | null

The frm routing algorithm to be used for routing payments to desired FRM's

default_profile
​string | null · maxLength: 64

The default profile that must be used for creating merchant accounts and payments

​object

Object for GenericLinkUiConfig

MerchantApplicationDetails

Information identifying merchant details
name
​string | null

Name of the the merchant application

version
​string | null

Version of the merchant application

MerchantCategoryCode

string
Example: 5411

MerchantCommissionConfigs

​object

Tariff primitive: fee = MAX(min, ceil(pct * base / 100) + fixed).

fixed and min are minor units. JSON must keep both >= 0: a negative addend or floor credits the merchant instead of charging a fee. Percentage already rejects values outside 0–100; this type applies the same gate to the minor-unit fields so the API matches the dashboard form.

MerchantCommissionDecisionConfigReq

​MerchantCommissionConfigs · required
name
​string | null
​object

MerchantCommissionDecisionManagerRecord

name
​string · required
​MerchantCommissionConfigs · required
​ProgramMerchantCommissionConfigs · required
created_at
​integer · int64 · required
modified_at
​integer · int64 · required

MerchantConnectorAccountId

string

A type for merchant_connector_id that can be used for merchant_connector_account ids

MerchantConnectorCreate

Create a new Merchant Connector for the merchant account. The connector could be a payment processor / facilitator / acquirer or specialized services like Fraud / Accounting etc."
connector_type
​ConnectorType · enum · required

Type of the Connector for the financial use case. Could range from Payments to Accounting to Banking.

Enum values:
payment_processor
payment_vas
fin_operations
fiz_operations
networks
banking_entities
non_banking_finance
payout_processor
connector_name
​Connector · enum · required
Enum values:
flexifai
fiftyfourpay
honeycoin
k218pay
bitex
hypergate
maguapay
payadmit
connector_label
​string | null

This is an unique label you can generate and pass in order to identify this connector account on your Hyperswitch dashboard and reports. Eg: if your profile label is default, connector label can be stripe_default

Example: stripe_US_travel
profile_id
​string | null · maxLength: 64

Identifier for the profile, if not provided default will be chosen from merchant account

​object
​array | null

An object containing the details about the payment methods that need to be enabled under this merchant connector account

Example: [{"accepted_countries":{"list":["FR","DE","IN"],"type":"disable_only"},"accepted_currencies":{"list":["USD","EUR"],"type":"enable_only"},"installment_payment_enabled":true,"maximum_amount":68607706,"minimum_amount":1,"payment_method":"wallet","payment_method_issuers":["labore magna ipsum","aute"],"payment_method_types":["upi_collect","upi_intent"],"payment_schemes":["Discover","Discover"],"recurring_enabled":true}]
​object
metadata
​object | null

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

test_mode
​boolean | null

A boolean value to indicate if the connector is in Test mode. By default, its value is false.

Example: false
Default: false
disabled
​boolean | null

A boolean value to indicate if the connector is disabled. By default, its value is false.

Example: false
Default: false
​array | null

Contains the frm configs for the merchant connector

Example: [{"gateway":"stripe","payment_methods":[{"payment_method":"card","payment_method_types":[{"payment_method_type":"credit","card_networks":["Visa"],"flow":"pre","action":"cancel_txn"},{"payment_method_type":"debit","card_networks":["Visa"],"flow":"pre"}]}]}]
business_country
​string · enum
Enum values:
AF
AX
AL
DZ
AS
AD
AO
AI
business_label
​string | null

The business label to which the connector account is attached. To be deprecated soon. Use the 'profile_id' instead

business_sub_label
​string | null

The business sublabel to which the connector account is attached. To be deprecated soon. Use the 'profile_id' instead

Example: chase
merchant_connector_id
​string | null

Unique ID of the connector

Example: mca_5apGeP94tMts6rg3U3kR
pm_auth_config
​object | null
status
​string · enum
Enum values:
inactive
active
​
​object
​object
​object
linked_payment_mca_id
​string | null

Opt-in link to a payment-processor MCA of the same underlying connector. Set on a payout_processor MCA; when a payout is made, its terminal_balance hold is drawn directly from the linked payment MCA's balance instead of requiring this MCA's own balance to be seeded manually. Several payout MCAs may share the same linked payment MCA.

MerchantConnectorCurrencyLimits

terminal_currency
​Currency · enum · required

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

Enum values:
AED
AFN
ALL
AMD
ANG
AOA
ARS
AUD
terminal_min_amount
​MinorUnit · int64 · required

This Unit struct represents MinorUnit in which core amount works

terminal_max_amount
​MinorUnit · int64 · required

This Unit struct represents MinorUnit in which core amount works

​AcceptedPaymentCurrencyLimit[] · required

Accepted payment currencies with per-currency amount ranges

MerchantConnectorDeleteResponse

merchant_id
​string · maxLength: 255 · required

The identifier for the Merchant Account

Example: y3oqhf46pyzuxjbcn2giaqnb44
merchant_connector_id
​string · required

Unique ID of the connector

Example: mca_5apGeP94tMts6rg3U3kR
deleted
​boolean · required

If the connector is deleted or not

Example: false

MerchantConnectorDetails

connector_account_details
​object | null

Account details of the Connector. You can specify up to 50 keys, with key names up to 40 characters long and values up to 500 characters long. Useful for storing additional, structured information on an object.

metadata
​object | null

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

card_testing_guard_config
​object | null

MerchantConnectorDetailsWrap

Merchant connector details used to make payments.
creds_identifier
​string · required

Creds Identifier is to uniquely identify the credentials. Do not send any sensitive info, like encoded_data in this field. And do not send the string "null".

​object

MerchantConnectorId

merchant_id
​string · required
merchant_connector_id
​string · required

MerchantConnectorListResponse

connector_type
​ConnectorType · enum · required

Type of the Connector for the financial use case. Could range from Payments to Accounting to Banking.

Enum values:
payment_processor
payment_vas
fin_operations
fiz_operations
networks
banking_entities
non_banking_finance
payout_processor
connector_name
​Connector · enum · required
Enum values:
flexifai
fiftyfourpay
honeycoin
k218pay
bitex
hypergate
maguapay
payadmit
merchant_connector_id
​string · required

Unique ID of the merchant connector account

Example: mca_5apGeP94tMts6rg3U3kR
profile_id
​string · maxLength: 64 · required

Identifier for the profile, if not provided default will be chosen from merchant account

status
​ConnectorStatus · enum · required
Enum values:
inactive
active
connector_label
​string | null

A unique label to identify the connector account created under a profile

Example: stripe_US_travel
​array | null

An object containing the details about the payment methods that need to be enabled under this merchant connector account

Example: [{"accepted_countries":{"list":["FR","DE","IN"],"type":"disable_only"},"accepted_currencies":{"list":["USD","EUR"],"type":"enable_only"},"installment_payment_enabled":true,"maximum_amount":68607706,"minimum_amount":1,"payment_method":"wallet","payment_method_issuers":["labore magna ipsum","aute"],"payment_method_types":["upi_collect","upi_intent"],"payment_schemes":["Discover","Discover"],"recurring_enabled":true}]
test_mode
​boolean | null

A boolean value to indicate if the connector is in Test mode. By default, its value is false.

Example: false
Default: false
disabled
​boolean | null

A boolean value to indicate if the connector is disabled. By default, its value is false.

Example: false
Default: false
​array | null

Contains the frm configs for the merchant connector

Example: [{"gateway":"stripe","payment_methods":[{"payment_method":"card","payment_method_types":[{"payment_method_type":"credit","card_networks":["Visa"],"flow":"pre","action":"cancel_txn"},{"payment_method_type":"debit","card_networks":["Visa"],"flow":"pre"}]}]}]
business_country
​string · enum
Enum values:
AF
AX
AL
DZ
AS
AD
AO
AI
business_label
​string | null

The business label to which the connector account is attached. To be deprecated soon. Use the 'profile_id' instead

Example: travel
business_sub_label
​string | null

The business sublabel to which the connector account is attached. To be deprecated soon. Use the 'profile_id' instead

Example: chase
applepay_verified_domains
​array | null

identifier for the verified domains of a particular connector account

pm_auth_config
​object | null
group_id
​string | null

Connector group this processor belongs to, if any

MerchantConnectorResponse

Response of creating a new Merchant Connector for the merchant account."
connector_type
​ConnectorType · enum · required

Type of the Connector for the financial use case. Could range from Payments to Accounting to Banking.

Enum values:
payment_processor
payment_vas
fin_operations
fiz_operations
networks
banking_entities
non_banking_finance
payout_processor
connector_name
​Connector · enum · required
Enum values:
flexifai
fiftyfourpay
honeycoin
k218pay
bitex
hypergate
maguapay
payadmit
merchant_connector_id
​string · required

Unique ID of the merchant connector account

Example: mca_5apGeP94tMts6rg3U3kR
profile_id
​string · maxLength: 64 · required

Identifier for the profile, if not provided default will be chosen from merchant account

status
​ConnectorStatus · enum · required
Enum values:
inactive
active
connector_label
​string | null

A unique label to identify the connector account created under a profile

Example: stripe_US_travel
​object
​array | null

An object containing the details about the payment methods that need to be enabled under this merchant connector account

Example: [{"accepted_countries":{"list":["FR","DE","IN"],"type":"disable_only"},"accepted_currencies":{"list":["USD","EUR"],"type":"enable_only"},"installment_payment_enabled":true,"maximum_amount":68607706,"minimum_amount":1,"payment_method":"wallet","payment_method_issuers":["labore magna ipsum","aute"],"payment_method_types":["upi_collect","upi_intent"],"payment_schemes":["Discover","Discover"],"recurring_enabled":true}]
​object
metadata
​object | null

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

test_mode
​boolean | null

A boolean value to indicate if the connector is in Test mode. By default, its value is false.

Example: false
Default: false
disabled
​boolean | null

A boolean value to indicate if the connector is disabled. By default, its value is false.

Example: false
Default: false
​array | null

Contains the frm configs for the merchant connector

Example: [{"gateway":"stripe","payment_methods":[{"payment_method":"card","payment_method_types":[{"payment_method_type":"credit","card_networks":["Visa"],"flow":"pre","action":"cancel_txn"},{"payment_method_type":"debit","card_networks":["Visa"],"flow":"pre"}]}]}]
business_country
​string · enum
Enum values:
AF
AX
AL
DZ
AS
AD
AO
AI
business_label
​string | null

The business label to which the connector account is attached. To be deprecated soon. Use the 'profile_id' instead

Example: travel
business_sub_label
​string | null

The business sublabel to which the connector account is attached. To be deprecated soon. Use the 'profile_id' instead

Example: chase
applepay_verified_domains
​array | null

identifier for the verified domains of a particular connector account

pm_auth_config
​object | null
​
​object
​object

Connector details for webhook configuration via hyperswitch API

​object
group_id
​string | null

Connector group this processor belongs to, if any

​object
linked_payment_mca_id
​string | null

Opt-in link to a payment-processor MCA of the same underlying connector. Set on a payout_processor MCA; when a payout is made, its terminal_balance hold is drawn directly from the linked payment MCA's balance instead of requiring this MCA's own balance to be seeded manually. Several payout MCAs may share the same linked payment MCA.

MerchantConnectorUpdate

Create a new Merchant Connector for the merchant account. The connector could be a payment processor / facilitator / acquirer or specialized services like Fraud / Accounting etc."
connector_type
​ConnectorType · enum · required

Type of the Connector for the financial use case. Could range from Payments to Accounting to Banking.

Enum values:
payment_processor
payment_vas
fin_operations
fiz_operations
networks
banking_entities
non_banking_finance
payout_processor
status
​ConnectorStatus · enum · required
Enum values:
inactive
active
connector_label
​string | null

This is an unique label you can generate and pass in order to identify this connector account on your Hyperswitch dashboard and reports. Eg: if your profile label is default, connector label can be stripe_default

Example: stripe_US_travel
​object
​array | null

An object containing the details about the payment methods that need to be enabled under this merchant connector account

Example: [{"accepted_countries":{"list":["FR","DE","IN"],"type":"disable_only"},"accepted_currencies":{"list":["USD","EUR"],"type":"enable_only"},"installment_payment_enabled":true,"maximum_amount":68607706,"minimum_amount":1,"payment_method":"wallet","payment_method_issuers":["labore magna ipsum","aute"],"payment_method_types":["upi_collect","upi_intent"],"payment_schemes":["Discover","Discover"],"recurring_enabled":true}]
​object
metadata
​object | null

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

test_mode
​boolean | null

A boolean value to indicate if the connector is in Test mode. By default, its value is false.

Example: false
Default: false
disabled
​boolean | null

A boolean value to indicate if the connector is disabled. By default, its value is false.

Example: false
Default: false
​array | null

Contains the frm configs for the merchant connector

Example: [{"gateway":"stripe","payment_methods":[{"payment_method":"card","payment_method_types":[{"payment_method_type":"credit","card_networks":["Visa"],"flow":"pre","action":"cancel_txn"},{"payment_method_type":"debit","card_networks":["Visa"],"flow":"pre"}]}]}]
pm_auth_config
​object | null

pm_auth_config will relate MCA records to their respective chosen auth services, based on payment_method and pmt

​
​object
​object
​object
linked_payment_mca_id
​string | null

Opt-in link to a payment-processor MCA of the same underlying connector. Only meaningful on a payout_processor MCA. Omitted = unchanged; null = unlink; string = set/replace link.

MerchantConnectorWebhookDetails

merchant_secret
​string · required
additional_secret
​string · required

MerchantCountryCode

string

A wrapper type for merchant country codes that provides validation and conversion functionality.

This type stores a country code as a string and provides methods to validate it and convert it to a Country enum variant.

MerchantDetails

primary_contact_person
​string | null · maxLength: 255

The merchant's primary contact name

Example: John Doe
primary_phone
​string | null · maxLength: 255

The merchant's primary phone number

Example: 999999999
primary_email
​string | null · maxLength: 255

The merchant's primary email address

Example: johndoe@test.com
secondary_contact_person
​string | null · maxLength: 255

The merchant's secondary contact name

Example: John Doe2
secondary_phone
​string | null · maxLength: 255

The merchant's secondary phone number

Example: 999999988
secondary_email
​string | null · maxLength: 255

The merchant's secondary email address

Example: johndoe2@test.com
website
​string | null · maxLength: 255

The business website of the merchant

Example: www.example.com
about_business
​string | null · maxLength: 255

A brief description about merchant's business

Example: Online Retail with a wide selection of organic products for North America
​object

Address details

merchant_tax_registration_id
​string | null

MerchantId

string

A type for merchant_id that can be used for merchant ids

MerchantProductType

string · enum
Enum values:
orchestration
vault
recon
recovery
cost_observability
dynamic_routing

MerchantRecipientData

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · requires: connector_recipient_id
type = object · requires: wallet_id
type = object · requires: account_data
Properties for Variant 1:
connector_recipient_id
​string | null · required

MerchantRoutingAlgorithm

Routing algorithm configuration created for a merchant. Represents a fully defined routing strategy scoped to a profile and transaction type.
id
​string · required

Unique identifier of the routing configuration.

Example:

JSONCode
"routing_abc123"
Example: routing_abc123
profile_id
​string · required

Profile ID to which this routing configuration belongs.

Example:

JSONCode
"profile_123"
Example: profile_123
name
​string · required

Human-readable name of the routing configuration.

Example:

JSONCode
"default_card_routing"
Example: default_card_routing
description
​string · required

Description explaining the purpose of this routing configuration.

Example:

JSONCode
"Primary routing strategy for card payments"
Example: Primary routing strategy for card payments
​RoutingAlgorithmWrapper · required
created_at
​integer · int64 · required

Timestamp (in milliseconds since epoch) when the routing configuration was created.

Example:

JSONCode
1718000000000
Example: 1718000000000
modified_at
​integer · int64 · required

Timestamp (in milliseconds since epoch) when the routing configuration was last modified.

Example:

JSONCode
1718050000000
Example: 1718050000000
algorithm_for
​TransactionType · enum · required
Enum values:
payment
payout
three_ds_authentication

MetadataValue

key
​string · required
value
​string · required

Method

string · enum
Enum values:
GET
POST
PUT
DELETE
PATCH

MifinityData

date_of_birth
​string · date · required
language_preference
​string | null

MinorUnit

integer · int64

This Unit struct represents MinorUnit in which core amount works

MitCategory

string · enum
Enum values:
installment
unscheduled
recurring
resubmission

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.

MobilePayRedirection

MobilePaymentConsent

string · enum
Enum values:
consent_required
consent_not_required
consent_optional

MobilePaymentData

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · requires: direct_carrier_billing
Properties for Variant 1:
​object · required

MobilePaymentNextStepData

consent_data_required
​MobilePaymentConsent · enum · required
Enum values:
consent_required
consent_not_required
consent_optional

MobilePaymentResponse

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · requires: direct_carrier_billing
Properties for Variant 1:
​object · required

MockMode

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = string
type = string
type = object · requires: forced
Properties for Variant 1:
string · enum
Enum values:
disabled

MomoRedirection

MultibancoBillingDetails

email
​string | null

MultibancoTransferInstructions

reference
​string · required
entity
​string · required

NetworkDetails

network_advice_code
​string | null

NetworkParams

Represents additional network-level parameters for 3DS processing.
​object

Represents network-specific parameters for the Cartes Bancaires 3DS process.

NetworkTokenData

network_token
​string · required

The network token

Example: 4604000460040787
token_exp_month
​string · required

The token's expiry month

Example: 05
token_exp_year
​string · required

The token's expiry year

Example: 24
token_cryptogram
​string · required

The token cryptogram

card_holder_name
​string · required

The card holder's name

Example: John Test
card_network
​string · enum

Indicates the card network.

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

The type of the card such as Credit, Debit

Example: CREDIT
card_issuing_country
​string | null

The country in which the card was issued

Example: INDIA
bank_code
​string | null

The bank code of the bank that issued the card

Example: JP_AMEX
card_issuer
​string | null

The name of the issuer of card

Example: chase
nick_name
​string | null

The card holder's nick name

Example: John Test
eci
​string | null

The ECI(Electronic Commerce Indicator) value for this authentication.

NetworkTokenResponse

last4
​string | null

The last four digit of the network token

card_type
​string | null

The type of the card such as Credit, Debit

card_network
​string · enum

Indicates the card network.

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

The ISIN of the token

card_issuer
​string | null

The name of the issuer of card

card_issuing_country
​string | null

The country in which the card was issued

token_exp_month
​string | null

The expiry month of the network token

token_exp_year
​string | null

The expiry year of the network token

card_holder_name
​string | null

The card holder's name

NetworkTransactionIdAndCardDetails

card_number
​string · required

The card number

Example: 4242424242424242
card_exp_month
​string · required

The card's expiry month

Example: 24
card_exp_year
​string · required

The card's expiry year

Example: 24
card_holder_name
​string · required

The card holder's name

Example: John Test
network_transaction_id
​string · required

The network transaction ID provided by the card network during a CIT (Customer Initiated Transaction), when setup_future_usage is set to off_session.

card_issuer
​string | null

The name of the issuer of card

Example: chase
card_network
​string · enum

Indicates the card network.

Enum values:
Visa
Mastercard
AmericanExpress
JCB
DinersClub
Discover
CartesBancaires
UnionPay
card_type
​string | null
card_issuing_country
​string | null
card_issuing_country_code
​string | null
bank_code
​string | null
nick_name
​string | null

The card holder's nick name

Example: John Test

NetworkTransactionIdAndDecryptedWalletTokenDetails

Network Transaction ID and Decrypted Wallet Token Details
decrypted_token
​string · required

The Decrypted Token

Example: 4604000460040787
token_exp_month
​string · required

The token's expiry month

Example: 05
token_exp_year
​string · required

The token's expiry year

Example: 24
card_holder_name
​string · required

The card holder's name

Example: John Test
network_transaction_id
​string · required

The network transaction ID provided by the card network during a Customer Initiated Transaction (CIT) when setup_future_usage is set to off_session.

eci
​string | null

ECI indicator of the card

token_source
​string · enum

Source of the token

Enum values:
google_pay
apple_pay
Example: google_pay, apple_pay
card_network
​string · enum

Indicates the card network.

Enum values:
Visa
Mastercard
AmericanExpress
JCB
DinersClub
Discover
CartesBancaires
UnionPay

NetworkTransactionIdAndNetworkTokenDetails

network_token
​string · required

The Network Token

Example: 4604000460040787
token_exp_month
​string · required

The token's expiry month

Example: 05
token_exp_year
​string · required

The token's expiry year

Example: 24
card_holder_name
​string · required

The card holder's name

Example: John Test
network_transaction_id
​string · required

The network transaction ID provided by the card network during a Customer Initiated Transaction (CIT) when setup_future_usage is set to off_session.

card_network
​string · enum

Indicates the card network.

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

The type of the card such as Credit, Debit

Example: CREDIT
card_issuing_country
​string | null

The country in which the card was issued

Example: INDIA
bank_code
​string | null

The bank code of the bank that issued the card

Example: JP_AMEX
card_issuer
​string | null

The name of the issuer of card

Example: chase
nick_name
​string | null

The card holder's nick name

Example: John Test
eci
​string | null

The ECI(Electronic Commerce Indicator) value for this authentication.

NextAction

url
​string · required

The URL for authenticatating the user.

http_method
​Method · enum · required
Enum values:
GET
POST
PUT
DELETE
PATCH

NextActionCall

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = string
type = string
type = string
type = string
type = string
type = object · requires: deny
type = string
Properties for Variant 1:
string · enum
Enum values:
post_session_tokens

The next action call is Post Session Tokens

NextActionData

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · type="redirect_to_url" · requires: redirect_to_url
type = object · type="redirect_inside_popup" · requires: popup_url, redirect_response_url
type = object · type="display_bank_transfer_information" · requires: bank_transfer_steps_and_charges_details
type = object · type="third_party_sdk_session_token"
type = object · type="qr_code_information" · requires: image_data_url, qr_code_url
type = object · type="fetch_qr_code_information" · requires: qr_code_fetch_url
type = object · type="invoke_upi_intent_sdk" · requires: sdk_uri, display_from_timestamp
type = object · type="invoke_upi_qr_flow" · requires: qr_code_url, display_from_timestamp
type = object · type="display_voucher_information" · requires: voucher_details
type = object · type="wait_screen_information" · requires: display_from_timestamp
type = object · type="three_ds_invoke" · requires: three_ds_data
type = object · type="invoke_sdk_client" · requires: next_action_data
type = object · type="collect_otp" · requires: consent_data_required
type = object · type="invoke_hidden_iframe" · requires: iframe_data
Properties for Variant 1:
Contains the url for redirection flow
redirect_to_url
​string · required
type
​string · enum · required
Enum values:
redirect_to_url

NextActionType

string · enum
Enum values:
redirect_to_url
display_qr_code
invoke_sdk_client
trigger_api
display_bank_transfer_information
display_wait_screen
collect_otp
redirect_inside_popup

NoThirdPartySdkSessionResponse

epoch_timestamp
​integer · int64 · min: 0 · required

Timestamp at which session is requested

expires_at
​integer · int64 · min: 0 · required

Timestamp at which session expires

merchant_session_identifier
​string · required

The identifier for the merchant session

nonce
​string · required

Apple pay generated unique ID (UUID) value

merchant_identifier
​string · required

The identifier for the merchant

domain_name
​string · required

The domain name of the merchant which is registered in Apple Pay

display_name
​string · required

The name to be displayed on Apple Pay button

signature
​string · required

A string which represents the properties of a payment

operational_analytics_identifier
​string · required

The identifier for the operational analytics

retries
​integer · int32 · min: 0 · required

The number of retries to get the session response

psp_id
​string · required

The identifier for the connector transaction

NoonData

order_category
​string | null

Information about the order category that merchant wants to specify at connector level. (e.g. In Noon Payments it can take values like "pay", "food", or any other custom string set by the merchant in Noon's Dashboard)

NullObject

NumberComparison

Represents a number comparison for "NumberComparisonArrayValue"
comparisonType
​ComparisonType · enum · required

Conditional comparison type

Enum values:
equal
not_equal
less_than
less_than_equal
greater_than
greater_than_equal
number
​MinorUnit · int64 · required

This Unit struct represents MinorUnit in which core amount works

OnlineMandate

Details of online mandate
ip_address
​string · required

Ip address of the customer machine from which the mandate was created

Example: 123.32.25.123
user_agent
​string · required

The user-agent of the customer's browser

OpenBankingData

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · requires: open_banking_pis
Properties for Variant 1:
open_banking_pis
​object · required

OpenBankingResponse

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · requires: open_banking_pis
Properties for Variant 1:
open_banking_pis
​object · required

OpenBankingSessionToken

open_banking_session_token
​string · required

The session token for OpenBanking Connectors

OpenBankingUk

account_holder_name
​string · required

Account holder name

Example: John Doe
iban
​string · required

International Bank Account Number (iban) - used in many countries for identifying a bank along with it's customer.

Example: DE89370400440532013000

OpenBankingUkAdditionalData

Masked payout method details for OpenBankingUK bank redirect payout method
account_holder_name
​string · required

Account holder name

Example: John Doe
iban
​string · required

International Bank Account Number (iban) - used in many countries for identifying a bank along with it's customer.

Example: DE89370400440532013000

OpenRouterDecideGatewayRequest

Request to decide the optimal gateway for routing a payment
​PaymentInfo · required

Payment information used for routing decision-making

merchantId
​string · required

Profile ID of the merchant

Example: pro_aMoPnEkgCVnh2WVsFe32
eligibleGatewayList
​array | null

List of eligible gateways for routing consideration

Example: ["stripe:mca_123", "adyen:mca_456"]
rankingAlgorithm
​string · enum
Enum values:
SR_BASED_ROUTING
PL_BASED_ROUTING
NTW_BASED_ROUTING
eliminationEnabled
​boolean | null

Whether elimination logic is enabled for filtering gateways

Example: true

Order

on
​SortOn · enum · required
Enum values:
amount
created
modified
by
​SortBy · enum · required
Enum values:
asc
desc

OrderDetailsWithAmount

product_name
​string · maxLength: 255 · required

Name of the product that is being purchased

Example: shirt
quantity
​integer · int32 · min: 0 · required

The quantity of the product to be purchased

Example: 1
amount
​integer · int64 · required

the amount per quantity of product

tax_rate
​number | null · double

tax rate applicable to the product

total_tax_amount
​integer | null · int64

total tax amount applicable to the product

requires_shipping
​boolean | null
product_img_link
​string | null

The image URL of the product

product_id
​string | null

ID of the product that is being purchased

category
​string | null

Category of the product that is being purchased

sub_category
​string | null

Sub category of the product that is being purchased

brand
​string | null

Brand of the product that is being purchased

product_type
​string · enum
Enum values:
physical
digital
travel
ride
event
accommodation
product_tax_code
​string | null

The tax code for the product

description
​string | null

Description for the item

sku
​string | null

Stock Keeping Unit (SKU) or the item identifier for this item.

upc
​string | null

Universal Product Code for the item.

commodity_code
​string | null

Code describing a commodity or a group of commodities pertaining to goods classification.

unit_of_measure
​string | null

Unit of measure used for the item quantity.

total_amount
​integer | null · int64

Total amount for the item.

unit_discount_amount
​integer | null · int64

Discount amount applied to this item.

OrganizationCreateRequest

organization_name
​string · required

Name of the organization

organization_details
​object | null

Details about the organization

metadata
​object | null

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

OrganizationResponse

organization_id
​string · minLength: 1 · maxLength: 64 · required

The unique identifier for the Organization

Example: org_q98uSGAYbjEwqs0mJwnz
modified_at
​string · date-time · required
created_at
​string · date-time · required
organization_name
​string | null

Name of the Organization

organization_details
​object | null

Details about the organization

metadata
​object | null

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

organization_type
​string · enum
Enum values:
standard
platform

OrganizationType

string · enum
Enum values:
standard
platform

OrganizationUpdateRequest

platform_merchant_id
​string · required

Platform merchant id is unique distiguisher for special merchant in the platform org

organization_name
​string | null

Name of the organization

organization_details
​object | null

Details about the organization

metadata
​object | null

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

OutgoingWebhook

merchant_id
​string · required

The merchant id of the merchant

event_id
​string · required

The unique event id for each webhook

event_type
​EventType · enum · required
Enum values:
payment_succeeded
payment_failed
payment_processing
payment_cancelled
payment_cancelled_post_capture
payment_authorized
payment_partially_authorized
payment_captured
​OutgoingWebhookContent · required
timestamp
​string · date-time

The time at which webhook was sent

OutgoingWebhookContent

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · type="payment_details" · requires: object
type = object · type="refund_details" · requires: object
type = object · type="dispute_details" · requires: object
type = object · type="mandate_details" · requires: object
type = object · type="payout_details" · requires: object
type = object · type="subscription_details" · requires: object
Properties for PaymentsResponse:
type
​string · enum · required
Enum values:
payment_details
​PaymentsResponse · required

OutgoingWebhookEndpointStatus

string · enum
Enum values:
active
inactive
deprecated

OutgoingWebhookRequestContent

The request information (headers and body) sent in the webhook.
body
​string · required

The request body sent in the webhook.

headers
​array[] · required

The request headers sent in the webhook.

Example: [["content-type","application/json"],["content-length","1024"]]

OutgoingWebhookResponseContent

The response information (headers, body and status code) received for the webhook sent.
body
​string | null

The response body received for the webhook sent.

headers
​array | null

The response headers received for the webhook sent.

Example: [["content-type","application/json"],["content-length","1024"]]
status_code
​integer | null · int32 · min: 0

The HTTP status code for the webhook sent.

Example: 200
error_message
​string | null

Error message in case any error occurred when trying to deliver the webhook.

Example: 200

PartnerApplicationDetails

Information identifying partner / external platform details
name
​string | null

Name of the partner/external platform

version
​string | null

Version of the partner/external platform

Example: 1.0.0
integrator
​string | null

Integrator

PartnerMerchantIdentifierDetails

Information identifying partner and merchant application initiating the request
​object

Information identifying partner / external platform details

​object

Information identifying merchant details

Passthrough

psp_token
​string · required

PSP token generated for the payout method

Example: token_12345
token_type
​PaymentMethodType · enum · required

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

Enum values:
ach
affirm
afterpay_clearpay
alfamart
ali_pay
ali_pay_hk
alma
amazon_pay

PassthroughAdditionalData

additional payout method details for passthrough payout method
psp_token
​string · required

Psp_token of the passthrough flow

Example: token_12345
token_type
​PaymentMethodType · enum · required

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

Enum values:
ach
affirm
afterpay_clearpay
alfamart
ali_pay
ali_pay_hk
alma
amazon_pay

PauseOption

string · enum
Enum values:
immediately
end_of_term
specific_date

PauseSubscriptionRequest

Request payload for pausing a subscription.
pause_option
​string · enum
Enum values:
immediately
end_of_term
specific_date
pause_at
​string | null

Optional date when the subscription should be paused (if not provided, pauses immediately)

PauseSubscriptionResponse

Response payload returned after successfully pausing a subscription.
id
​SubscriptionId · required

A type for subscription_id that can be used for subscription ids

status
​SubscriptionStatus · enum · required

Possible states of a subscription lifecycle.

  • Created: Subscription was created but not yet activated.
  • Active: Subscription is currently active.
  • InActive: Subscription is inactive.
  • Pending: Subscription is pending activation.
  • Trial: Subscription is in a trial period.
  • Paused: Subscription is paused.
  • Unpaid: Subscription is unpaid.
  • Onetime: Subscription is a one-time payment.
  • Cancelled: Subscription has been cancelled.
  • Failed: Subscription has failed.
Enum values:
active
created
in_active
pending
trial
paused
unpaid
onetime
profile_id
​ProfileId · required

A type for profile_id that can be used for business profile ids

merchant_id
​MerchantId · required

A type for merchant_id that can be used for merchant ids

customer_id
​CustomerId · required

A type for customer_id that can be used for customer ids

merchant_reference_id
​string | null

Merchant specific Unique identifier.

paused_at
​string | null

Date when the subscription was paused

PayLaterData

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · requires: klarna_redirect
type = object · requires: klarna_sdk
type = object · requires: affirm_redirect
type = object · requires: afterpay_clearpay_redirect
type = object · requires: pay_bright_redirect
type = object · requires: flexiti_redirect
type = object · requires: walley_redirect
type = object · requires: alma_redirect
type = object · requires: atome_redirect
type = object · requires: breadpay_redirect
type = object · requires: payjustnow_redirect
Properties for Variant 1:
​object · required

For KlarnaRedirect as PayLater Option

PayPalWalletData

token
​string · required

Token generated for the Apple pay

PaylaterResponse

​object

PaymentAttemptDetailedResponse

Extended payment attempt information for the detailed view. Carries all fields from [`PaymentAttemptResponse`] plus: - `routing_details` — the structured routing decision (connector chosen, algorithm used, fallback order). - `surcharge_details` — explicitly surfaced surcharge breakdown. - `connector_metadata` — full connector metadata.
attempt_id
​string · required
status
​AttemptStatus · enum · required

The status of the attempt

Enum values:
started
authentication_failed
router_declined
authentication_pending
authentication_successful
authorized
authorization_failed
charged
amount
​integer · int64 · required
created_at
​string · required
modified_at
​string · required
​PaymentCaptureFeeDetail[] · required

Authorized fee snapshots for this attempt's captures.

Legacy attempt-level snapshots have capture_id: null.

order_tax_amount
​integer | null · int64
currency
​string · enum

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

Enum values:
AED
AFN
ALL
AMD
ANG
AOA
ARS
AUD
connector
​string | null
merchant_connector_id
​string | null
error_message
​string | null

Human-readable error message from the connector, if the attempt failed.

payment_method
​string · enum

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

Enum values:
card
card_redirect
pay_later
wallet
bank_redirect
bank_transfer
crypto
bank_debit
connector_transaction_id
​string | null
capture_method
​string · enum

Specifies how the payment is captured.

  • automatic: Funds are captured immediately after successful authorization. This is the default behavior if the field is omitted.
  • manual: Funds are authorized but not captured. A separate request to the /payments/{payment_id}/capture endpoint is required to capture the funds.
Enum values:
automatic
manual
manual_multiple
scheduled
sequential_automatic
authentication_type
​string · enum

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

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

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

Enum values:
three_ds
no_three_ds
cancellation_reason
​string | null
mandate_id
​string | null
error_code
​string | null

Connector-specific error code.

payment_token
​string | null
connector_metadata
​
payment_experience
​string · enum

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

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

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

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

Connector-side reference ID for reconciliation.

unified_code
​string | null

Unified error code across connectors.

TODO (not yet live).

unified_message
​string | null

Unified error message across connectors.

TODO (not yet live).

client_source
​string | null

Client source header from the confirm request.

client_version
​string | null

Client version header from the confirm request.

​object

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

​object

Human-readable summary of the routing decision that was applied to a specific payment attempt.

The raw straight_through_algorithm JSON stored in payment_attempts is deserialized here so dashboards can render the connector order, algorithm type, and the connector that was actually selected.

algorithm uses [StraightThroughAlgorithmInner] rather than [StraightThroughAlgorithm] so that it serialises directly as {"type": "single", "data": ...}. [StraightThroughAlgorithm] wraps through [StraightThroughAlgorithmSerde::Nested] which would produce an extra {"algorithm": {...}} nesting layer in the JSON response.

​object

Details of surcharge applied on this payment, if applicable

PaymentAttemptResponse

attempt_id
​string · required

A unique identifier for this specific payment attempt.

status
​AttemptStatus · enum · required

The status of the attempt

Enum values:
started
authentication_failed
router_declined
authentication_pending
authentication_successful
authorized
authorization_failed
charged
amount
​integer · int64 · 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.,

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

Time at which the payment attempt was created

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

Time at which the payment attempt was last modified

Example: 2022-09-10T10:11:12Z
​PaymentCaptureFeeDetail[] · required

Authorized fee snapshots for this attempt's captures.

Legacy attempt-level snapshots have capture_id: null.

order_tax_amount
​integer | null · int64

The payment attempt tax_amount.

Example: 6540
currency
​string · enum

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

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

The name of the payment connector (e.g., 'stripe', 'adyen') used for this attempt.

merchant_connector_id
​string | null

Merchant connector account used for this attempt. Present on terminal-scoped velocity declines so attempt history can show which MCA blocked the request.

error_message
​string | null

A human-readable message from the connector explaining the error, if one occurred during this payment attempt.

payment_method
​string · enum

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

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

A unique identifier for a payment provided by the connector

capture_method
​string · enum

Specifies how the payment is captured.

  • automatic: Funds are captured immediately after successful authorization. This is the default behavior if the field is omitted.
  • manual: Funds are authorized but not captured. A separate request to the /payments/{payment_id}/capture endpoint is required to capture the funds.
Enum values:
automatic
manual
manual_multiple
scheduled
sequential_automatic
authentication_type
​string · enum

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

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

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

Enum values:
three_ds
no_three_ds
Default: three_ds
cancellation_reason
​string | null

If the payment was cancelled the reason will be provided here

mandate_id
​string | null

If this payment attempt is associated with a mandate (e.g., for a recurring or subsequent payment), this field will contain the ID of that mandate.

error_code
​string | null

The error code returned by the connector if this payment attempt failed. This code is specific to the connector.

payment_token
​string | null

If a tokenized (saved) payment method was used for this attempt, this field contains the payment token representing that payment method.

connector_metadata
​

Additional data related to some connectors

payment_experience
​string · enum

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

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

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

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

The connector's own reference or transaction ID for this specific payment attempt. Useful for reconciliation with the connector.

Example: 993672945374576J
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

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

client_source
​string | null

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

client_version
​string | null

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

​object

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

PaymentCaptureFeeDetail

One authorized fee snapshot for a payment capture.
reference_id
​string · required

Idempotency reference. Legacy rows use the payment attempt identifier.

created_at
​string · required

Time when the snapshot was stored.

Example: 2024-01-01T00:00:00Z
currency
​string · required

Three-letter ISO 4217 currency code.

base_amount
​integer · int64 · required

Captured base amount, in minor units.

capture_id
​string | null

Internal capture identifier. Legacy attempt-level snapshots contain null.

merchant_commission_amount
​integer | null · int64

Merchant commission snapshot. null means that no snapshot exists.

provider_cost
​integer | null · int64

Provider cost snapshot. This field requires connector-cost read access.

margin
​integer | null · int64

Merchant commission minus provider cost. This field requires connector-cost read access.

merchant_commission_rate
​

Resolved merchant rate snapshot.

provider_cost_rate
​

Resolved provider rate snapshot. This field requires connector-cost read access.

merchant_commission_rule
​string | null

Resolved merchant rule name.

provider_cost_rule
​string | null

Resolved provider rule name. This field requires connector-cost read access.

PaymentChannel

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = string
type = string
type = string
type = object · requires: other
Properties for Variant 1:
string · enum
Enum values:
ecommerce

PaymentChargeType

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · requires: Stripe
Properties for Variant 1:
Stripe
​StripeChargeType · enum · required
Enum values:
direct
destination

PaymentCreatePaymentLinkConfig

Configure a custom payment link for the particular payment
theme
​string | null · maxLength: 255

custom theme for the payment link

Example: #4E6ADD
logo
​string | null · maxLength: 255

merchant display logo

Example: https://i.pinimg.com/736x/4d/83/5c/4d835ca8aafbbb15f84d07d926fda473.jpg
seller_name
​string | null · maxLength: 255

Custom merchant name for payment link

Example: hyperswitch
sdk_layout
​string | null · maxLength: 255

Custom layout for sdk

Example: accordion
display_sdk_only
​boolean | null

Display only the sdk for payment link

Example: true
Default: false
enabled_saved_payment_method
​boolean | null

Enable saved payment method option for payment link

Example: true
Default: false
hide_card_nickname_field
​boolean | null

Hide card nickname field option for payment link

Example: true
Default: false
show_card_form_by_default
​boolean | null

Show card form by default for payment link

Example: true
Default: true
​array | null

Dynamic details related to merchant to be rendered in payment link

​object
details_layout
​string · enum
Enum values:
layout1
layout2
payment_button_text
​string | null

Text for payment link's handle confirm button

custom_message_for_card_terms
​string | null

Text for customizing message for card terms

​PaymentMethodConfig[]

List of custom T&C messages grouped by payment method

payment_button_colour
​string | null

Custom background colour for payment link's handle confirm button

skip_status_screen
​boolean | null

Skip the status screen after payment completion

payment_button_text_colour
​string | null

Custom text colour for payment link's handle confirm button

background_colour
​string | null

Custom background colour for the payment link

​object | null

SDK configuration rules

​object | null

Payment link configuration rules

enable_button_only_on_form_ready
​boolean | null

Flag to enable the button only when the payment form is ready for submission

payment_form_header_text
​string | null

Optional header for the SDK's payment form

payment_form_label_type
​string · enum
Enum values:
above
floating
never
show_card_terms
​string · enum
Enum values:
always
auto
never
is_setup_mandate_flow
​boolean | null

Boolean to control payment button text for setup mandate calls

color_icon_card_cvc_error
​string | null

Hex color for the CVC icon during error state

PaymentData

Represents the payment data used in the 3DS decision rule.
amount
​integer · int64 · required

The amount of the payment in minor units (e.g., cents for USD).

currency
​Currency · enum · required

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

Enum values:
AED
AFN
ALL
AMD
ANG
AOA
ARS
AUD

PaymentDetailedResponse

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

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

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

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

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

Three-letter ISO 4217 currency code.

​PaymentAttemptDetailedResponse[] · required

The list is ordered by created_at ascending.

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

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

​FieldOrigins · required

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

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

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

Merchant-supplied description for this payment.

metadata
​

Merchant-supplied metadata key/value pairs.

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

Details of customer attached to this payment

​object
​object
​object

Statistics for a customer within a single profile

​object

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

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

PaymentDetails

payment_method
​string · enum

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

Enum values:
card
card_redirect
pay_later
wallet
bank_redirect
bank_transfer
crypto
bank_debit
payment_method_type
​string · enum

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

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

The payment method information provided for making a payment

setup_future_usage
​string · enum

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

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

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.

return_url
​string | null

The url to which user must be redirected to after completion of the purchase

capture_method
​string · enum

Specifies how the payment is captured.

  • automatic: Funds are captured immediately after successful authorization. This is the default behavior if the field is omitted.
  • manual: Funds are authorized but not captured. A separate request to the /payments/{payment_id}/capture endpoint is required to capture the funds.
Enum values:
automatic
manual
manual_multiple
scheduled
sequential_automatic
authentication_type
​string · enum

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

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

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

Enum values:
three_ds
no_three_ds
payment_type
​string · enum

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

Enum values:
normal
new_mandate
setup_mandate
recurring_mandate
installment
payment_method_id
​string | null

PaymentDetailsQueryParams

Query parameters for `GET /payments/{payment_id}/details`.
expand_customer_statistics
​boolean | null

When true, includes customer payment statistics for this payment's profile (OLAP).

PaymentErrorDetails

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

Unified error details standardized across all payment connectors

​object

Error details from the card issuer

​object

Error details from the payment connector

PaymentExperience

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

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

PaymentExperienceTypes

eligible_connectors
​string[] · required

The list of eligible connectors for a given payment experience

Example: ["stripe","adyen"]
payment_experience_type
​string · enum

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

Enum values:
redirect_to_url
invoke_sdk_client
display_qr_code
one_click
link_wallet
invoke_payment_app
display_wait_screen
collect_otp

PaymentFeeSummary

The authorized fee snapshot aggregated across a payment's capture rows. `None` on the containing response means that no merchant commission snapshot exists. A calculated zero remains `Some(0)`.
currency
​string · required

Three-letter ISO 4217 currency code shared by all aggregated captures.

base_amount
​integer · int64 · required

Sum of the captured base amounts, in minor units.

merchant_commission_amount
​integer · int64 · required

Sum of the merchant commission snapshots, in minor units.

provider_cost
​integer | null · int64

Sum of provider costs. This field requires connector-cost read access.

margin
​integer | null · int64

Merchant commission minus provider cost. This field requires connector-cost read access.

merchant_commission_rate
​

Resolved merchant rate when all capture rows contain the same snapshot.

provider_cost_rate
​

Resolved provider rate when all capture rows contain the same snapshot.

merchant_commission_rule
​string | null

Resolved merchant rule when all capture rows contain the same rule.

provider_cost_rule
​string | null

Resolved provider rule when all capture rows contain the same rule.

PaymentFieldValidationField

string · enum
Enum values:
email
cardholder_name

Payment field subject to custom regex validation.

PaymentFieldValidationMode

string · enum
Enum values:
allow
deny

Whether a regex rule allows or denies matching values.

PaymentFieldValidationParameter

One regex rule that applies to a payment field.
field
​PaymentFieldValidationField · enum · required

Payment field subject to custom regex validation.

Enum values:
email
cardholder_name
mode
​PaymentFieldValidationMode · enum · required

Whether a regex rule allows or denies matching values.

Enum values:
allow
deny
pattern
​string · required

Rust regex pattern. Case-sensitive unless the pattern uses an inline flag such as (?i). Must be non-empty after trim. Max length: [MAX_PATTERN_BYTES] bytes.

description
​string | null

PaymentFieldValidationParamsRequest

Full parameter list for a scope. Replaces the previous list on PUT.
​PaymentFieldValidationParameter[] · required

PaymentFieldValidationParamsResponse

Stored / returned parameter list for a scope.
​PaymentFieldValidationParameter[] · required
scope
​PaymentFieldValidationScope · enum · required

Ownership scope for payment field validation rules.

Enum values:
organization
merchant
connector
merchant_connector_id
​string | null

PaymentFieldValidationScope

string · enum
Enum values:
organization
merchant
connector

Ownership scope for payment field validation rules.

PaymentFieldValidationScopeQuery

Scope query for merchant routes whose body is shared across scopes.
scope
​PaymentFieldValidationScope · enum

Ownership scope for payment field validation rules.

Enum values:
organization
merchant
connector
merchant_connector_id
​string | null

PaymentId

string

A type for payment_id that can be used for payment ids

PaymentInfo

Payment information used for routing decision-making
paymentId
​string · required

Unique identifier for the payment transaction

Example: pay_12345
amount
​integer · int64 · required

Payment amount in minor units

Example: 100
currency
​string · required

Currency code for the payment

Example: USD
paymentType
​string · required

Type of payment transaction being processed

Example: ORDER_PAYMENT
metadata
​string · required

Optional metadata associated with the payment

Example: metadata
paymentMethodType
​string · required

Specific payment method type being used

Example: upi
paymentMethod
​string · required

General payment method category

Example: upi
cardIsin
​string · required

Card Issuer Identification Number (first 6 digits of card)

Example: 424242

PaymentIntentStateMetadata

Additional metadata for payment intent state containing refunded and disputed amounts
total_refunded_amount
​integer · int64

This Unit struct represents MinorUnit in which core amount works

total_disputed_amount
​integer · int64

This Unit struct represents MinorUnit in which core amount works

​object

Additional metadata for payment intent state containing refunded and disputed amounts

PaymentLinkBackgroundImageConfig

url
​string · required

URL of the image

Example: https://hyperswitch.io/favicon.ico
position
​string · enum
Enum values:
left
top left
top
top right
right
bottom right
bottom
bottom left
​

PaymentLinkConfig

theme
​string · required

custom theme for the payment link

logo
​string · required

merchant display logo

seller_name
​string · required

Custom merchant name for payment link

sdk_layout
​string · required

Custom layout for sdk

display_sdk_only
​boolean · required

Display only the sdk for payment link

enabled_saved_payment_method
​boolean · required

Enable saved payment method option for payment link

hide_card_nickname_field
​boolean · required

Hide card nickname field option for payment link

show_card_form_by_default
​boolean · required

Show card form by default for payment link

enable_button_only_on_form_ready
​boolean · required

Flag to enable the button only when the payment form is ready for submission

allowed_domains
​array | null · unique

A list of allowed domains (glob patterns) where this link can be embedded / opened from

​array | null

Dynamic details related to merchant to be rendered in payment link

​object
details_layout
​string · enum
Enum values:
layout1
layout2
branding_visibility
​boolean | null

Toggle for HyperSwitch branding visibility

payment_button_text
​string | null

Text for payment link's handle confirm button

custom_message_for_card_terms
​string | null

Text for customizing message for card terms

​PaymentMethodConfig[]

List of custom T&C messages grouped by payment method

payment_button_colour
​string | null

Custom background colour for payment link's handle confirm button

skip_status_screen
​boolean | null

Skip the status screen after payment completion

payment_button_text_colour
​string | null

Custom text colour for payment link's handle confirm button

background_colour
​string | null

Custom background colour for the payment link

​object | null

SDK configuration rules

​object | null

Payment link configuration rules

payment_form_header_text
​string | null

Optional header for the SDK's payment form

payment_form_label_type
​string · enum
Enum values:
above
floating
never
show_card_terms
​string · enum
Enum values:
always
auto
never
is_setup_mandate_flow
​boolean | null

Boolean to control payment button text for setup mandate calls

color_icon_card_cvc_error
​string | null

Hex color for the CVC icon during error state

PaymentLinkConfigRequest

theme
​string | null · maxLength: 255

custom theme for the payment link

Example: #4E6ADD
logo
​string | null · maxLength: 255

merchant display logo

Example: https://i.pinimg.com/736x/4d/83/5c/4d835ca8aafbbb15f84d07d926fda473.jpg
seller_name
​string | null · maxLength: 255

Custom merchant name for payment link

Example: hyperswitch
sdk_layout
​string | null · maxLength: 255

Custom layout for sdk

Example: accordion
display_sdk_only
​boolean | null

Display only the sdk for payment link

Example: true
Default: false
enabled_saved_payment_method
​boolean | null

Enable saved payment method option for payment link

Example: true
Default: false
hide_card_nickname_field
​boolean | null

Hide card nickname field option for payment link

Example: true
Default: false
show_card_form_by_default
​boolean | null

Show card form by default for payment link

Example: true
Default: true
​array | null

Dynamic details related to merchant to be rendered in payment link

​object
details_layout
​string · enum
Enum values:
layout1
layout2
payment_button_text
​string | null

Text for payment link's handle confirm button

custom_message_for_card_terms
​string | null

Text for customizing message for card terms

​PaymentMethodConfig[]

List of custom T&C messages grouped by payment method

payment_button_colour
​string | null

Custom background colour for payment link's handle confirm button

skip_status_screen
​boolean | null

Skip the status screen after payment completion

payment_button_text_colour
​string | null

Custom text colour for payment link's handle confirm button

background_colour
​string | null

Custom background colour for the payment link

​object | null

SDK configuration rules

​object | null

Payment link configuration rules

enable_button_only_on_form_ready
​boolean | null

Flag to enable the button only when the payment form is ready for submission

payment_form_header_text
​string | null

Optional header for the SDK's payment form

payment_form_label_type
​string · enum
Enum values:
above
floating
never
show_card_terms
​string · enum
Enum values:
always
auto
never
is_setup_mandate_flow
​boolean | null

Boolean to control payment button text for setup mandate calls

color_icon_card_cvc_error
​string | null

Hex color for the CVC icon during error state

PaymentLinkDetailsLayout

string · enum
Enum values:
layout1
layout2

PaymentLinkInitiateRequest

merchant_id
​string · required
payment_id
​string · required

PaymentLinkResponse

link
​string · required

URL for rendering the open payment link

payment_link_id
​string · required

Identifier for the payment link

secure_link
​string | null

URL for rendering the secure payment link

PaymentLinkSdkLabelType

string · enum
Enum values:
above
floating
never

PaymentLinkShowSdkTerms

string · enum
Enum values:
always
auto
never

PaymentLinkStatus

string · enum
Enum values:
active
expired

Status Of the Payment Link

PaymentLinkTransactionDetails

key
​string · maxLength: 255 · required

Key for the transaction details

Example: Policy-Number
value
​string · maxLength: 255 · required

Value for the transaction details

Example: 297472368473924
​object

PaymentListConstraints

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

The identifier for customer

Example: cus_y3oqhf46pyzuxjbcn2giaqnb44
starting_after
​string | null

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

Example: pay_fafa124123
ending_before
​string | null

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

Example: pay_fafa124123
limit
​integer · int32 · min: 0 · max: 100

limit on the number of objects to return

Default: 10
created
​string | null · date-time

The time at which payment is created

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

Time less than the payment created time

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

Time greater than the payment created time

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

Time less than or equals to the payment created time

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

Time greater than or equals to the payment created time

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

PaymentListFilterConstraints

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

The identifier for payment

profile_id
​string | null

The identifier for business profile

customer_id
​string | null

The identifier for customer

limit
​integer · int32 · min: 0

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

offset
​integer | null · int32 · min: 0

The starting point within a list of objects

​object
connector
​array | null

The list of connectors to filter payments list

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

The list of currencies to filter payments list

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

The list of payment status to filter payments list

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

The list of payment methods to filter payments list

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

The list of payment method types to filter payments list

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

The list of authentication types to filter payments list

Enum values:
three_ds
no_three_ds
merchant_connector_id
​array | null

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

​Order
card_network
​array | null

The List of all the card networks to filter payments list

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

The identifier for merchant order reference id

card_discovery
​array | null

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

Enum values:
manual
saved_card
click_to_pay
​object[]

Column predicates. Combined with other fields using AND.

PaymentListResponse

size
​integer · min: 0 · required

The number of payments included in the list

​PaymentsResponse[] · required

PaymentListResponseV2

count
​integer · min: 0 · required

The number of payments included in the list for given constraints

total_count
​integer · int64 · required

The total number of available payments for given constraints

​PaymentsResponse[] · required

The list of payments response objects

PaymentMethod

string · enum
Enum values:
card
card_redirect
pay_later
wallet
bank_redirect
bank_transfer
crypto
bank_debit

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

PaymentMethodBlockingConfig

Configuration for payment method blocking based on card attributes
​object

Card-specific blocking configuration

PaymentMethodCollectLinkRequest

Object for GenericLinkUiConfig
customer_id
​string · required

The unique identifier of the customer.

Example: cus_92dnwed8s32bV9D8Snbiasd8v
logo
​string | null · maxLength: 255

Merchant's display logo

Example: https://hyperswitch.io/favicon.ico
merchant_name
​string | null · maxLength: 255

Custom merchant name for the link

Example: Hyperswitch
theme
​string | null · maxLength: 255

Primary color to be used in the form represented in hex format

Example: #4285F4
pm_collect_link_id
​string | null

The unique identifier for the collect link.

Example: pm_collect_link_2bdacf398vwzq5n422S1
session_expiry
​integer | null · int32 · min: 0

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

Example: 900
return_url
​string | null

Redirect to this URL post completion

Example: https://sandbox.hyperswitch.io/payment_method/collect/pm_collect_link_2bdacf398vwzq5n422S1/status
​array | null

List of payment methods shown on collect UI

Example: [{"payment_method": "bank_transfer", "payment_method_types": ["ach", "bacs"]}]

PaymentMethodCollectLinkResponse

Object for GenericLinkUiConfig
pm_collect_link_id
​string · required

The unique identifier for the collect link.

Example: pm_collect_link_2bdacf398vwzq5n422S1
customer_id
​string · required

The unique identifier of the customer.

Example: cus_92dnwed8s32bV9D8Snbiasd8v
expiry
​string · date-time · required

Time when this link will be expired in ISO8601 format

Example: 2025-01-18T11:04:09.922Z
link
​string · required

URL to the form's link generated for collecting payment method details.

Example: https://sandbox.hyperswitch.io/payment_method/collect/pm_collect_link_2bdacf398vwzq5n422S1
logo
​string | null · maxLength: 255

Merchant's display logo

Example: https://hyperswitch.io/favicon.ico
merchant_name
​string | null · maxLength: 255

Custom merchant name for the link

Example: Hyperswitch
theme
​string | null · maxLength: 255

Primary color to be used in the form represented in hex format

Example: #4285F4
return_url
​string | null

Redirect to this URL post completion

Example: https://sandbox.hyperswitch.io/payment_method/collect/pm_collect_link_2bdacf398vwzq5n422S1/status
​array | null

List of payment methods shown on collect UI

Example: [{"payment_method": "bank_transfer", "payment_method_types": ["ach", "bacs"]}]

PaymentMethodConfig

Custom T&C messages for a specific payment method
payment_method
​PaymentMethod · enum · required

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

Enum values:
card
card_redirect
pay_later
wallet
bank_redirect
bank_transfer
crypto
bank_debit
​CustomTerms[] · required

Payment Method Types

Example: [{"message":{"display_mode":"custom","value":"Sample message"},"payment_method_type":"credit"}]

PaymentMethodCreate

payment_method
​PaymentMethod · enum · required

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

Enum values:
card
card_redirect
pay_later
wallet
bank_redirect
bank_transfer
crypto
bank_debit
payment_method_type
​string · enum

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

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

The name of the bank/ provider issuing the payment method to the end user

Example: Citibank
payment_method_issuer_code
​string · enum
Enum values:
jp_hdfc
jp_icici
jp_googlepay
jp_applepay
jp_phonepay
jp_wechat
jp_sofort
jp_giropay
​object
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.

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

The unique identifier of the customer.

Example: cus_y3oqhf46pyzuxjbcn2giaqnb44
card_network
​string | null

The card network

Example: Visa
​
​
client_secret
​string | null

For Client based calls, SDK will use the client_secret in order to call /payment_methods Client secret will be generated whenever a new payment method is created

​
​object

PaymentMethodCreateData

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · requires: card
type = object · requires: bank_debit
Properties for Variant 1:
​CardDetail · required

PaymentMethodData

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · requires: card
type = object · requires: card_redirect
type = object · requires: wallet
type = object · requires: pay_later
type = object · requires: bank_redirect
type = object · requires: bank_debit
type = object · requires: bank_transfer
type = object · requires: real_time_payment
type = object · requires: crypto
type = string
type = string
type = object · requires: upi
type = object · requires: voucher
type = object · requires: gift_card
type = object · requires: card_token
type = object · requires: open_banking
type = object · requires: mobile_payment
type = object · requires: network_token
Properties for Card:
​Card · required

PaymentMethodDataRequest

The payment method information provided for making a payment
​object
oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · requires: card
type = object · requires: card_redirect
type = object · requires: wallet
type = object · requires: pay_later
type = object · requires: bank_redirect
type = object · requires: bank_debit
type = object · requires: bank_transfer
type = object · requires: real_time_payment
type = object · requires: crypto
type = string
type = string
type = object · requires: upi
type = object · requires: voucher
type = object · requires: gift_card
type = object · requires: card_token
type = object · requires: open_banking
type = object · requires: mobile_payment
type = object · requires: network_token
Properties for Card:
​Card · required

PaymentMethodDataResponse

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · requires: card
type = object · requires: bank_transfer
type = object · requires: wallet
type = object · requires: pay_later
type = object · requires: bank_redirect
type = object · requires: crypto
type = object · requires: bank_debit
type = object · requires: mandate_payment
type = object · requires: reward
type = object · requires: real_time_payment
type = object · requires: upi
type = object · requires: voucher
type = object · requires: gift_card
type = object · requires: card_redirect
type = object · requires: card_token
type = object · requires: open_banking
type = object · requires: mobile_payment
type = object · requires: network_token
Properties for Variant 1:
​CardResponse · required

PaymentMethodDataResponseWithBilling

​object
oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · requires: card
type = object · requires: bank_transfer
type = object · requires: wallet
type = object · requires: pay_later
type = object · requires: bank_redirect
type = object · requires: crypto
type = object · requires: bank_debit
type = object · requires: mandate_payment
type = object · requires: reward
type = object · requires: real_time_payment
type = object · requires: upi
type = object · requires: voucher
type = object · requires: gift_card
type = object · requires: card_redirect
type = object · requires: card_token
type = object · requires: open_banking
type = object · requires: mobile_payment
type = object · requires: network_token
Properties for Variant 1:
​CardResponse · required

PaymentMethodDataWalletInfo

last4
​string · required

Last 4 digits of the card number

card_network
​string · required

The information of the payment method

type
​string | null

The type of payment method

card_exp_month
​string | null

The card's expiry month

Example: 10
card_exp_year
​string | null

The card's expiry year

Example: 25
auth_code
​string | null

Unique authorisation code for the payment

Example: 003225

PaymentMethodDeleteResponse

payment_method_id
​string · required

The unique identifier of the Payment method

Example: card_rGK4Vi5iSW70MY7J2mIg
deleted
​boolean · required

Whether payment method was deleted or not

Example: true

PaymentMethodIssuerCode

string · enum
Enum values:
jp_hdfc
jp_icici
jp_googlepay
jp_applepay
jp_phonepay
jp_wechat
jp_sofort
jp_giropay

PaymentMethodListInstallmentAmountDetails

Amount breakdown for a single installment plan
amount_per_installment
​number · double · required

Amount charged per installment in major units

total_amount
​number · double · required

Total amount across all installments in major units (may differ slightly from order amount due to ceiling)

PaymentMethodListInstallmentOption

Installment options for a payment method, as returned in the payment method list response
payment_method
​PaymentMethod · enum · required

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

Enum values:
card
card_redirect
pay_later
wallet
bank_redirect
bank_transfer
crypto
bank_debit
​PaymentMethodListInstallmentPlan[] · required

Individual installment plans with computed amounts

PaymentMethodListInstallmentPlan

A single installment plan with pre-computed amount breakdown
number_of_installments
​integer · int32 · min: 0 · required

Number of installments for this plan

billing_frequency
​BillingFrequency · enum · required

Billing frequency for a card installment plan

Enum values:
month
interest_rate
​number · double · required

Interest rate as a percentage

​PaymentMethodListInstallmentAmountDetails · required

Amount breakdown for a single installment plan

PaymentMethodListIntentData

Intent-only payment details returned as part of the Payment Method List response
payment_id
​string · required

Unique identifier for the payment

status
​IntentStatus · enum · required

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

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

This Unit struct represents MinorUnit in which core amount works

attempt_count
​integer · int32 · required

Number of payment attempts made

currency
​string · enum

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

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

Client secret for client-side payment confirmation

description
​string | null

A description for the payment

customer_id
​string | null

The customer identifier

return_url
​string | null

The URL to redirect to after payment completion

setup_future_usage
​string · enum

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

  • off_session: The payment method can be used for future payments when the customer is not present.
  • on_session: The payment method is intended for use only when the customer is present during checkout. If omitted, defaults to on_session.
Enum values:
off_session
on_session
​object
​object
metadata
​object | null

Additional metadata

order_details
​array | null

Order details for the payment

created
​string | null · date-time

Timestamp when the payment was created

expires_on
​string | null · date-time

Timestamp when the client secret expires

profile_id
​string | null

The profile identifier

merchant_order_reference_id
​string | null

Merchant-provided reference identifier

​array | null

Installment options available for this payment

PaymentMethodListResponse

currency
​Currency · enum · required

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

Enum values:
AED
AFN
ALL
AMD
ANG
AOA
ARS
AUD
​ResponsePaymentMethodsEnabled[] · required

Information about the payment method

​MandateType · required
show_surcharge_breakup_screen
​boolean · required

flag to indicate if surcharge and tax breakup screen should be shown or not

request_external_three_ds_authentication
​boolean · required

flag to indicate whether to perform external 3ds authentication

Example: true
is_tax_calculation_enabled
​boolean · required

flag that indicates whether to calculate tax on the order amount

​SdkNextAction · required
is_guest_customer
​boolean · required

indicates whether this is a guest customer flow

redirect_url
​string | null

Redirect URL of the merchant

Example: https://www.google.com
merchant_name
​string | null
payment_type
​string · enum

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

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

flag that indicates whether to collect shipping details from wallets or from the customer

collect_billing_details_from_wallets
​boolean | null

flag that indicates whether to collect billing details from wallets or from the customer

​object

Intent-only payment details returned as part of the Payment Method List response

show_logo
​boolean | null

Whether to show logo

logo_url
​string | null

The logo URL

PaymentMethodMetaData

Represents metadata about the payment method used in the 3DS decision rule.
card_network
​CardNetwork · enum · required

Indicates the card network.

Enum values:
Visa
Mastercard
AmericanExpress
JCB
DinersClub
Discover
CartesBancaires
UnionPay

PaymentMethodResponse

merchant_id
​string · required

Unique identifier for a merchant

Example: merchant_1671528864
payment_method_id
​string · required

The unique identifier of the Payment method

Example: card_rGK4Vi5iSW70MY7J2mIg
payment_method
​PaymentMethod · enum · required

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

Enum values:
card
card_redirect
pay_later
wallet
bank_redirect
bank_transfer
crypto
bank_debit
customer_id
​string | null · minLength: 1 · maxLength: 64

The unique identifier of the customer.

Example: cus_y3oqhf46pyzuxjbcn2giaqnb44
payment_method_type
​string · enum

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

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

Indicates whether the payment method supports recurring payments. Optional.

Example: true
installment_payment_enabled
​boolean | null

Indicates whether the payment method is eligible for installment payments (e.g., EMI, BNPL). Optional.

Example: true
payment_experience
​array | null

Type of payment experience enabled with the connector

Enum values:
redirect_to_url
invoke_sdk_client
display_qr_code
one_click
link_wallet
invoke_payment_app
display_wait_screen
collect_otp
Example: ["redirect_to_url"]
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.

created
​string | null · date-time

A timestamp (ISO 8601 code) that determines when the payment method was created

Example: 2023-01-18T11:04:09.922Z
​
last_used_at
​string | null · date-time
client_secret
​string | null

For Client based calls

PaymentMethodSpecificFeatures

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · requires: three_ds, no_three_ds, supported_card_networks
Properties for Variant 1:
three_ds
​FeatureStatus · enum · required

The status of the feature

Enum values:
not_supported
supported
no_three_ds
​FeatureStatus · enum · required

The status of the feature

Enum values:
not_supported
supported
supported_card_networks
​CardNetwork[] · required

List of supported card networks

Enum values:
Visa
Mastercard
AmericanExpress
JCB
DinersClub
Discover
CartesBancaires
UnionPay

PaymentMethodStatus

string · enum
Enum values:
active
inactive
processing
awaiting_data
new

Payment Method Status

PaymentMethodTokenizationDetails

payment_method_id
​string · required

The unique identifier for the payment method

psp_tokenization
​boolean · required

This indicates whether there is at least one active PSP token available

network_tokenization
​boolean · required

This indicates whether a payment method is tokenized with card network

is_eligible_for_mit_payment
​boolean · required

This indicates whether a payment method is eligible for performing a mit transaction

payment_method_status
​string · enum

Payment Method Status

Enum values:
active
inactive
processing
awaiting_data
new
network_transaction_id
​string | null

This is the transaction id generated by the network

PaymentMethodType

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

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

PaymentMethodUpdate

​object
​object
client_secret
​string | null · minLength: 30 · maxLength: 30

This is a 15 minute expiry token which shall be used from the client to authenticate and perform sessions from the SDK

Example: secret_k2uj3he2893eiu2d

PaymentMethodsConfig

List of custom T&C messages grouped by payment method

Custom T&C messages for a specific payment method
payment_method
​PaymentMethod · enum · required

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

Enum values:
card
card_redirect
pay_later
wallet
bank_redirect
bank_transfer
crypto
bank_debit
​CustomTerms[] · required

Payment Method Types

Example: [{"message":{"display_mode":"custom","value":"Sample message"},"payment_method_type":"credit"}]

PaymentMethodsEnabled

Details of all the payment methods enabled for the connector for the given merchant account
payment_method
​PaymentMethod · enum · required

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

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

Subtype of payment method

Example: ["credit"]

PaymentProcessingDetails

payment_processing_certificate
​string · required
payment_processing_certificate_key
​string · required

PaymentProcessingDetailsAt

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · payment_processing_details_at="Hyperswitch" · requires: payment_processing_certificate, payment_processing_certificate_key
type = object · payment_processing_details_at="Connector"
Properties for Variant 1:
payment_processing_certificate
​string · required
payment_processing_certificate_key
​string · required
payment_processing_details_at
​string · enum · required
Enum values:
Hyperswitch

PaymentResponseData

payment_id
​PaymentId · required

A type for payment_id that can be used for payment ids

status
​IntentStatus · enum · required

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

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

This Unit struct represents MinorUnit in which core amount works

currency
​Currency · enum · required

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

Enum values:
AED
AFN
ALL
AMD
ANG
AOA
ARS
AUD
profile_id
​string

A type for profile_id that can be used for business profile ids

connector
​string | null
payment_method_id
​string | null

Identifier for Payment Method

Example: pm_01926c58bc6e77c09e809964e72af8c8
return_url
​string | null

The url to which user must be redirected to after completion of the purchase

​
payment_experience
​string · enum

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

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

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

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

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

​object
​object
payment_type
​string · enum

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

Enum values:
normal
new_mandate
setup_mandate
recurring_mandate
installment
payment_token
​string | null

PaymentRetrieveBody

merchant_id
​string | null

The identifier for the Merchant Account.

force_sync
​boolean | null

Decider to enable or disable the connector call for retrieve request

client_secret
​string | null

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

expand_captures
​boolean | null

If enabled provides list of captures linked to latest attempt

expand_attempts
​boolean | null

If enabled provides list of attempts linked to payment intent

all_keys_required
​boolean | null

If enabled, provides whole connector response

expand_customer_statistics
​boolean | null

When true, includes customer statistics (OLAP) in the retrieve response.

PaymentTableField

string · enum
Enum values:
payment_id
status
amount
currency
customer_id
description
created
modified_at

Payment intent and active-attempt columns shown on the payments table.

PaymentType

string · enum
Enum values:
normal
new_mandate
setup_mandate
recurring_mandate
installment

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

PaymentsCancelPostCaptureRequest

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

The reason for the payment cancel

PaymentsCancelRequest

cancellation_reason
​string | null

The reason for the payment cancel

​object

Merchant connector details used to make payments.

all_keys_required
​boolean | null

If enabled, provides whole connector response

PaymentsCaptureRequest

merchant_id
​string | null

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

amount_to_capture
​integer | null · int64

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

Example: 6540
refund_uncaptured_amount
​boolean | null

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

statement_descriptor_suffix
​string | null

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

statement_descriptor_prefix
​string | null

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

​object

Merchant connector details used to make payments.

all_keys_required
​boolean | null

If true, returns stringified connector raw response body

PaymentsCompleteAuthorizeRequest

​object
client_secret
​string | null

Client Secret

threeds_method_comp_ind
​string · enum

Indicates if 3DS method data was successfully completed or not

Enum values:
Y
N
U

PaymentsConfirmRequest

amount
​integer | null · int64 · min: 0

The primary amount for the payment, provided in the lowest denomination of the specified currency (e.g., 6540 for $65.40 USD). This field is mandatory for creating a payment.

Example: 6540
order_tax_amount
​integer | null · int64

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

Example: 6540
currency
​string · enum

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

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

The amount to be captured from the user's payment method, in the lowest denomination. If not provided, and capture_method is automatic, the full payment amount will be captured. If capture_method is manual, this can be specified in the /capture call. Must be less than or equal to the authorized amount.

Example: 6540
shipping_cost
​integer | null · int64

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

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

Optional. A merchant-provided unique identifier for the payment, contains 30 characters long (e.g., "pay_mbabizu24mvu3mela5njyhpit4"). If provided, it ensures idempotency for the payment creation request. If omitted, Hyperswitch generates a unique ID for the payment.

Example: pay_mbabizu24mvu3mela5njyhpit4
​
connector
​array | null

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

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

Specifies how the payment is captured.

  • automatic: Funds are captured immediately after successful authorization. This is the default behavior if the field is omitted.
  • manual: Funds are authorized but not captured. A separate request to the /payments/{payment_id}/capture endpoint is required to capture the funds.
Enum values:
automatic
manual
manual_multiple
scheduled
sequential_automatic
authentication_type
​string · enum

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

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

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

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

If set to true, Hyperswitch attempts to confirm and authorize the payment immediately after creation, provided sufficient payment method details are included. If false or omitted (default is false), the payment is created with a status such as requires_payment_method or requires_confirmation, and a separate POST /payments/{payment_id}/confirm call is necessary to proceed with authorization.

Example: true
Default: false
​object

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

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

The identifier for the customer

Example: cus_y3oqhf46pyzuxjbcn2giaqnb44
​object

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

off_session
​boolean | null

Set to true to indicate that the customer is not in your checkout flow during this payment, and therefore is unable to authenticate. This parameter is intended for scenarios where you collect card details and charge them later. When making a recurring payment by passing a mandate_id, this parameter is mandatory

Example: true
description
​string | null

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

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

The URL to redirect the customer to after they complete the payment process or authentication. This is crucial for flows that involve off-site redirection (e.g., 3DS, some bank redirects, wallet payments).

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

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

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

The payment method information provided for making a payment

payment_method
​string · enum

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

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

As Hyperswitch tokenises the sensitive details about the payments method, it provides the payment_token as a reference to a stored payment method, ensuring that the sensitive details are not exposed in any manner.

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

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

Example: [{ "product_name": "Apple iPhone 16", "quantity": 1, "amount" : 69000 "product_img_link" : "https://dummy-img-link.com" }]
client_secret
​string | null

It's a token used for client side verification.

Example: pay_U42c409qyHwOkWo3vK60_secret_el9ksDkiB8hi6j9N78yo
​object

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

​object

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

mandate_id
​string | null · maxLength: 64

A unique identifier to link the payment to a mandate. To do Recurring payments after a mandate has been created, pass the mandate_id instead of payment_method_data

Example: mandate_iwer89rnjef349dni3
​object

Browser information to be used for 3DS 2.0

payment_experience
​string · enum

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

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

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

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

Merchant connector details used to make payments.

allowed_payment_method_types
​array | null

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

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

Denotes the retry action

Enum values:
manual_retry
requeue
metadata
​object | null

You can specify up to 50 keys, with key names up to 40 characters long and values up to 500 characters long. Metadata is useful for storing additional, structured information on an object.

​object

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

payment_link
​boolean | null

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

Example: true
Default: false
​object

Configure a custom payment link for the particular payment

payment_link_config_id
​string | null

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

payment_type
​string · enum

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

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

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

session_expiry
​integer | null · int32 · min: 0

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

Example: 900
frm_metadata
​object | null

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

request_external_three_ds_authentication
​boolean | null

Whether to perform external authentication (if applicable)

Example: true
​object

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

​

Details required for recurring payment

​

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

request_extended_authorization
​boolean | null

Optional boolean value to extent authorization period of this payment

capture method must be manual or manual_multiple

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

Your unique identifier for this payment or order. This ID helps you reconcile payments on your system. If provided, it is passed to the connector if supported.

Example: Custom_Order_id_123
skip_external_tax_calculation
​boolean | null

Whether to calculate tax for this payment intent

psd2_sca_exemption_type
​string · enum

SCA Exemptions types available for authentication

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

Indicates if 3ds challenge is forced

threeds_method_comp_ind
​string · enum

Indicates if 3DS method data was successfully completed or not

Enum values:
Y
N
U
is_iframe_redirection_enabled
​boolean | null

Indicates if the redirection has to open in the iframe

all_keys_required
​boolean | null

If enabled, provides whole connector response

​

Describes the channel through which the payment was initiated.

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

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

Example: 6540
shipping_amount_tax
​integer · int64

This Unit struct represents MinorUnit in which core amount works

duty_amount
​integer · int64

This Unit struct represents MinorUnit in which core amount works

order_date
​string | null · date-time

Date the payer placed the order.

enable_partial_authorization
​boolean | null

Allow partial authorization for this payment

Default: false
is_stored_credential
​boolean | null

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

Example: true
mit_category
​string · enum

Specifies the category of a Merchant Initiated Transaction (MIT). In the case of MIT, mit_category tells what kind of MIT is being processed. In the case of CIT, it tells the future intended MIT type.

Enum values:
installment
unscheduled
recurring
resubmission
​object

Billing Descriptor information to be sent to the payment gateway

tokenization
​string · enum

The type of tokenization to use for the payment method

Enum values:
skip_psp
tokenize_at_psp
​object

Information identifying partner and merchant application initiating the request

​array | null

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

​object

Installment selection sent by the customer during payment confirmation.

PaymentsCreateRequest

amount
​integer · int64 · min: 0 · required

The primary amount for the payment, provided in the lowest denomination of the specified currency (e.g., 6540 for $65.40 USD). This field is mandatory for creating a payment.

currency
​Currency · enum · required

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

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

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

Example: 6540
amount_to_capture
​integer | null · int64

The amount to be captured from the user's payment method, in the lowest denomination. If not provided, and capture_method is automatic, the full payment amount will be captured. If capture_method is manual, this can be specified in the /capture call. Must be less than or equal to the authorized amount.

Example: 6540
shipping_cost
​integer | null · int64

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

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

Optional. A merchant-provided unique identifier for the payment, contains 30 characters long (e.g., "pay_mbabizu24mvu3mela5njyhpit4"). If provided, it ensures idempotency for the payment creation request. If omitted, Hyperswitch generates a unique ID for the payment.

Example: pay_mbabizu24mvu3mela5njyhpit4
​
connector
​array | null

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

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

Specifies how the payment is captured.

  • automatic: Funds are captured immediately after successful authorization. This is the default behavior if the field is omitted.
  • manual: Funds are authorized but not captured. A separate request to the /payments/{payment_id}/capture endpoint is required to capture the funds.
Enum values:
automatic
manual
manual_multiple
scheduled
sequential_automatic
authentication_type
​string · enum

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

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

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

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

If set to true, Hyperswitch attempts to confirm and authorize the payment immediately after creation, provided sufficient payment method details are included. If false or omitted (default is false), the payment is created with a status such as requires_payment_method or requires_confirmation, and a separate POST /payments/{payment_id}/confirm call is necessary to proceed with authorization.

Example: true
Default: false
​object

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

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

The identifier for the customer

Example: cus_y3oqhf46pyzuxjbcn2giaqnb44
​object

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

off_session
​boolean | null

Set to true to indicate that the customer is not in your checkout flow during this payment, and therefore is unable to authenticate. This parameter is intended for scenarios where you collect card details and charge them later. When making a recurring payment by passing a mandate_id, this parameter is mandatory

Example: true
description
​string | null

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

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

The URL to redirect the customer to after they complete the payment process or authentication. This is crucial for flows that involve off-site redirection (e.g., 3DS, some bank redirects, wallet payments).

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

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

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

The payment method information provided for making a payment

payment_method
​string · enum

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

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

As Hyperswitch tokenises the sensitive details about the payments method, it provides the payment_token as a reference to a stored payment method, ensuring that the sensitive details are not exposed in any manner.

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

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

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

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

​object

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

mandate_id
​string | null · maxLength: 64

A unique identifier to link the payment to a mandate. To do Recurring payments after a mandate has been created, pass the mandate_id instead of payment_method_data

Example: mandate_iwer89rnjef349dni3
​object

Browser information to be used for 3DS 2.0

payment_experience
​string · enum

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

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

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

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

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

Example: food
​object

Merchant connector details used to make payments.

allowed_payment_method_types
​array | null

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

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

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

​object

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

payment_link
​boolean | null

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

Example: true
Default: false
​object

Configure a custom payment link for the particular payment

payment_link_config_id
​string | null

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

profile_id
​string | null

The business profile to be used for this payment, if not passed the default business profile associated with the merchant account will be used. It is mandatory in case multiple business profiles have been set up.

​object

Details of surcharge applied on this payment, if applicable

payment_type
​string · enum

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

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

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

session_expiry
​integer | null · int32 · min: 0

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

Example: 900
frm_metadata
​object | null

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

request_external_three_ds_authentication
​boolean | null

Whether to perform external authentication (if applicable)

Example: true
​object

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

​

Details required for recurring payment

​

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

request_extended_authorization
​boolean | null

Optional boolean value to extent authorization period of this payment

capture method must be manual or manual_multiple

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

Your unique identifier for this payment or order. This ID helps you reconcile payments on your system. If provided, it is passed to the connector if supported.

Example: Custom_Order_id_123
skip_external_tax_calculation
​boolean | null

Whether to calculate tax for this payment intent

psd2_sca_exemption_type
​string · enum

SCA Exemptions types available for authentication

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

Indicates if 3ds challenge is forced

threeds_method_comp_ind
​string · enum

Indicates if 3DS method data was successfully completed or not

Enum values:
Y
N
U
is_iframe_redirection_enabled
​boolean | null

Indicates if the redirection has to open in the iframe

all_keys_required
​boolean | null

If enabled, provides whole connector response

​

Describes the channel through which the payment was initiated.

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

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

Example: 6540
shipping_amount_tax
​integer · int64

This Unit struct represents MinorUnit in which core amount works

duty_amount
​integer · int64

This Unit struct represents MinorUnit in which core amount works

order_date
​string | null · date-time

Date the payer placed the order.

enable_partial_authorization
​boolean | null

Allow partial authorization for this payment

Default: false
enable_overcapture
​boolean | null

Boolean indicating whether to enable overcapture for this payment

Example: true
is_stored_credential
​boolean | null

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

Example: true
mit_category
​string · enum

Specifies the category of a Merchant Initiated Transaction (MIT). In the case of MIT, mit_category tells what kind of MIT is being processed. In the case of CIT, it tells the future intended MIT type.

Enum values:
installment
unscheduled
recurring
resubmission
​object

Billing Descriptor information to be sent to the payment gateway

tokenization
​string · enum

The type of tokenization to use for the payment method

Enum values:
skip_psp
tokenize_at_psp
​object

Information identifying partner and merchant application initiating the request

​array | null

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

​object

Installment selection sent by the customer during payment confirmation.

PaymentsCreateResponseOpenApi

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

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

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

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

Example: merchant_1668273825
status
​string · enum · required

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

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

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

Example: 6540
net_amount
​integer · int64 · required

The payment net amount. net_amount = amount + surcharge_details.surcharge_amount + surcharge_details.tax_amount + shipping_cost + order_tax_amount, If no surcharge_details, shipping_cost, order_tax_amount, net_amount = amount

Example: 6540
amount_capturable
​integer · int64 · min: 100 · required

The amount (in minor units) that can still be captured for this payment. This is relevant when capture_method is manual. Once fully captured, or if capture_method is automatic and payment succeeded, this will be 0.

Example: 6540
processor_merchant_id
​string · maxLength: 255 · required

The identifier for the processor merchant account. In platform-connected setups, this is the connected merchant ID. For standard merchants, this is same as merchant_id.

Example: merchant_1689512302
currency
​Currency · enum · required

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

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

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

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

Total number of attempts associated with this payment

shipping_cost
​integer | null · int64

The shipping cost for the payment.

Example: 6540
amount_received
​integer | null · int64

The total amount (in minor units) that has been captured for this payment. For fauxpay sandbox connector, this might reflect the authorized amount if status is succeeded even if capture_method was manual.

Example: 6540
initiator
​string · enum

Represents the initiator context in platform-connected setups Used in payment/refund/dispute responses to indicate who initiated the operation None indicates a standard merchant flow / JWT flow / Admin flow or insufficient information

Enum values:
platform
connected
sdk_authorization
​string | null

Token containing encoded information for sdk authorization.

Example: cHJvZmlsZV9pZD1wcm9mXzEyMyxwdWJsaXNoYWJsZV9rZXk9cGtfbGl2ZV8xMjM=
connector
​string | null

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

Example: stripe
​object

Additional metadata for payment intent state containing refunded and disputed amounts

client_secret
​string | null

A secret token unique to this payment intent. It is primarily used by client-side applications (e.g., Hyperswitch SDKs) to authenticate actions like confirming the payment or handling next actions. This secret should be handled carefully and not exposed publicly beyond its intended client-side use.

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

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

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

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

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

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

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

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

​array | null

List of disputes that happened on this intent

​array | null

List of attempts that happened on this intent

​array | null

List of captures done on latest attempt

mandate_id
​string | null · maxLength: 255

A unique identifier to link the payment to a mandate, can be used instead of payment_method_data, in case of setting up recurring payments

Example: mandate_iwer89rnjef349dni3
​object

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

setup_future_usage
​string · enum

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

  • off_session: The payment method can be used for future payments when the customer is not present.
  • on_session: The payment method is intended for use only when the customer is present during checkout. If omitted, defaults to on_session.
Enum values:
off_session
on_session
off_session
​boolean | null

Set to true to indicate that the customer is not in your checkout flow during this payment, and therefore is unable to authenticate. This parameter is intended for scenarios where you collect card details and charge them later. This parameter can only be used with confirm=true.

Example: true
capture_method
​string · enum

Specifies how the payment is captured.

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

Provide a reference to a stored payment method

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

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

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

The URL to redirect after the completion of the operation

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

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

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

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

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

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

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

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

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

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

error_code
​string | null

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

Example: E0001
error_message
​string | null

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

Example: Failed while verifying the card
​object

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

payment_experience
​string · enum

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

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

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

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

A label identifying the specific merchant connector account (MCA) used for this payment. This often combines the connector name, business country, and a custom label (e.g., "stripe_US_primary").

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

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

business_sub_label
​string | null

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

allowed_payment_method_types
​array | null

Allowed Payment Method Types for a given PaymentIntent

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

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

connector_transaction_id
​string | null

A unique identifier for a payment provided by the connector

Example: 993672945374576J
​object

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

metadata
​object | null

You can specify up to 50 keys, with key names up to 40 characters long and values up to 500 characters long. Metadata is useful for storing additional, structured information on an object.

​object

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

​
​object

additional data that might be required by hyperswitch

reference_id
​string | null

reference(Identifier) to the payment at connector side

Example: 993672945374576J
​object
profile_id
​string | null

The business profile that is associated with this payment

​object

Details of surcharge applied on this payment, if applicable

merchant_decision
​string | null

Denotes the action(approve or reject) taken by merchant in case of manual review. Manual review can occur when the transaction is marked as risky by the frm_processor, payment processor or when there is underpayment/over payment incase of crypto payment

merchant_connector_id
​string | null

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

incremental_authorization_allowed
​boolean | null

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

authorization_count
​integer | null · int32

Total number of authorizations happened in an incremental_authorization payment

​array | null

List of incremental authorizations happened to the payment

​object

Details of external authentication

external_3ds_authentication_attempted
​boolean | null

Flag indicating if external 3ds authentication is made or not

expires_on
​string | null · date-time

Date Time for expiry of the payment

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

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

​object

Browser information to be used for 3DS 2.0

​

Describes the channel through which the payment was initiated.

payment_method_id
​string | null

A unique identifier for the payment method used in this payment. If the payment method was saved or tokenized, this ID can be used to reference it for future transactions or recurring payments. Refer payment_method_tokenization_details for detailed view of payment method tokenization

network_transaction_id
​string | null

The network transaction ID is a unique identifier for the transaction as recognized by the payment network (e.g., Visa, Mastercard), this ID can be used to reference it for future transactions or recurring payments. Refer payment_method_tokenization_details for detailed view of payment method tokenization

payment_method_status
​string · enum

Payment Method Status

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

Date time at which payment was updated

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

Charge Information

frm_metadata
​object | null

You can specify up to 50 keys, with key names up to 40 characters long and values up to 500 characters long. FRM Metadata is useful for storing additional, structured information on an object related to FRM.

extended_authorization_applied
​boolean | null

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

extended_authorization_last_applied_at
​string | null · date-time

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

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

Optional boolean value to extent authorization period of this payment

capture method must be manual or manual_multiple

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

date and time after which this payment cannot be captured

merchant_order_reference_id
​string | null · maxLength: 255

Merchant's identifier for the payment/invoice. This will be sent to the connector if the connector provides support to accept multiple reference ids. In case the connector supports only one reference id, Hyperswitch's Payment ID will be sent as reference.

Example: Custom_Order_id_123
order_tax_amount
​integer · int64

This Unit struct represents MinorUnit in which core amount works

connector_mandate_id
​string | null

Connector Identifier for the payment method

card_discovery
​string · enum

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

Enum values:
manual
saved_card
click_to_pay
force_3ds_challenge
​boolean | null

Indicates if 3ds challenge is forced

force_3ds_challenge_trigger
​boolean | null

Indicates if 3ds challenge is triggered

issuer_error_code
​string | null

Error code received from the issuer in case of failed payments

issuer_error_message
​string | null

Error message received from the issuer in case of failed payments

is_iframe_redirection_enabled
​boolean | null

Indicates if the redirection has to open in the iframe

whole_connector_response
​string | null

Contains whole connector response

enable_partial_authorization
​boolean | null

Allow partial authorization for this payment

Default: false
enable_overcapture
​boolean | null

Bool indicating if overcapture must be requested for this payment

is_overcapture_enabled
​boolean | null

Boolean indicating whether overcapture is effectively enabled for this payment

​object
is_stored_credential
​boolean | null

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

Example: true
mit_category
​string · enum

Specifies the category of a Merchant Initiated Transaction (MIT). In the case of MIT, mit_category tells what kind of MIT is being processed. In the case of CIT, it tells the future intended MIT type.

Enum values:
installment
unscheduled
recurring
resubmission
​object

Billing Descriptor information to be sent to the payment gateway

tokenization
​string · enum

The type of tokenization to use for the payment method

Enum values:
skip_psp
tokenize_at_psp
​object

Information identifying partner and merchant application initiating the request

​object
​array | null

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

​object

Installment selection made by the customer during payment confirmation.

​object

Statistics for a customer within a single profile

​object

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

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

PaymentsDynamicTaxCalculationRequest

​Address · required
payment_method_type
​PaymentMethodType · enum · required

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

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

Client Secret

session_id
​string | null

Session Id

PaymentsDynamicTaxCalculationResponse

payment_id
​string · required

The identifier for the payment

net_amount
​MinorUnit · int64 · required

This Unit struct represents MinorUnit in which core amount works

​DisplayAmountOnSdk · required
order_tax_amount
​integer · int64

This Unit struct represents MinorUnit in which core amount works

shipping_cost
​integer · int64

This Unit struct represents MinorUnit in which core amount works

PaymentsEligibilityRequest

client_secret
​string · required

Token used for client side verification

Example: pay_U42c409qyHwOkWo3vK60_secret_el9ksDkiB8hi6j9N78yo
payment_method_type
​PaymentMethod · enum · required

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

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

Payment method data request for eligibility check

payment_method_subtype
​string · enum

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

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

Browser information to be used for 3DS 2.0

PaymentsEligibilityResponse

payment_id
​string · required

The identifier for the payment

​SdkNextAction · required

PaymentsExternalAuthenticationRequest

device_channel
​DeviceChannel · enum · required

Device Channel indicating whether request is coming from App or Browser

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

Indicates if 3DS method data was successfully completed or not

Enum values:
Y
N
U
client_secret
​string | null

Client Secret

​object

SDK Information if request is from SDK

PaymentsExternalAuthenticationResponse

trans_status
​TransactionStatus · enum · required

Indicates the transaction status

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

Three DS Requestor URL

acs_url
​string | null

Access Server URL to be used for challenge submission

challenge_request
​string | null

Challenge request which should be sent to acs_url

challenge_request_key
​string | null

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

acs_reference_number
​string | null

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

acs_trans_id
​string | null

Unique identifier assigned by the ACS to identify a single transaction

three_dsserver_trans_id
​string | null

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

acs_signed_content
​string | null

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

three_ds_requestor_app_url
​string | null

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

error_message
​string | null

Error message if any

PaymentsIncrementalAuthorizationRequest

amount
​integer · int64 · required

The total amount including previously authorized amount and additional amount

Example: 6540
reason
​string | null

Reason for incremental authorization

PaymentsPostSessionTokensRequest

payment_method_type
​PaymentMethodType · enum · required

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

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

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

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

It's a token used for client side verification.

PaymentsPostSessionTokensResponse

payment_id
​string · required

The identifier for the payment

status
​string · enum · required

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

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

PaymentsRequest

amount
​integer | null · int64 · min: 0

The primary amount for the payment, provided in the lowest denomination of the specified currency (e.g., 6540 for $65.40 USD). This field is mandatory for creating a payment.

Example: 6540
order_tax_amount
​integer | null · int64

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

Example: 6540
currency
​string · enum

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

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

The amount to be captured from the user's payment method, in the lowest denomination. If not provided, and capture_method is automatic, the full payment amount will be captured. If capture_method is manual, this can be specified in the /capture call. Must be less than or equal to the authorized amount.

Example: 6540
shipping_cost
​integer | null · int64

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

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

Optional. A merchant-provided unique identifier for the payment, contains 30 characters long (e.g., "pay_mbabizu24mvu3mela5njyhpit4"). If provided, it ensures idempotency for the payment creation request. If omitted, Hyperswitch generates a unique ID for the payment.

Example: pay_mbabizu24mvu3mela5njyhpit4
merchant_id
​string | null · maxLength: 255

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

Example: merchant_1668273825
​
connector
​array | null

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

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

Specifies how the payment is captured.

  • automatic: Funds are captured immediately after successful authorization. This is the default behavior if the field is omitted.
  • manual: Funds are authorized but not captured. A separate request to the /payments/{payment_id}/capture endpoint is required to capture the funds.
Enum values:
automatic
manual
manual_multiple
scheduled
sequential_automatic
authentication_type
​string · enum

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

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

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

Enum values:
three_ds
no_three_ds
Default: three_ds
​object
capture_on
​string | null · date-time

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

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

If set to true, Hyperswitch attempts to confirm and authorize the payment immediately after creation, provided sufficient payment method details are included. If false or omitted (default is false), the payment is created with a status such as requires_payment_method or requires_confirmation, and a separate POST /payments/{payment_id}/confirm call is necessary to proceed with authorization.

Example: true
Default: false
​object

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

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

The identifier for the customer

Example: cus_y3oqhf46pyzuxjbcn2giaqnb44
​object

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

off_session
​boolean | null

Set to true to indicate that the customer is not in your checkout flow during this payment, and therefore is unable to authenticate. This parameter is intended for scenarios where you collect card details and charge them later. When making a recurring payment by passing a mandate_id, this parameter is mandatory

Example: true
description
​string | null

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

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

The URL to redirect the customer to after they complete the payment process or authentication. This is crucial for flows that involve off-site redirection (e.g., 3DS, some bank redirects, wallet payments).

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

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

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

The payment method information provided for making a payment

payment_method
​string · enum

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

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

As Hyperswitch tokenises the sensitive details about the payments method, it provides the payment_token as a reference to a stored payment method, ensuring that the sensitive details are not exposed in any manner.

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

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

Example: [{ "product_name": "Apple iPhone 16", "quantity": 1, "amount" : 69000 "product_img_link" : "https://dummy-img-link.com" }]
client_secret
​string | null

It's a token used for client side verification.

Example: pay_U42c409qyHwOkWo3vK60_secret_el9ksDkiB8hi6j9N78yo
​object

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

​object

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

mandate_id
​string | null · maxLength: 64

A unique identifier to link the payment to a mandate. To do Recurring payments after a mandate has been created, pass the mandate_id instead of payment_method_data

Example: mandate_iwer89rnjef349dni3
​object

Browser information to be used for 3DS 2.0

payment_experience
​string · enum

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

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

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

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

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

Example: food
​object

Merchant connector details used to make payments.

allowed_payment_method_types
​array | null

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

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

Business sub label for the payment

retry_action
​string · enum

Denotes the retry action

Enum values:
manual_retry
requeue
metadata
​object | null

You can specify up to 50 keys, with key names up to 40 characters long and values up to 500 characters long. Metadata is useful for storing additional, structured information on an object.

​object

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

​object

additional data that might be required by hyperswitch

payment_link
​boolean | null

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

Example: true
Default: false
​object

Configure a custom payment link for the particular payment

payment_link_config_id
​string | null

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

profile_id
​string | null

The business profile to be used for this payment, if not passed the default business profile associated with the merchant account will be used. It is mandatory in case multiple business profiles have been set up.

​object

Details of surcharge applied on this payment, if applicable

payment_type
​string · enum

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

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

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

session_expiry
​integer | null · int32 · min: 0

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

Example: 900
frm_metadata
​object | null

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

request_external_three_ds_authentication
​boolean | null

Whether to perform external authentication (if applicable)

Example: true
​object

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

​

Details required for recurring payment

​

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

request_extended_authorization
​boolean | null

Optional boolean value to extent authorization period of this payment

capture method must be manual or manual_multiple

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

Your unique identifier for this payment or order. This ID helps you reconcile payments on your system. If provided, it is passed to the connector if supported.

Example: Custom_Order_id_123
skip_external_tax_calculation
​boolean | null

Whether to calculate tax for this payment intent

psd2_sca_exemption_type
​string · enum

SCA Exemptions types available for authentication

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

Indicates if 3ds challenge is forced

threeds_method_comp_ind
​string · enum

Indicates if 3DS method data was successfully completed or not

Enum values:
Y
N
U
is_iframe_redirection_enabled
​boolean | null

Indicates if the redirection has to open in the iframe

all_keys_required
​boolean | null

If enabled, provides whole connector response

​

Describes the channel through which the payment was initiated.

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

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

Example: 6540
shipping_amount_tax
​integer · int64

This Unit struct represents MinorUnit in which core amount works

duty_amount
​integer · int64

This Unit struct represents MinorUnit in which core amount works

order_date
​string | null · date-time

Date the payer placed the order.

enable_partial_authorization
​boolean | null

Allow partial authorization for this payment

Default: false
enable_overcapture
​boolean | null

Boolean indicating whether to enable overcapture for this payment

Example: true
is_stored_credential
​boolean | null

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

Example: true
mit_category
​string · enum

Specifies the category of a Merchant Initiated Transaction (MIT). In the case of MIT, mit_category tells what kind of MIT is being processed. In the case of CIT, it tells the future intended MIT type.

Enum values:
installment
unscheduled
recurring
resubmission
​object

Billing Descriptor information to be sent to the payment gateway

tokenization
​string · enum

The type of tokenization to use for the payment method

Enum values:
skip_psp
tokenize_at_psp
​object

Information identifying partner and merchant application initiating the request

​array | null

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

​object

Installment selection sent by the customer during payment confirmation.

PaymentsResponse

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

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

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

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

Example: merchant_1668273825
status
​string · enum · required

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

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

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

Example: 6540
net_amount
​integer · int64 · required

The payment net amount. net_amount = amount + surcharge_details.surcharge_amount + surcharge_details.tax_amount + shipping_cost + order_tax_amount, If no surcharge_details, shipping_cost, order_tax_amount, net_amount = amount

Example: 6540
amount_capturable
​integer · int64 · min: 100 · required

The amount (in minor units) that can still be captured for this payment. This is relevant when capture_method is manual. Once fully captured, or if capture_method is automatic and payment succeeded, this will be 0.

Example: 6540
processor_merchant_id
​string · maxLength: 255 · required

The identifier for the processor merchant account. In platform-connected setups, this is the connected merchant ID. For standard merchants, this is same as merchant_id.

Example: merchant_1689512302
currency
​Currency · enum · required

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

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

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

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

Total number of attempts associated with this payment

shipping_cost
​integer | null · int64

The shipping cost for the payment.

Example: 6540
amount_received
​integer | null · int64

The total amount (in minor units) that has been captured for this payment. For fauxpay sandbox connector, this might reflect the authorized amount if status is succeeded even if capture_method was manual.

Example: 6540
initiator
​string · enum

Represents the initiator context in platform-connected setups Used in payment/refund/dispute responses to indicate who initiated the operation None indicates a standard merchant flow / JWT flow / Admin flow or insufficient information

Enum values:
platform
connected
sdk_authorization
​string | null

Token containing encoded information for sdk authorization.

Example: cHJvZmlsZV9pZD1wcm9mXzEyMyxwdWJsaXNoYWJsZV9rZXk9cGtfbGl2ZV8xMjM=
connector
​string | null

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

Example: stripe
​object

Additional metadata for payment intent state containing refunded and disputed amounts

client_secret
​string | null

A secret token unique to this payment intent. It is primarily used by client-side applications (e.g., Hyperswitch SDKs) to authenticate actions like confirming the payment or handling next actions. This secret should be handled carefully and not exposed publicly beyond its intended client-side use.

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

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

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

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

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

Details of customer attached to this payment

description
​string | null

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

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

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

​array | null

List of disputes that happened on this intent

​array | null

List of attempts that happened on this intent

​array | null

List of captures done on latest attempt

mandate_id
​string | null · maxLength: 255

A unique identifier to link the payment to a mandate, can be used instead of payment_method_data, in case of setting up recurring payments

Example: mandate_iwer89rnjef349dni3
​object

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

setup_future_usage
​string · enum

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

  • off_session: The payment method can be used for future payments when the customer is not present.
  • on_session: The payment method is intended for use only when the customer is present during checkout. If omitted, defaults to on_session.
Enum values:
off_session
on_session
off_session
​boolean | null

Set to true to indicate that the customer is not in your checkout flow during this payment, and therefore is unable to authenticate. This parameter is intended for scenarios where you collect card details and charge them later. This parameter can only be used with confirm=true.

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

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

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

Specifies how the payment is captured.

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

Provide a reference to a stored payment method

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

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

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

The URL to redirect after the completion of the operation

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

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

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

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

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

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

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

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

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

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

error_code
​string | null

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

Example: E0001
error_message
​string | null

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

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

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

unified_message
​string | null

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

​object

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

payment_experience
​string · enum

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

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

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

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

A label identifying the specific merchant connector account (MCA) used for this payment. This often combines the connector name, business country, and a custom label (e.g., "stripe_US_primary").

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

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

business_sub_label
​string | null

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

allowed_payment_method_types
​array | null

Allowed Payment Method Types for a given PaymentIntent

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

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

connector_transaction_id
​string | null

A unique identifier for a payment provided by the connector

Example: 993672945374576J
​object

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

metadata
​object | null

You can specify up to 50 keys, with key names up to 40 characters long and values up to 500 characters long. Metadata is useful for storing additional, structured information on an object.

​object

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

​
​object

additional data that might be required by hyperswitch

reference_id
​string | null

reference(Identifier) to the payment at connector side

Example: 993672945374576J
​object
profile_id
​string | null

The business profile that is associated with this payment

​object

Details of surcharge applied on this payment, if applicable

merchant_decision
​string | null

Denotes the action(approve or reject) taken by merchant in case of manual review. Manual review can occur when the transaction is marked as risky by the frm_processor, payment processor or when there is underpayment/over payment incase of crypto payment

merchant_connector_id
​string | null

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

incremental_authorization_allowed
​boolean | null

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

authorization_count
​integer | null · int32

Total number of authorizations happened in an incremental_authorization payment

​array | null

List of incremental authorizations happened to the payment

​object

Details of external authentication

external_3ds_authentication_attempted
​boolean | null

Flag indicating if external 3ds authentication is made or not

expires_on
​string | null · date-time

Date Time for expiry of the payment

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

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

​object

Browser information to be used for 3DS 2.0

​

Describes the channel through which the payment was initiated.

payment_method_id
​string | null

A unique identifier for the payment method used in this payment. If the payment method was saved or tokenized, this ID can be used to reference it for future transactions or recurring payments. Refer payment_method_tokenization_details for detailed view of payment method tokenization

network_transaction_id
​string | null

The network transaction ID is a unique identifier for the transaction as recognized by the payment network (e.g., Visa, Mastercard), this ID can be used to reference it for future transactions or recurring payments. Refer payment_method_tokenization_details for detailed view of payment method tokenization

payment_method_status
​string · enum

Payment Method Status

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

Date time at which payment was updated

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

Charge Information

frm_metadata
​object | null

You can specify up to 50 keys, with key names up to 40 characters long and values up to 500 characters long. FRM Metadata is useful for storing additional, structured information on an object related to FRM.

extended_authorization_applied
​boolean | null

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

extended_authorization_last_applied_at
​string | null · date-time

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

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

Optional boolean value to extent authorization period of this payment

capture method must be manual or manual_multiple

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

date and time after which this payment cannot be captured

merchant_order_reference_id
​string | null · maxLength: 255

Merchant's identifier for the payment/invoice. This will be sent to the connector if the connector provides support to accept multiple reference ids. In case the connector supports only one reference id, Hyperswitch's Payment ID will be sent as reference.

Example: Custom_Order_id_123
order_tax_amount
​integer · int64

This Unit struct represents MinorUnit in which core amount works

connector_mandate_id
​string | null

Connector Identifier for the payment method

card_discovery
​string · enum

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

Enum values:
manual
saved_card
click_to_pay
force_3ds_challenge
​boolean | null

Indicates if 3ds challenge is forced

force_3ds_challenge_trigger
​boolean | null

Indicates if 3ds challenge is triggered

issuer_error_code
​string | null

Error code received from the issuer in case of failed payments

issuer_error_message
​string | null

Error message received from the issuer in case of failed payments

is_iframe_redirection_enabled
​boolean | null

Indicates if the redirection has to open in the iframe

whole_connector_response
​string | null

Contains whole connector response

enable_partial_authorization
​boolean | null

Allow partial authorization for this payment

Default: false
enable_overcapture
​boolean | null

Bool indicating if overcapture must be requested for this payment

is_overcapture_enabled
​boolean | null

Boolean indicating whether overcapture is effectively enabled for this payment

​object
is_stored_credential
​boolean | null

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

Example: true
mit_category
​string · enum

Specifies the category of a Merchant Initiated Transaction (MIT). In the case of MIT, mit_category tells what kind of MIT is being processed. In the case of CIT, it tells the future intended MIT type.

Enum values:
installment
unscheduled
recurring
resubmission
​object

Billing Descriptor information to be sent to the payment gateway

tokenization
​string · enum

The type of tokenization to use for the payment method

Enum values:
skip_psp
tokenize_at_psp
​object

Information identifying partner and merchant application initiating the request

​object
​array | null

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

​object

Installment selection made by the customer during payment confirmation.

​object

Statistics for a customer within a single profile

​object

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

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

PaymentsRetrieveRequest

resource_id
​string · required

The type of ID (ex: payment intent id, payment attempt id or connector txn id)

force_sync
​boolean · required

Decider to enable or disable the connector call for retrieve request

merchant_id
​string | null

The identifier for the Merchant Account.

param
​string | null

Optional query parameters that might be specific to a connector or flow, passed through during the retrieve operation. Use with caution and refer to specific connector documentation if applicable.

connector
​string | null

Optionally specifies the connector to be used for a 'force_sync' retrieve operation. If provided, Hyperswitch will attempt to sync the payment status from this specific connector.

​object

Merchant connector details used to make payments.

client_secret
​string | null

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

expand_captures
​boolean | null

If enabled provides list of captures linked to latest attempt

expand_attempts
​boolean | null

If enabled provides list of attempts linked to payment intent

all_keys_required
​boolean | null

If enabled, provides whole connector response

expand_customer_statistics
​boolean | null

When true, response includes [crate::customers::CustomerStatisticsItem] for the payment's profile (OLAP).

PaymentsSessionRequest

payment_id
​string · required

The identifier for the payment

wallets
​PaymentMethodType[] · required

The list of the supported wallets

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

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

​object

Merchant connector details used to make payments.

PaymentsSessionResponse

payment_id
​string · required

The identifier for the payment

client_secret
​string · required

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

​SessionToken[] · required

The list of session token object

PaymentsUpdateMetadataRequest

metadata
​object · required

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

​object

additional data that might be required by hyperswitch

PaymentsUpdateMetadataResponse

payment_id
​string · required

The identifier for the payment

status
​string · enum · required

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

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

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

​object

additional data that might be required by hyperswitch

PaymentsUpdateRequest

amount
​integer | null · int64 · min: 0

The primary amount for the payment, provided in the lowest denomination of the specified currency (e.g., 6540 for $65.40 USD). This field is mandatory for creating a payment.

Example: 6540
order_tax_amount
​integer | null · int64

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

Example: 6540
currency
​string · enum

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

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

The amount to be captured from the user's payment method, in the lowest denomination. If not provided, and capture_method is automatic, the full payment amount will be captured. If capture_method is manual, this can be specified in the /capture call. Must be less than or equal to the authorized amount.

Example: 6540
shipping_cost
​integer | null · int64

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

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

Optional. A merchant-provided unique identifier for the payment, contains 30 characters long (e.g., "pay_mbabizu24mvu3mela5njyhpit4"). If provided, it ensures idempotency for the payment creation request. If omitted, Hyperswitch generates a unique ID for the payment.

Example: pay_mbabizu24mvu3mela5njyhpit4
​
connector
​array | null

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

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

Specifies how the payment is captured.

  • automatic: Funds are captured immediately after successful authorization. This is the default behavior if the field is omitted.
  • manual: Funds are authorized but not captured. A separate request to the /payments/{payment_id}/capture endpoint is required to capture the funds.
Enum values:
automatic
manual
manual_multiple
scheduled
sequential_automatic
authentication_type
​string · enum

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

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

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

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

If set to true, Hyperswitch attempts to confirm and authorize the payment immediately after creation, provided sufficient payment method details are included. If false or omitted (default is false), the payment is created with a status such as requires_payment_method or requires_confirmation, and a separate POST /payments/{payment_id}/confirm call is necessary to proceed with authorization.

Example: true
Default: false
​object

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

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

The identifier for the customer

Example: cus_y3oqhf46pyzuxjbcn2giaqnb44
​object

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

off_session
​boolean | null

Set to true to indicate that the customer is not in your checkout flow during this payment, and therefore is unable to authenticate. This parameter is intended for scenarios where you collect card details and charge them later. When making a recurring payment by passing a mandate_id, this parameter is mandatory

Example: true
description
​string | null

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

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

The URL to redirect the customer to after they complete the payment process or authentication. This is crucial for flows that involve off-site redirection (e.g., 3DS, some bank redirects, wallet payments).

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

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

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

The payment method information provided for making a payment

payment_method
​string · enum

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

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

As Hyperswitch tokenises the sensitive details about the payments method, it provides the payment_token as a reference to a stored payment method, ensuring that the sensitive details are not exposed in any manner.

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

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

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

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

​object

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

​object

Browser information to be used for 3DS 2.0

payment_experience
​string · enum

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

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

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

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

Merchant connector details used to make payments.

allowed_payment_method_types
​array | null

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

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

Denotes the retry action

Enum values:
manual_retry
requeue
metadata
​object | null

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

​object

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

payment_link
​boolean | null

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

Example: true
Default: false
​object

Configure a custom payment link for the particular payment

payment_link_config_id
​string | null

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

​object

Details of surcharge applied on this payment, if applicable

payment_type
​string · enum

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

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

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

session_expiry
​integer | null · int32 · min: 0

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

Example: 900
frm_metadata
​object | null

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

request_external_three_ds_authentication
​boolean | null

Whether to perform external authentication (if applicable)

Example: true
​object

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

​

Details required for recurring payment

​

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

request_extended_authorization
​boolean | null

Optional boolean value to extent authorization period of this payment

capture method must be manual or manual_multiple

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

Your unique identifier for this payment or order. This ID helps you reconcile payments on your system. If provided, it is passed to the connector if supported.

Example: Custom_Order_id_123
skip_external_tax_calculation
​boolean | null

Whether to calculate tax for this payment intent

psd2_sca_exemption_type
​string · enum

SCA Exemptions types available for authentication

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

Indicates if 3ds challenge is forced

threeds_method_comp_ind
​string · enum

Indicates if 3DS method data was successfully completed or not

Enum values:
Y
N
U
is_iframe_redirection_enabled
​boolean | null

Indicates if the redirection has to open in the iframe

all_keys_required
​boolean | null

If enabled, provides whole connector response

​

Describes the channel through which the payment was initiated.

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

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

Example: 6540
shipping_amount_tax
​integer · int64

This Unit struct represents MinorUnit in which core amount works

duty_amount
​integer · int64

This Unit struct represents MinorUnit in which core amount works

order_date
​string | null · date-time

Date the payer placed the order.

enable_partial_authorization
​boolean | null

Allow partial authorization for this payment

Default: false
enable_overcapture
​boolean | null

Boolean indicating whether to enable overcapture for this payment

Example: true
is_stored_credential
​boolean | null

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

Example: true
mit_category
​string · enum

Specifies the category of a Merchant Initiated Transaction (MIT). In the case of MIT, mit_category tells what kind of MIT is being processed. In the case of CIT, it tells the future intended MIT type.

Enum values:
installment
unscheduled
recurring
resubmission
​object

Billing Descriptor information to be sent to the payment gateway

tokenization
​string · enum

The type of tokenization to use for the payment method

Enum values:
skip_psp
tokenize_at_psp
​object

Information identifying partner and merchant application initiating the request

​array | null

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

​object

Installment selection sent by the customer during payment confirmation.

PayoutAttemptResponse

attempt_id
​string · required

Unique identifier for the attempt

status
​PayoutStatus · enum · required
Enum values:
success
failed
cancelled
initiated
expired
reversed
pending
ineligible
amount
​integer · int64 · required

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

Example: 6583
​FeeDetail[] · required

Fee snapshots for this attempt. The list contains at most one row.

currency
​string · enum

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

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

The connector used for the payout

error_code
​string | null

Connector's error code in case of failures

error_message
​string | null

Connector's error message in case of failures

payment_method
​string · enum

The payout_type of the payout request is a mandatory field for confirming the payouts. It should be specified in the Create request. If not provided, it must be updated in the Payout Update request before it can be confirmed.

Enum values:
card
bank
wallet
bank_redirect
payout_method_type
​string · enum

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

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

A unique identifier for a payout provided by the connector

cancellation_reason
​string | null

If the payout was cancelled the reason provided here

unified_code
​string | null · maxLength: 255

(This field is not live yet) Error code unified across the connectors is received here in case of errors while calling the underlying connector

Example: UE_000
unified_message
​string | null · maxLength: 1024

(This field is not live yet) Error message unified across the connectors is received here in case of errors while calling the underlying connector

Example: Invalid card details

PayoutCancelRequest

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

Unique identifier for the payout. This ensures idempotency for multiple payouts that have been done by a single merchant. This field is auto generated and is returned in the API response.

Example: 187282ab-40ef-47a9-9206-5099ba31e432

PayoutConfirmRequest

client_secret
​string · required

It's a token used for client side verification.

merchant_order_reference_id
​string | null · maxLength: 255

Your unique identifier for this payout or order. This ID helps you reconcile payouts on your system. If provided, it is passed to the connector if supported.

Example: merchant_order_ref_123
amount
​integer | null · int64 · min: 0

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

Example: 1000
currency
​string · enum

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

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

This field allows the merchant to manually select a connector with which the payout can go through.

Enum values:
phonypay
flexifai
fiftyfourpay
bitex
hypergate
maguapay
payadmit
milkypay
Example: ["wise","adyen"]
payout_type
​string · enum

The payout_type of the payout request is a mandatory field for confirming the payouts. It should be specified in the Create request. If not provided, it must be updated in the Payout Update request before it can be confirmed.

Enum values:
card
bank
wallet
bank_redirect
​

The payout method information required for carrying out a payout

​object
auto_fulfill
​boolean | null

Set to true to confirm the payout without review, no further action required

Example: true
Default: false
​object

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

return_url
​string | null

The URL to redirect after the completion of the operation

Example: https://hyperswitch.io
business_country
​string · enum
Enum values:
AF
AX
AL
DZ
AS
AD
AO
AI
description
​string | null

A description of the payout

Example: It's my first payout request
entity_type
​string · enum

Type of entity to whom the payout is being carried out to, select from the given list of options

Enum values:
Individual
Company
NonProfit
PublicSector
NaturalPerson
lowercase
Personal
recurring
​boolean | null

Specifies whether or not the payout request is recurring

Default: false
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.

payout_token
​string | null

Provide a reference to a stored payout method, used to process the payout.

Example: 187282ab-40ef-47a9-9206-5099ba31e432
profile_id
​string | null

The business profile to use for this payout, especially if there are multiple business profiles associated with the account, otherwise default business profile associated with the merchant account will be used.

priority
​string · enum

The send method which will be required for processing payouts, check options for better understanding.

Enum values:
instant
fast
regular
wire
cross_border
internal
payout_link
​boolean | null

Whether to get the payout link (if applicable). Merchant need to specify this during the Payout Create, this field can not be updated during Payout Update.

Example: true
Default: false
​object

Custom payout link config for the particular payout, if payout link is to be generated.

session_expiry
​integer | null · int32 · min: 0

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

Example: 900
payout_method_id
​string | null

Identifier for payout method

​object

Browser information to be used for 3DS 2.0

PayoutConnectors

string · enum
Enum values:
phonypay
flexifai
fiftyfourpay
bitex
hypergate
maguapay
payadmit
milkypay

PayoutCreatePayoutLinkConfig

Custom payout link config for the particular payout, if payout link is to be generated.
logo
​string | null · maxLength: 255

Merchant's display logo

Example: https://hyperswitch.io/favicon.ico
merchant_name
​string | null · maxLength: 255

Custom merchant name for the link

Example: Hyperswitch
theme
​string | null · maxLength: 255

Primary color to be used in the form represented in hex format

Example: #4285F4
payout_link_id
​string | null

The unique identifier for the collect link.

Example: pm_collect_link_2bdacf398vwzq5n422S1
​array | null

List of payout methods shown on collect UI

Example: [{"payment_method": "bank_transfer", "payment_method_types": ["ach", "bacs"]}]
form_layout
​string · enum
Enum values:
tabs
journey
test_mode
​boolean | null

test_mode allows for opening payout links without any restrictions. This removes

  • domain name validations
  • check for making sure link is accessed within an iframe
Example: false

PayoutCreateResponse

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

Unique identifier for the payout. This ensures idempotency for multiple payouts that have been done by a single merchant. This field is auto generated and is returned in the API response.

Example: 187282ab-40ef-47a9-9206-5099ba31e432
merchant_id
​string · maxLength: 255 · required

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

Example: merchant_1668273825
amount
​integer · int64 · required

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

Example: 1000
currency
​Currency · enum · required

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

Enum values:
AED
AFN
ALL
AMD
ANG
AOA
ARS
AUD
auto_fulfill
​boolean · required

Set to true to confirm the payout without review, no further action required

Example: true
Default: false
customer_id
​string · maxLength: 255 · required

The identifier for the customer object. If not provided the customer ID will be autogenerated.

Example: cus_y3oqhf46pyzuxjbcn2giaqnb44
client_secret
​string · required

It's a token used for client side verification.

Example: pay_U42c409qyHwOkWo3vK60_secret_el9ksDkiB8hi6j9N78yo
return_url
​string · required

The URL to redirect after the completion of the operation

Example: https://hyperswitch.io
business_country
​CountryAlpha2 · enum · required
Enum values:
AF
AX
AL
DZ
AS
AD
AO
AI
entity_type
​PayoutEntityType · enum · required

Type of entity to whom the payout is being carried out to, select from the given list of options

Enum values:
Individual
Company
NonProfit
PublicSector
NaturalPerson
lowercase
Personal
recurring
​boolean · required

Specifies whether or not the payout request is recurring

Default: false
status
​PayoutStatus · enum · required
Enum values:
success
failed
cancelled
initiated
expired
reversed
pending
ineligible
profile_id
​string · required

The business profile that is associated with this payout

merchant_order_reference_id
​string | null · maxLength: 255

Your unique identifier for this payout or order. This ID helps you reconcile payouts on your system. If provided, it is passed to the connector if supported.

Example: merchant_order_ref_123
connector
​string | null

The connector used for the payout

Example: wise
payout_type
​string · enum

The payout_type of the payout request is a mandatory field for confirming the payouts. It should be specified in the Create request. If not provided, it must be updated in the Payout Update request before it can be confirmed.

Enum values:
card
bank
wallet
bank_redirect
​

The payout method information for response

​object
​object

Details of customer attached to this payment

business_label
​string | null

Business label of the merchant for this payout

Example: food
description
​string | null

A description of the payout

Example: It's my first payout request
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.

merchant_connector_id
​string | null

Unique identifier of the merchant connector account

Example: mca_sAD3OZLATetvjLOYhUSy
error_message
​string | null

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

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

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

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

Time when the payout was created

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

Underlying processor's payout resource ID

Example: S3FC9G9M2MVFDXT5
priority
​string · enum

The send method which will be required for processing payouts, check options for better understanding.

Enum values:
instant
fast
regular
wire
cross_border
internal
​array | null

List of attempts

​object
unified_code
​string | null · maxLength: 255

(This field is not live yet) Error code unified across the connectors is received here in case of errors while calling the underlying connector

Example: UE_000
unified_message
​string | null · maxLength: 1024

(This field is not live yet) Error message unified across the connectors is received here in case of errors while calling the underlying connector

Example: Invalid card details
payout_method_id
​string | null

Identifier for payout method

​object

A fee snapshot summary for one business transaction.

PayoutEntityType

string · enum
Enum values:
Individual
Company
NonProfit
PublicSector
NaturalPerson
lowercase
Personal

Type of entity to whom the payout is being carried out to, select from the given list of options

PayoutFulfillRequest

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

Unique identifier for the payout. This ensures idempotency for multiple payouts that have been done by a single merchant. This field is auto generated and is returned in the API response.

Example: 187282ab-40ef-47a9-9206-5099ba31e432

PayoutLinkInitiateRequest

merchant_id
​string · required
payout_id
​string · required

PayoutLinkResponse

payout_link_id
​string · required
link
​string · required

PayoutListConstraints

A type representing a range of time for filtering, including a mandatory start time and an optional end time.
start_time
​string · date-time · required

The start time to filter payments list or to get list of filters. To get list of filters start time is needed to be passed

end_time
​string | null · date-time

The end time to filter payments list or to get list of filters. If not passed the default time is now

customer_id
​string | null

The identifier for customer

Example: cus_y3oqhf46pyzuxjbcn2giaqnb44
starting_after
​string | null

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

Example: payout_fafa124123
ending_before
​string | null

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

Example: payout_fafa124123
limit
​integer · int32 · min: 0 · max: 100

limit on the number of objects to return

Default: 10
created
​string | null · date-time

The time at which payout is created

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

PayoutListFilterConstraints

A type representing a range of time for filtering, including a mandatory start time and an optional end time.
start_time
​string · date-time · required

The start time to filter payments list or to get list of filters. To get list of filters start time is needed to be passed

currency
​Currency · enum · required

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

Enum values:
AED
AFN
ALL
AMD
ANG
AOA
ARS
AUD
entity_type
​PayoutEntityType · enum · required

Type of entity to whom the payout is being carried out to, select from the given list of options

Enum values:
Individual
Company
NonProfit
PublicSector
NaturalPerson
lowercase
Personal
end_time
​string | null · date-time

The end time to filter payments list or to get list of filters. If not passed the default time is now

payout_id
​string | null · minLength: 30 · maxLength: 30

The identifier for payout

Example: 187282ab-40ef-47a9-9206-5099ba31e432
merchant_order_reference_id
​string | null · maxLength: 255

The merchant order reference ID for payout

Example: merchant_order_ref_123
profile_id
​string | null

The identifier for business profile

customer_id
​string | null

The identifier for customer

Example: cus_y3oqhf46pyzuxjbcn2giaqnb44
limit
​integer · int32 · min: 0

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

offset
​integer | null · int32 · min: 0

The starting point within a list of objects

connector
​array | null

The list of connectors to filter payouts list

Enum values:
phonypay
flexifai
fiftyfourpay
bitex
hypergate
maguapay
payadmit
milkypay
Example: ["wise","adyen"]
status
​array | null

The list of payout status to filter payouts list

Enum values:
success
failed
cancelled
initiated
expired
reversed
pending
ineligible
Example: ["pending","failed"]
payout_method
​array | null

The list of payout methods to filter payouts list

Enum values:
card
bank
wallet
bank_redirect
Example: ["bank","card"]
​object[]

Column predicates. Combined with other fields using AND.

PayoutListFilters

connector
​PayoutConnectors[] · required

The list of available connector filters

Enum values:
phonypay
flexifai
fiftyfourpay
bitex
hypergate
maguapay
payadmit
milkypay
currency
​Currency[] · required

The list of available currency filters

Enum values:
AED
AFN
ALL
AMD
ANG
AOA
ARS
AUD
status
​PayoutStatus[] · required

The list of available payout status filters

Enum values:
success
failed
cancelled
initiated
expired
reversed
pending
ineligible
payout_method
​PayoutType[] · required

The list of available payout method filters

Enum values:
card
bank
wallet
bank_redirect

PayoutListResponse

size
​integer · min: 0 · required

The number of payouts included in the list

​PayoutCreateResponse[] · required

The list of payouts response objects

total_count
​integer | null · int64

The total number of available payouts for given constraints

PayoutMethodData

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · requires: card
type = object · requires: bank
type = object · requires: wallet
type = object · requires: bank_redirect
type = object · requires: passthrough
Properties for Variant 1:
​CardPayout · required

PayoutMethodDataResponse

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · requires: card
type = object · requires: bank
type = object · requires: wallet
type = object · requires: bank_redirect
type = object · requires: passthrough
Properties for Variant 1:
​CardAdditionalData · required

Masked payout method details for card payout method

PayoutRetrieveBody

force_sync
​boolean | null
merchant_id
​string | null

PayoutRetrieveRequest

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

Unique identifier for the payout. This ensures idempotency for multiple payouts that have been done by a single merchant. This field is auto generated and is returned in the API response.

Example: 187282ab-40ef-47a9-9206-5099ba31e432
force_sync
​boolean | null

force_sync with the connector to get payout details (defaults to false)

Example: true
Default: false
merchant_id
​string | null

The identifier for the Merchant Account.

PayoutSendPriority

string · enum
Enum values:
instant
fast
regular
wire
cross_border
internal

The send method which will be required for processing payouts, check options for better understanding.

PayoutStatus

string · enum
Enum values:
success
failed
cancelled
initiated
expired
reversed
pending
ineligible

PayoutTableField

string · enum
Enum values:
payout_id
customer_id
amount
currency
status
payout_type
description
created

Payout and payout-attempt columns shown on the payouts table.

PayoutType

string · enum
Enum values:
card
bank
wallet
bank_redirect

The payout_type of the payout request is a mandatory field for confirming the payouts. It should be specified in the Create request. If not provided, it must be updated in the Payout Update request before it can be confirmed.

PayoutUpdateRequest

merchant_order_reference_id
​string | null · maxLength: 255

Your unique identifier for this payout or order. This ID helps you reconcile payouts on your system. If provided, it is passed to the connector if supported.

Example: merchant_order_ref_123
amount
​integer | null · int64 · min: 0

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

Example: 1000
currency
​string · enum

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

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

This field allows the merchant to manually select a connector with which the payout can go through.

Enum values:
phonypay
flexifai
fiftyfourpay
bitex
hypergate
maguapay
payadmit
milkypay
Example: ["wise","adyen"]
confirm
​boolean | null

This field is used when merchant wants to confirm the payout, thus useful for the payout Confirm request. Ideally merchants should Create a payout, Update it (if required), then Confirm it.

Example: true
Default: false
payout_type
​string · enum

The payout_type of the payout request is a mandatory field for confirming the payouts. It should be specified in the Create request. If not provided, it must be updated in the Payout Update request before it can be confirmed.

Enum values:
card
bank
wallet
bank_redirect
​

The payout method information required for carrying out a payout

​object
auto_fulfill
​boolean | null

Set to true to confirm the payout without review, no further action required

Example: true
Default: false
​object

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

client_secret
​string | null

It's a token used for client side verification.

Example: pay_U42c409qyHwOkWo3vK60_secret_el9ksDkiB8hi6j9N78yo
return_url
​string | null

The URL to redirect after the completion of the operation

Example: https://hyperswitch.io
business_country
​string · enum
Enum values:
AF
AX
AL
DZ
AS
AD
AO
AI
description
​string | null

A description of the payout

Example: It's my first payout request
entity_type
​string · enum

Type of entity to whom the payout is being carried out to, select from the given list of options

Enum values:
Individual
Company
NonProfit
PublicSector
NaturalPerson
lowercase
Personal
recurring
​boolean | null

Specifies whether or not the payout request is recurring

Default: false
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.

payout_token
​string | null

Provide a reference to a stored payout method, used to process the payout.

Example: 187282ab-40ef-47a9-9206-5099ba31e432
profile_id
​string | null

The business profile to use for this payout, especially if there are multiple business profiles associated with the account, otherwise default business profile associated with the merchant account will be used.

priority
​string · enum

The send method which will be required for processing payouts, check options for better understanding.

Enum values:
instant
fast
regular
wire
cross_border
internal
payout_link
​boolean | null

Whether to get the payout link (if applicable). Merchant need to specify this during the Payout Create, this field can not be updated during Payout Update.

Example: true
Default: false
​object

Custom payout link config for the particular payout, if payout link is to be generated.

session_expiry
​integer | null · int32 · min: 0

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

Example: 900
payout_method_id
​string | null

Identifier for payout method

​object

Browser information to be used for 3DS 2.0

PayoutsCreateRequest

amount
​integer · int64 · min: 0 · required

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

currency
​Currency · enum · required

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

Enum values:
AED
AFN
ALL
AMD
ANG
AOA
ARS
AUD
merchant_order_reference_id
​string | null · maxLength: 255

Your unique identifier for this payout or order. This ID helps you reconcile payouts on your system. If provided, it is passed to the connector if supported.

Example: merchant_order_ref_123
​
connector
​array | null

This field allows the merchant to manually select a connector with which the payout can go through.

Enum values:
phonypay
flexifai
fiftyfourpay
bitex
hypergate
maguapay
payadmit
milkypay
Example: ["wise","adyen"]
confirm
​boolean | null

This field is used when merchant wants to confirm the payout, thus useful for the payout Confirm request. Ideally merchants should Create a payout, Update it (if required), then Confirm it.

Example: true
Default: false
payout_type
​string · enum

The payout_type of the payout request is a mandatory field for confirming the payouts. It should be specified in the Create request. If not provided, it must be updated in the Payout Update request before it can be confirmed.

Enum values:
card
bank
wallet
bank_redirect
​

The payout method information required for carrying out a payout

​object
auto_fulfill
​boolean | null

Set to true to confirm the payout without review, no further action required

Example: true
Default: false
​object

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

return_url
​string | null

The URL to redirect after the completion of the operation

Example: https://hyperswitch.io
business_country
​string · enum
Enum values:
AF
AX
AL
DZ
AS
AD
AO
AI
description
​string | null

A description of the payout

Example: It's my first payout request
entity_type
​string · enum

Type of entity to whom the payout is being carried out to, select from the given list of options

Enum values:
Individual
Company
NonProfit
PublicSector
NaturalPerson
lowercase
Personal
recurring
​boolean | null

Specifies whether or not the payout request is recurring

Default: false
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.

payout_token
​string | null

Provide a reference to a stored payout method, used to process the payout.

Example: 187282ab-40ef-47a9-9206-5099ba31e432
profile_id
​string | null

The business profile to use for this payout, especially if there are multiple business profiles associated with the account, otherwise default business profile associated with the merchant account will be used.

priority
​string · enum

The send method which will be required for processing payouts, check options for better understanding.

Enum values:
instant
fast
regular
wire
cross_border
internal
payout_link
​boolean | null

Whether to get the payout link (if applicable). Merchant need to specify this during the Payout Create, this field can not be updated during Payout Update.

Example: true
Default: false
​object

Custom payout link config for the particular payout, if payout link is to be generated.

session_expiry
​integer | null · int32 · min: 0

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

Example: 900
payout_method_id
​string | null

Identifier for payout method

​object

Browser information to be used for 3DS 2.0

Paypal

email
​string · required

Email linked with paypal account

Example: john.doe@example.com
telephone_number
​string · required

mobile number linked to paypal account

Example: 16608213349
paypal_id
​string · required

id of the paypal account

Example: G83KXTJ5EHCQ2

PaypalAdditionalData

Masked payout method details for paypal wallet payout method
email
​string | null

Email linked with paypal account

Example: john.doe@example.com
telephone_number
​string | null

mobile number linked to paypal account

Example: ******* 3349
paypal_id
​string | null

id of the paypal account

Example: G83K ***** HCQ2

PaypalFlow

string · enum
Enum values:
checkout

PaypalRedirection

email
​string | null · maxLength: 255

paypal's email address

Example: johntest@test.com

PaypalSessionTokenResponse

connector
​string · required

Name of the connector

session_token
​string · required

The session token for PayPal

​SdkNextAction · required
client_token
​string | null

Authorization token used by client to initiate sdk

​object

PaypalTransactionInfo

flow
​PaypalFlow · enum · required
Enum values:
checkout
currency_code
​Currency · enum · required

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

Enum values:
AED
AFN
ALL
AMD
ANG
AOA
ARS
AUD
total_price
​string · required

Total price

Example: 38.02

PayseraData

PazeSessionTokenResponse

client_id
​string · required

Paze Client ID

client_name
​string · required

Client Name to be displayed on the Paze screen

client_profile_id
​string · required

Paze Client Profile ID

transaction_currency_code
​Currency · enum · required

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

Enum values:
AED
AFN
ALL
AMD
ANG
AOA
ARS
AUD
transaction_amount
​string · required

The transaction amount

Example: 38.02
email_address
​string | null · maxLength: 255

Email Address

Example: johntest@test.com

PazeWalletData

complete_response
​string · required

PeachpaymentsData

rrn
​string | null

A numeric reference number supplied by the system retaining the original source information and used to assist in locating that information or a copy thereof.

PeriodUnit

string · enum
Enum values:
Day
Week
Month
Year

PermissionScope

string · enum
Enum values:
read
write

PhoneDetails

number
​string | null

The contact number

Example: 9123456789
country_code
​string | null

The country code attached to the number

Example: +1

PixAdditionalDetails

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · requires: immediate
type = object · requires: scheduled
Properties for Variant 1:
​ImmediateExpirationTime · required

PixBankTransfer

bank_account_number
​string · required

Bank account number is an unique identifier assigned by a bank to a customer.

Example: 000123456
pix_key
​string · required

Unique key for pix customer

Example: 000123456
bank_name
​string | null

Bank name

Example: Deutsche Bank
bank_branch
​string | null

Bank branch

Example: 3707
tax_id
​string | null

Individual taxpayer identification number

Example: 000123456

PixBankTransferAdditionalData

pix_key
​string | null

Partially masked unique key for pix transfer

Example: a1f4102e ****** 6fa48899c1d1
cpf
​string | null

Partially masked CPF - CPF is a Brazilian tax identification number

Example: **** 124689
cnpj
​string | null

Partially masked CNPJ - CNPJ is a Brazilian company tax identification number

Example: **** 417312
source_bank_account_id
​string | null

Partially masked source bank account number

Example: ********-****-4073-****-9fa964d08bc5
expiry_date
​string | null

The expiration date and time for the Pix QR code in ISO 8601 format

Example: 2025-09-10T10:11:12Z

PixKey

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · type="cpf" · requires: value
type = object · type="cnpj" · requires: value
type = object · type="email" · requires: value
type = object · type="phone" · requires: value
type = object · type="evp_token" · requires: value
Properties for Variant 1:
type
​string · enum · required
Enum values:
cpf
value
​string · required

PlatformAccountCreateRequest

organization_name
​string · maxLength: 64 · required

PlatformAccountCreateResponse

org_id
​string · minLength: 1 · maxLength: 64 · required
org_type
​OrganizationType · enum · required
Enum values:
standard
platform
merchant_id
​string · required
merchant_account_type
​MerchantAccountType · enum · required
Enum values:
standard
platform
connected
org_name
​string | null

PlatformBaseCurrencyResponse

Locked platform base currency for the current tenant.
base_currency
​Currency · enum · required

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

Enum values:
AED
AFN
ALL
AMD
ANG
AOA
ARS
AUD

PollConfig

delay_in_secs
​integer · int32 · min: 0 · required

Interval of the poll

frequency
​integer · int32 · min: 0 · required

Frequency of the poll

PollConfigResponse

poll_id
​string · required

Poll Id

delay_in_secs
​integer · int32 · required

Interval of the poll

frequency
​integer · int32 · required

Frequency of the poll

PollResponse

poll_id
​string · required

The poll id

status
​PollStatus · enum · required
Enum values:
pending
completed
not_found

PollStatus

string · enum
Enum values:
pending
completed
not_found

PostAuthenticationRequestPaymentMethodData

payment_method_type
​AuthenticationPaymentMethodType · enum · required
Enum values:
ctp
​AuthenticationPaymentMethodData · required

PostCaptureVoidResponse

Additional metadata for payment intent state containing refunded and disputed amounts
updated_at
​string · date-time · required

Timestamp when the post capture void was last updated

status
​string · enum

The status of a post-capture void operation

Enum values:
succeeded
pending
failed
connector_reference_id
​string | null

Connector reference id for post capture void

description
​string | null

Description or message related to the post capture void

PostCaptureVoidStatus

string · enum
Enum values:
succeeded
pending
failed

The status of a post-capture void operation

PrimaryBusinessDetails

country
​CountryAlpha2 · enum · required
Enum values:
AF
AX
AL
DZ
AS
AD
AO
AI
business
​string · required

PriorityLogicData

name
​string | null

Name of the logic

Example: success_rate_logic
status
​string | null

Status of the logic execution

Example: success
failure_reason
​string | null

Reason for failure if the logic failed

Example: insufficient_data

PriorityLogicOutput

isEnforcement
​boolean | null

Whether enforcement mode is enabled

Example: false
gws
​array | null

List of gateways returned by the priority logic

Example: ["stripe:mca1","adyen:mca2"]
priorityLogicTag
​string | null

Tag identifying the priority logic used

gatewayReferenceIds
​object | null

Map of gateway reference IDs

​object
​object

ProcessorPaymentToken

Processor payment token for MIT payments where payment_method_data is not available
processor_payment_token
​string · required
merchant_connector_id
​string | null

ProductType

string · enum
Enum values:
physical
digital
travel
ride
event
accommodation

ProfileAcquirerCreate

acquirer_assigned_merchant_id
​string · required

The merchant id assigned by the acquirer

Example: M123456789
merchant_name
​string · required

merchant name

Example: NewAge Retailer
network
​string · required

Network provider

Example: VISA
acquirer_bin
​string · required

Acquirer bin

Example: 456789
acquirer_fraud_rate
​number · double · required

Fraud rate for the particular acquirer configuration

Example: 0.01
profile_id
​string · required

Parent profile id to link the acquirer account with

Example: pro_ky0yNyOXXlA5hF8JzE5q
acquirer_ica
​string | null

Acquirer ica provided by acquirer

Example: 401288

ProfileAcquirerResponse

profile_acquirer_id
​string · required

The unique identifier of the profile acquirer

Example: pro_acq_LCRdERuylQvNQ4qh3QE0
acquirer_assigned_merchant_id
​string · required

The merchant id assigned by the acquirer

Example: M123456789
merchant_name
​string · required

Merchant name

Example: NewAge Retailer
network
​string · required

Network provider

Example: VISA
acquirer_bin
​string · required

Acquirer bin

Example: 456789
acquirer_fraud_rate
​number · double · required

Fraud rate for the particular acquirer configuration

Example: 0.01
profile_id
​string · required

Parent profile id to link the acquirer account with

Example: pro_ky0yNyOXXlA5hF8JzE5q
acquirer_ica
​string | null

Acquirer ica provided by acquirer

Example: 401288

ProfileAcquirerUpdate

acquirer_assigned_merchant_id
​string | null
merchant_name
​string | null
network
​string | null
acquirer_bin
​string | null
acquirer_ica
​string | null
acquirer_fraud_rate
​number | null · double

ProfileCreate

profile_name
​string | null · maxLength: 64

The name of profile

return_url
​string | null · maxLength: 255

The URL to redirect after the completion of the operation

Example: https://www.example.com/success
enable_payment_response_hash
​boolean | null

A boolean value to indicate if payment response hash needs to be enabled

Example: true
Default: true
payment_response_hash_key
​string | null

Refers to the hash key used for calculating the signature for webhooks and redirect response. If the value is not provided, a value is automatically generated.

redirect_to_merchant_with_http_post
​boolean | null

A boolean value to indicate if redirect to merchant with http post needs to be enabled

Example: true
Default: false
​object
metadata
​object | null

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

routing_algorithm
​object | null

The routing algorithm to be used for routing payments to desired connectors

intent_fulfillment_time
​integer | null · int32 · min: 0

Will be used to determine the time till which your payment will be active once the payment session starts

Example: 900
frm_routing_algorithm
​object | null

The frm routing algorithm to be used for routing payments to desired FRM's

​
applepay_verified_domains
​array | null

Verified Apple Pay domains for a particular profile

session_expiry
​integer | null · int32 · min: 0

Client Secret Default expiry for all payments created under this profile

Example: 900
​object
​object
use_billing_as_payment_method_billing
​boolean | null

Whether to use the billing details passed when creating the intent as payment method billing

collect_shipping_details_from_wallet_connector
​boolean | null

A boolean value to indicate if customer shipping details needs to be collected from wallet connector only if it is required field for connector (Eg. Apple Pay, Google Pay etc)

Example: false
Default: false
collect_billing_details_from_wallet_connector
​boolean | null

A boolean value to indicate if customer billing details needs to be collected from wallet connector only if it is required field for connector (Eg. Apple Pay, Google Pay etc)

Example: false
Default: false
always_collect_shipping_details_from_wallet_connector
​boolean | null

A boolean value to indicate if customer shipping details needs to be collected from wallet connector irrespective of connector required fields (Eg. Apple pay, Google pay etc)

Example: false
Default: false
always_collect_billing_details_from_wallet_connector
​boolean | null

A boolean value to indicate if customer billing details needs to be collected from wallet connector irrespective of connector required fields (Eg. Apple pay, Google pay etc)

Example: false
Default: false
is_connector_agnostic_mit_enabled
​boolean | null

Indicates if the MIT (merchant initiated transaction) payments can be made connector agnostic, i.e., MITs may be processed through different connector than CIT (customer initiated transaction) based on the routing rules. If set to false, MIT will go through the same connector as the CIT.

​object

Object for GenericLinkUiConfig

outgoing_webhook_custom_http_headers
​object | null

These key-value pairs are sent as additional custom headers in the outgoing webhook request. It is recommended not to use more than four key-value pairs.

tax_connector_id
​string | null

Merchant Connector id to be stored for tax_calculator connector

is_tax_connector_enabled
​boolean

Indicates if tax_calculator connector is enabled or not. If set to true tax_connector_id will be checked.

is_network_tokenization_enabled
​boolean

Indicates if network tokenization is enabled or not.

is_auto_retries_enabled
​boolean | null

Indicates if is_auto_retries_enabled is enabled or not.

max_auto_retries_enabled
​integer | null · int32 · min: 0

Maximum number of auto retries allowed for a payment

always_request_extended_authorization
​boolean | null

Bool indicating if extended authentication must be requested for all payments

is_click_to_pay_enabled
​boolean

Indicates if click to pay is enabled or not.

authentication_product_ids
​object | null

Product authentication ids

​object
is_clear_pan_retries_enabled
​boolean | null

Indicates if clear pan retries is enabled or not.

force_3ds_challenge
​boolean | null

Indicates if 3ds challenge is forced

is_debit_routing_enabled
​boolean | null

Indicates if debit routing is enabled or not

merchant_business_country
​string · enum
Enum values:
AF
AX
AL
DZ
AS
AD
AO
AI
is_iframe_redirection_enabled
​boolean | null

Indicates if the redirection has to open in the iframe

Example: false
is_pre_network_tokenization_enabled
​boolean | null

Indicates if pre network tokenization is enabled or not

merchant_category_code
​string
merchant_country_code
​string

A wrapper type for merchant country codes that provides validation and conversion functionality.

This type stores a country code as a string and provides methods to validate it and convert it to a Country enum variant.

dispute_polling_interval
​integer | null · int32

Time interval (in hours) for polling the connector to check for new disputes

Example: 2
is_manual_retry_enabled
​boolean | null

Indicates if manual retry for payment is enabled or not

always_require_payout_approval
​boolean | null

When true, a confirmed payout that would normally move to requires_creation instead stays in awaiting_approval until approved via payouts update-status.

Example: true
Default: true
always_enable_overcapture
​boolean | null

Bool indicating if overcapture must be requested for all payments

is_external_vault_enabled
​string · enum
Enum values:
enable
skip
​object
billing_processor_id
​string | null

Merchant Connector id to be stored for billing_processor connector

is_l2_l3_enabled
​boolean | null

Flag to enable Level 2 and Level 3 processing data for card transactions

show_logo
​boolean | null

Whether to show logo

Example: true
Default: true
logo_url
​string | null · maxLength: 255

The logo URL

Example: https://www.example.com/logo.png
​object

Configuration for payment method blocking based on card attributes

auto_cancel_timeout_secs
​integer | null · int64

Timeout in seconds after which eligible payment intents are auto-cancelled

auto_cancel_eligible_statuses
​array | null

Payment intent statuses eligible for auto-cancellation

Enum values:
succeeded
failed
cancelled
cancelled_post_capture
processing
requires_customer_action
requires_merchant_action
requires_payment_method
is_default_fallback_routing_enabled
​boolean

Use default fallback routing when no routing rule matches

ProfileDefaultRoutingConfig

Default routing configuration associated with a business profile. This represents the fallback routing connectors configured at the profile level.
profile_id
​string · required

Unique identifier of the business profile.

Example:

JSONCode
"profile_123"
Example: profile_123
​RoutableConnectorChoice[] · required

List of connectors configured as default for this profile.

Example:

JSONCode
[ { "connector": "stripe", "merchant_connector_id": "mca_ExbsYfO1xFErhNtwY1PX" } ]

ProfileId

string

A type for profile_id that can be used for business profile ids

ProfileResponse

merchant_id
​string · maxLength: 64 · required

The identifier for Merchant Account

Example: y3oqhf46pyzuxjbcn2giaqnb44
profile_id
​string · maxLength: 64 · required

The identifier for profile. This must be used for creating merchant accounts, payments and payouts

Example: pro_abcdefghijklmnopqrstuvwxyz
profile_name
​string · maxLength: 64 · required

Name of the profile

enable_payment_response_hash
​boolean · required

A boolean value to indicate if payment response hash needs to be enabled

Example: true
Default: true
redirect_to_merchant_with_http_post
​boolean · required

A boolean value to indicate if redirect to merchant with http post needs to be enabled

Example: true
Default: false
is_tax_connector_enabled
​boolean · required

Indicates if tax_calculator connector is enabled or not. If set to true tax_connector_id will be checked.

is_network_tokenization_enabled
​boolean · required

Indicates if network tokenization is enabled or not.

Example: false
Default: false
is_auto_retries_enabled
​boolean · required

Indicates if is_auto_retries_enabled is enabled or not.

Example: false
Default: false
is_click_to_pay_enabled
​boolean · required

Indicates if click to pay is enabled or not.

Example: false
Default: false
is_clear_pan_retries_enabled
​boolean · required

Indicates if clear pan retries is enabled or not.

force_3ds_challenge
​boolean · required

Indicates if 3ds challenge is forced

is_pre_network_tokenization_enabled
​boolean · required

Indicates if pre network tokenization is enabled or not

Example: false
Default: false
is_default_fallback_routing_enabled
​boolean · required

Use default fallback routing when no routing rule matches

Example: false
Default: false
return_url
​string | null · maxLength: 255

The URL to redirect after the completion of the operation

Example: https://www.example.com/success
payment_response_hash_key
​string | null

Refers to the hash key used for calculating the signature for webhooks and redirect response. If the value is not provided, a value is automatically generated.

​object
metadata
​object | null

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

routing_algorithm
​object | null

The routing algorithm to be used for routing payments to desired connectors

intent_fulfillment_time
​integer | null · int64

Will be used to determine the time till which your payment will be active once the payment session starts

Example: 900
frm_routing_algorithm
​object | null

The routing algorithm to be used to process the incoming request from merchant to outgoing payment processor or payment method. The default is 'Custom'

​
applepay_verified_domains
​array | null

Verified Apple Pay domains for a particular profile

session_expiry
​integer | null · int64

Client Secret Default expiry for all payments created under this profile

Example: 900
​object
​object
use_billing_as_payment_method_billing
​boolean | null
​object
collect_shipping_details_from_wallet_connector
​boolean | null

A boolean value to indicate if customer shipping details needs to be collected from wallet connector only if it is required field for connector (Eg. Apple Pay, Google Pay etc)

Example: false
Default: false
collect_billing_details_from_wallet_connector
​boolean | null

A boolean value to indicate if customer billing details needs to be collected from wallet connector only if it is required field for connector (Eg. Apple Pay, Google Pay etc)

Example: false
Default: false
always_collect_shipping_details_from_wallet_connector
​boolean | null

A boolean value to indicate if customer shipping details needs to be collected from wallet connector irrespective of connector required fields (Eg. Apple pay, Google pay etc)

Example: false
Default: false
always_collect_billing_details_from_wallet_connector
​boolean | null

A boolean value to indicate if customer billing details needs to be collected from wallet connector irrespective of connector required fields (Eg. Apple pay, Google pay etc)

Example: false
Default: false
is_connector_agnostic_mit_enabled
​boolean | null

Indicates if the MIT (merchant initiated transaction) payments can be made connector agnostic, i.e., MITs may be processed through different connector than CIT (customer initiated transaction) based on the routing rules. If set to false, MIT will go through the same connector as the CIT.

is_raw_card_data_enabled
​boolean | null

Indicates whether direct raw card data is accepted for payments on this profile.

Example: false
Default: false
​object

Object for GenericLinkUiConfig

outgoing_webhook_custom_http_headers
​object | null

These key-value pairs are sent as additional custom headers in the outgoing webhook request.

tax_connector_id
​string | null

Merchant Connector id to be stored for tax_calculator connector

max_auto_retries_enabled
​integer | null · int32

Maximum number of auto retries allowed for a payment

always_request_extended_authorization
​boolean | null

Bool indicating if extended authentication must be requested for all payments

authentication_product_ids
​object | null

Product authentication ids

​object
is_debit_routing_enabled
​boolean | null

Indicates if debit routing is enabled or not

merchant_business_country
​string · enum
Enum values:
AF
AX
AL
DZ
AS
AD
AO
AI
​array | null

Acquirer configs

is_iframe_redirection_enabled
​boolean | null

Indicates if the redirection has to open in the iframe

Example: false
merchant_category_code
​string
merchant_country_code
​string

A wrapper type for merchant country codes that provides validation and conversion functionality.

This type stores a country code as a string and provides methods to validate it and convert it to a Country enum variant.

dispute_polling_interval
​integer | null · int32 · min: 0

Time interval (in hours) for polling the connector to check dispute statuses

Example: 2
is_manual_retry_enabled
​boolean | null

Indicates if manual retry for payment is enabled or not

always_require_payout_approval
​boolean | null

When true, a confirmed payout that would normally move to requires_creation instead stays in awaiting_approval until approved via payouts update-status.

always_enable_overcapture
​boolean | null

Bool indicating if overcapture must be requested for all payments

is_external_vault_enabled
​string · enum
Enum values:
enable
skip
​object
billing_processor_id
​string | null

Merchant Connector id to be stored for billing_processor connector

is_l2_l3_enabled
​boolean | null

Flag to enable Level 2 and Level 3 processing data for card transactions

show_logo
​boolean | null

Whether to show logo

Example: true
Default: true
logo_url
​string | null · maxLength: 255

The logo URL

Example: https://www.example.com/logo.png
​object

Configuration for payment method blocking based on card attributes

auto_cancel_timeout_secs
​integer | null · int64

Timeout in seconds after which eligible payment intents are auto-cancelled

auto_cancel_eligible_statuses
​array | null

Payment intent statuses eligible for auto-cancellation

Enum values:
succeeded
failed
cancelled
cancelled_post_capture
processing
requires_customer_action
requires_merchant_action
requires_payment_method

ProgramConnectorCostConfigs

​ConnectorCostConfigs · required
​RuleConnectorCostConfigs · required
​object · required

ProgramConnectorSelection

The program, having a default connector selection and a bunch of rules. Also can hold arbitrary metadata.
​ConnectorSelection · required
​RuleConnectorSelection · required

Represents a rule

Code
rule_name: [stripe, adyen, checkout] { payment.method = card { payment.method.cardtype = (credit, debit) { payment.method.network = (amex, rupay, diners) } payment.method.cardtype = credit } }
​object · required

ProgramMerchantCommissionConfigs

​MerchantCommissionConfigs · required
​RuleMerchantCommissionConfigs · required
​object · required

ProgramThreeDsDecisionRule

​ThreeDSDecisionRule · required

Struct representing the output configuration for the 3DS Decision Rule Engine.

​RuleThreeDsDecisionRule · required
​object · required

RankingAlgorithm

string · enum
Enum values:
SR_BASED_ROUTING
PL_BASED_ROUTING
NTW_BASED_ROUTING

RealTimePaymentData

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · requires: fps
type = object · requires: duit_now
type = object · requires: prompt_pay
type = object · requires: viet_qr
type = object · requires: qris
Properties for Variant 1:
fps
​object · required

RealTimePaymentDataResponse

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · requires: fps
type = object · requires: duit_now
type = object · requires: prompt_pay
type = object · requires: viet_qr
type = object · requires: qris
Properties for Variant 1:
fps
​object · required

ReceiverDetails

amount_received
​integer · int64 · required

The amount received by receiver

amount_charged
​integer | null · int64

The amount charged by ACH

amount_remaining
​integer | null · int64

The amount remaining to be sent via ACH

RecommendedAction

string · enum
Enum values:
do_not_retry
retry_after_10_days
retry_after_1_hour
retry_after_24_hours
retry_after_2_days
retry_after_4_days
retry_after_6_days
retry_after_8_days

ReconStatus

string · enum
Enum values:
not_requested
requested
active
disabled

RecurringDetails

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · type="mandate_id" · requires: data
type = object · type="payment_method_id" · requires: data
type = object · type="processor_payment_token" · requires: data
type = object · type="network_transaction_id_and_card_details" · requires: data
type = object · type="network_transaction_id_and_network_token_details" · requires: data
type = object · type="network_transaction_id_and_decrypted_wallet_token_details" · requires: data
type = object · type="card_with_limited_data" · requires: data
Properties for Variant 1:
type
​string · enum · required
Enum values:
mandate_id
data
​string · required

RecurringPaymentIntervalUnit

string · enum
Enum values:
year
month
day
hour
minute

RedirectResponse

param
​string | null
json_payload
​object | null

RefundListRequest

A type representing a range of time for filtering, including a mandatory start time and an optional end time.
start_time
​string · date-time · required

The start time to filter payments list or to get list of filters. To get list of filters start time is needed to be passed

end_time
​string | null · date-time

The end time to filter payments list or to get list of filters. If not passed the default time is now

payment_id
​string | null

The identifier for the payment

payment_id_in
​array | null

Restrict results to refunds for these payment IDs (e.g. customer recent activity).

refund_id
​string | null

The identifier for the refund

profile_id
​string | null

The identifier for business profile

limit
​integer | null · int64

Limit on the number of objects to return

offset
​integer | null · int64

The starting point within a list of objects

​object
connector
​array | null

The list of connectors to filter refunds list

merchant_connector_id
​array | null

The list of merchant connector ids to filter the refunds list for selected label

currency
​array | null

The list of currencies to filter refunds list

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

The list of refund statuses to filter refunds list

Enum values:
succeeded
failed
pending
review
​object[]

Column predicates. Combined with other fields using AND.

RefundListResponse

count
​integer · min: 0 · required

The number of refunds included in the list

total_count
​integer · int64 · required

The total number of refunds in the list

​RefundResponse[] · required

The List of refund response object

RefundRequest

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

The payment id against which refund is to be initiated

Example: pay_mbabizu24mvu3mela5njyhpit4
refund_id
​string | null · minLength: 30 · maxLength: 30

Unique Identifier for the Refund. This is to ensure idempotency for multiple partial refunds initiated against the same payment. If this is not passed by the merchant, this field shall be auto generated and provided in the API response. It is recommended to generate uuid(v4) as the refund_id.

Example: ref_mbabizu24mvu3mela5njyhpit4
merchant_id
​string | null · maxLength: 255

The identifier for the Merchant Account

Example: y3oqhf46pyzuxjbcn2giaqnb44
amount
​integer | null · int64 · min: 100

Total amount for which the refund is to be initiated. Amount for the payment in lowest denomination of the currency. (i.e) in cents for USD denomination, in paisa for INR denomination etc., If not provided, this will default to the full payment amount

Example: 6540
reason
​string | null · maxLength: 255

Reason for the refund. Often useful for displaying to users and your customer support executive. In case the payment went through Stripe, this field needs to be passed with one of these enums: duplicate, fraudulent, or requested_by_customer

Example: Customer returned the product
refund_type
​string · enum

To indicate whether to refund needs to be instant or scheduled

Enum values:
scheduled
instant
Default: Instant
metadata
​object | null

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

​object

Merchant connector details used to make payments.

​

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

all_keys_required
​boolean | null

If true, returns stringified connector raw response body

RefundResponse

refund_id
​string · required

Unique Identifier for the refund

payment_id
​string · required

The payment id against which refund is initiated

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

Example: 6540
currency
​string · required

The three-letter ISO currency code

status
​RefundStatus · enum · required

The status for refunds

Enum values:
succeeded
failed
pending
review
connector
​string · required

The connector used for the refund and the corresponding payment

Example: stripe
reason
​string | null

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

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

error_message
​string | null

The error message

error_code
​string | null

The code for the error

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

created_at
​string | null · date-time

The timestamp at which refund is created

updated_at
​string | null · date-time

The timestamp at which refund is updated

profile_id
​string | null

The id of business profile for this refund

merchant_connector_id
​string | null

The merchant_connector_id of the processor through which this payment went through

​

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

issuer_error_code
​string | null

Error code received from the issuer in case of failed refunds

issuer_error_message
​string | null

Error message received from the issuer in case of failed refunds

raw_connector_response
​string | null

Contains whole connector response

connector_refund_id
​string | null

A unique identifier for a payment provided by the connector

​object

A fee snapshot summary for one business transaction.

RefundStatus

string · enum
Enum values:
succeeded
failed
pending
review

The status for refunds

RefundTableField

string · enum
Enum values:
refund_id
payment_id
amount
currency
status
reason
connector
merchant_connector_id

Refund table columns.

RefundType

string · enum
Enum values:
scheduled
instant

To indicate whether to refund needs to be instant or scheduled

RefundUpdateRequest

reason
​string | null · maxLength: 255

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

Example: Customer returned the product
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.

RefundableCreditsHandling

string · enum
Enum values:
no_action
schedule_refund

RegisterConnectorWebhookResponse

​
connector_webhook_id
​string | null
webhook_registration_status
​string · enum

The status of webhook registration

Enum values:
Success
Failure
error_code
​string | null
error_message
​string | null

RelayCaptureRequestData

authorized_amount
​integer · int64 · required

The amount that is authorized for capture

Example: 6540
amount_to_capture
​integer · int64 · required

The amount that is being captured

Example: 6540
currency
​Currency · enum · required

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

Enum values:
AED
AFN
ALL
AMD
ANG
AOA
ARS
AUD
capture_method
​string · enum

Specifies how the payment is captured.

  • automatic: Funds are captured immediately after successful authorization. This is the default behavior if the field is omitted.
  • manual: Funds are authorized but not captured. A separate request to the /payments/{payment_id}/capture endpoint is required to capture the funds.
Enum values:
automatic
manual
manual_multiple
scheduled
sequential_automatic

RelayData

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · requires: refund
type = object · requires: capture
type = object · requires: incremental_authorization
type = object · requires: void
Properties for Variant 1:
​RelayRefundRequestData · required

RelayError

code
​string · required

The error code

message
​string · required

The error message

RelayIncrementalAuthorizationRequestData

total_amount
​integer · int64 · required

Original amount + additional amount of the transaction

Example: 6540
additional_amount
​integer · int64 · required

The amount by which the payment needs is incremented

Example: 6540
currency
​Currency · enum · required

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

Enum values:
AED
AFN
ALL
AMD
ANG
AOA
ARS
AUD

RelayRefundRequestData

amount
​integer · int64 · required

The amount that is being refunded

Example: 6540
currency
​Currency · enum · required

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

Enum values:
AED
AFN
ALL
AMD
ANG
AOA
ARS
AUD
reason
​string | null · maxLength: 255

The reason for the refund

Example: Customer returned the product

RelayRequest

connector_resource_id
​string · required

The identifier that is associated to a resource at the connector reference to which the relay request is being made

Example: 7256228702616471803954
connector_id
​string · required

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

Example: mca_5apGeP94tMts6rg3U3kR
type
​RelayType · enum · required
Enum values:
refund
capture
incremental_authorization
void
​

RelayResponse

id
​string · required

The unique identifier for the Relay

Example: relay_mbabizu24mvu3mela5njyhpit4
status
​RelayStatus · enum · required
Enum values:
created
pending
success
failure
connector_resource_id
​string · required

The identifier that is associated to a resource at the connector reference to which the relay request is being made

Example: pi_3MKEivSFNglxLpam0ZaL98q9
connector_id
​string · required

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

Example: mca_5apGeP94tMts6rg3U3kR
profile_id
​string · required

The business profile that is associated with this relay request.

Example: pro_abcdefghijklmnopqrstuvwxyz
type
​RelayType · enum · required
Enum values:
refund
capture
incremental_authorization
void
​object
connector_reference_id
​string | null

The identifier that is associated to a resource at the connector to which the relay request is being made

Example: re_3QY4TnEOqOywnAIx1Mm1p7GQ
​

RelayStatus

string · enum
Enum values:
created
pending
success
failure

RelayType

string · enum
Enum values:
refund
capture
incremental_authorization
void

RelayVoidRequestData

amount
​integer · int64 · required

The amount of the transaction that is being voided

Example: 6540
currency
​string · enum

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

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

The cancellation reason for voiding the transaction

Example: Requested by merchant

RequestPaymentMethodTypes

payment_method_type
​PaymentMethodType · enum · required

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

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

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

Enum values:
redirect_to_url
invoke_sdk_client
display_qr_code
one_click
link_wallet
invoke_payment_app
display_wait_screen
collect_otp
card_networks
​array | null
Enum values:
Visa
Mastercard
AmericanExpress
JCB
DinersClub
Discover
CartesBancaires
UnionPay
​
​

Object to filter the customer countries for which the payment method is displayed

minimum_amount
​integer · int64

This Unit struct represents MinorUnit in which core amount works

maximum_amount
​integer · int64

This Unit struct represents MinorUnit in which core amount works

recurring_enabled
​boolean | null

Indicates whether the payment method supports recurring payments. Optional.

Example: false
installment_payment_enabled
​boolean | null

Indicates whether the payment method is eligible for installment payments (e.g., EMI, BNPL). Optional.

Example: true

RequestSurchargeDetails

Details of surcharge applied on this payment, if applicable
surcharge_amount
​integer · int64 · required
tax_amount
​integer · int64

This Unit struct represents MinorUnit in which core amount works

RequiredFieldInfo

Required fields info used while listing the payment_method_data
required_field
​string · required

Required field for a payment_method through a payment_method_type

display_name
​string · required

Display name of the required field in the front-end

​FieldType · required

Possible field type of required fields in payment_method_data

value
​string | null

Resource

string · enum
Enum values:
payment
refund
api_key
account
connector
routing
dispute
mandate

ResponsePaymentMethodTypes

payment_method_type
​PaymentMethodType · enum · required

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

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

The list of payment experiences enabled, if applicable for a payment method type

​array | null

The list of card networks enabled, if applicable for a payment method type

​object
​object
​object | null

Required fields for the payment_method_type.

​object
pm_auth_connector
​string | null

auth service connector label for this payment method type, if exists

ResponsePaymentMethodsEnabled

payment_method
​PaymentMethod · enum · required

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

Enum values:
card
card_redirect
pay_later
wallet
bank_redirect
bank_transfer
crypto
bank_debit
​ResponsePaymentMethodTypes[] · required

The list of payment method types enabled for a connector account

ResumeOption

string · enum
Enum values:
immediately
specific_date

ResumeSubscriptionRequest

Request payload for resuming a subscription.
resume_option
​string · enum
Enum values:
immediately
specific_date
resume_date
​string | null

Optional date when the subscription should be resumed (if not provided, resumes immediately)

charges_handling
​string · enum
Enum values:
invoice_immediately
add_to_unbilled_charges
unpaid_invoices_handling
​string · enum
Enum values:
no_action
schedule_payment_collection

ResumeSubscriptionResponse

Response payload returned after successfully resuming a subscription.
id
​SubscriptionId · required

A type for subscription_id that can be used for subscription ids

status
​SubscriptionStatus · enum · required

Possible states of a subscription lifecycle.

  • Created: Subscription was created but not yet activated.
  • Active: Subscription is currently active.
  • InActive: Subscription is inactive.
  • Pending: Subscription is pending activation.
  • Trial: Subscription is in a trial period.
  • Paused: Subscription is paused.
  • Unpaid: Subscription is unpaid.
  • Onetime: Subscription is a one-time payment.
  • Cancelled: Subscription has been cancelled.
  • Failed: Subscription has failed.
Enum values:
active
created
in_active
pending
trial
paused
unpaid
onetime
profile_id
​ProfileId · required

A type for profile_id that can be used for business profile ids

merchant_id
​MerchantId · required

A type for merchant_id that can be used for merchant ids

customer_id
​CustomerId · required

A type for customer_id that can be used for customer ids

merchant_reference_id
​string | null

Merchant specific Unique identifier.

next_billing_at
​string | null

Date when the subscription was resumed

RetrieveApiKeyResponse

The response body for retrieving an API Key.
key_id
​string · maxLength: 64 · required

The identifier for the API Key.

Example: 5hEEqkgJUyuxgSKGArHA4mWSnX
name
​string · maxLength: 64 · required

The unique name for the API Key to help you identify it.

Example: Sandbox integration key
prefix
​string · maxLength: 64 · required

The first few characters of the plaintext API Key to help you identify it.

created
​string · date-time · required

The time at which the API Key was created.

Example: 2022-09-10T10:11:12Z
​ApiKeyExpiration · required
​ApiKeyPermissionGrant[] · required

JSON column value: explicit non-empty grants for the key.

merchant_id
​string | null · maxLength: 64

The identifier for the Merchant Account.

Example: y3oqhf46pyzuxjbcn2giaqnb44
organization_id
​string | null

The identifier for the Organization Account.

tenant_id
​string | null

The identifier for the Tenant.

description
​string | null · maxLength: 256

The description to provide more context about the API Key.

Example: Key used by our developers to integrate with the sandbox environment
whitelisted_ips
​array | null

Whitelisted IP addresses for this key. Empty or absent means all IPs are allowed.

RetrievePaymentLinkRequest

client_secret
​string | null

It's a token used for client side verification.

RetrievePaymentLinkResponse

payment_link_id
​string · required

Identifier for Payment Link

merchant_id
​string · required

Identifier for Merchant

link_to_pay
​string · required

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

amount
​integer · int64 · required

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

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

Date and time of Payment Link creation

status
​PaymentLinkStatus · enum · required

Status Of the Payment Link

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

Date and time of Expiration for Payment Link

description
​string | null

Description for Payment Link

currency
​string · enum

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

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

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

RetryAction

string · enum
Enum values:
manual_retry
requeue

Denotes the retry action

RetryFeatureData

Represents the data associated with a retry feature in GSM.
step_up_possible
​boolean · required

indicates if step_up retry is possible

clear_pan_possible
​boolean · required

indicates if retry with pan is possible

alternate_network_possible
​boolean · required

indicates if retry with alternate network possible

decision
​GsmDecision · enum · required
Enum values:
retry
do_default

RevokeApiKeyResponse

The response body for revoking an API Key.
key_id
​string · maxLength: 64 · required

The identifier for the API Key.

Example: 5hEEqkgJUyuxgSKGArHA4mWSnX
revoked
​boolean · required

Indicates whether the API key was revoked or not.

Example: true
merchant_id
​string | null · maxLength: 64

The identifier for the Merchant Account.

Example: y3oqhf46pyzuxjbcn2giaqnb44
organization_id
​string | null

The identifier for the Organization Account.

tenant_id
​string | null

The identifier for the Tenant.

RevolutPayData

RewardData

merchant_id
​string · required

The merchant ID with which we have to call the connector

RoutableChoiceKind

string · enum
Enum values:
OnlyConnector
FullStruct

RoutableConnectorChoice

Routable Connector chosen for a payment
connector
​RoutableConnectors · enum · required

RoutableConnectors are the subset of Connectors that are eligible for payments routing

Enum values:
flexifai
fiftyfourpay
k218pay
bitex
hypergate
maguapay
payadmit
milkypay
merchant_connector_id
​string | null

RoutableConnectors

string · enum
Enum values:
flexifai
fiftyfourpay
k218pay
bitex
hypergate
maguapay
payadmit
milkypay

RoutableConnectors are the subset of Connectors that are eligible for payments routing

RoutingAlgorithmKind

string · enum
Enum values:
single
priority
volume_split
advanced
dynamic
three_ds_decision_rule

RoutingAlgorithmWrapper

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
No specific criteria
No specific criteria
Properties for Variant 1:
oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · type="single" · requires: data
type = object · type="priority" · requires: data
type = object · type="volume_split" · requires: data
type = object · type="advanced" · requires: data
type = object · type="three_ds_decision_rule" · requires: data
Properties for Variant 1:
type
​string · enum · required
Enum values:
single
​RoutableConnectorChoice · required

Routable Connector chosen for a payment

RoutingConfigRequest

name
​string | null

Unique name of the routing configuration.

This identifier is used to reference the routing config internally.

Example:

JSONCode
"default_card_routing"
Example: default_card_routing
description
​string | null

Optional human-readable description of the routing configuration.

Example:

JSONCode
"Primary routing strategy for card payments in India"
Example: Primary routing strategy for card payments in Middle east
​
profile_id
​string | null

Profile ID associated with this routing configuration.

Routing configs can be scoped per business profile.

Example:

JSONCode
"profile_123"
Example: profile_123
transaction_type
​string · enum
Enum values:
payment
payout
three_ds_authentication

RoutingDictionary

Routing dictionary for a merchant. Contains all routing configurations created by the merchant, along with the currently active routing configuration.
merchant_id
​string · required

Unique merchant identifier.

Example:

JSONCode
"merchant_789"
Example: merchant_789
​RoutingDictionaryRecord[] · required

List of all routing configuration records associated with this merchant.

active_id
​string | null

Currently active routing configuration ID.

Example:

JSONCode
"routing_abc123"
Example: routing_abc123

RoutingDictionaryRecord

Metadata record representing a stored routing configuration. Used in routing dictionary listings.
id
​string · required

Unique identifier of the routing configuration.

Example:

JSONCode
"routing_abc123"
Example: routing_abc123
profile_id
​string · required

Profile ID associated with this routing configuration.

Example:

JSONCode
"profile_123"
Example: profile_123
name
​string · required

Name of the routing configuration.

Example:

JSONCode
"india_card_routing"
Example: india_card_routing
kind
​RoutingAlgorithmKind · enum · required
Enum values:
single
priority
volume_split
advanced
dynamic
three_ds_decision_rule
description
​string · required

Description of this routing configuration.

Example:

JSONCode
"Volume split routing for domestic transactions"
Example: Volume split routing for domestic transactions
created_at
​integer · int64 · required

Creation timestamp (milliseconds since epoch).

Example: 1718000000000
modified_at
​integer · int64 · required

Last modification timestamp (milliseconds since epoch).

Example: 1718050000000
algorithm_for
​string · enum
Enum values:
payment
payout
three_ds_authentication
decision_engine_routing_id
​string | null

Associated Decision Engine routing identifier (if applicable).

Present when routing is linked to an external decision engine.

Example:

JSONCode
"de_route_456"
Example: de_route_456

RoutingEvaluateRequest

Request body used to evaluate routing rules. This API evaluates routing logic based on dynamic parameters like payment method, amount, country, card_bin, etc.
created_by
​string · required

Identifier of the user/system triggering routing evaluation.

Example:

JSONCode
"created_by": "some_id"
Example: profile_123
parameters
​object · required

Dynamic parameters used during routing evaluation.

Each key represents a routing attribute.

Example fields:

  • payment_method
  • payment_method_type
  • amount
  • currency
  • authentication_type
  • card_bin
  • capture_method
  • business_country
  • billing_country
  • business_label
  • setup_future_usage
  • card_network
  • payment_type
  • mandate_type
  • mandate_acceptance_type
  • metadata

Example:

JSONCode
{ "payment_method": { "type": "enum_variant", "value": "card" }, "amount": { "type": "number", "value": 10 }, "currency": { "type": "str_value", "value": "INR" }, "authentication_type": { "type": "enum_variant", "value": "three_ds" }, "card_bin": { "type": "str_value", "value": "424242" }, "business_country": { "type": "str_value", "value": "IN" }, "setup_future_usage": { "type": "enum_variant", "value": "off_session" }, "card_network": { "type": "enum_variant", "value": "visa" }, "metadata": { "type": "metadata_variant", "value": { "key": "key1", "value": "value1" } } }

For the complete superset of supported routing keys, refer to routing_configs.keys in: https://github.com/juspay/decision-engine/blob/main/config/development.toml

​DeRoutableConnectorChoice[] · required

Fallback connectors used if routing rule evaluation fails.

These connectors will be returned if no rule matches.

Example:

JSONCode
[ { "gateway_name": "stripe", "gateway_id": "mca_123" } ]

RoutingEvaluateResponse

Response returned after routing evaluation. Contains: - Routing status - Raw output structure (priority / volume_split) - Final evaluated connectors - Eligible connectors list
status
​string · required

Status of routing evaluation.

Example:

JSONCode
"success"
Example: success
output
​required

Raw routing output returned by routing engine.

Possible structures:

  1. Volume Split:
JSONCode
{ "type": "volume_split", "splits": [ { "connector": { "gateway_name": "adyen", "gateway_id": "mca_124" }, "split": 60 }, { "connector": { "gateway_name": "stripe", "gateway_id": "mca_123" }, "split": 40 } ] }
  1. Priority:
JSONCode
{ "type": "priority", "connectors": [ { "gateway_name": "stripe", "gateway_id": "mca_123" }, { "gateway_name": "adyen", "gateway_id": "mca_124" } ] }
​RoutableConnectorChoice[] · required

Final connector(s) selected after evaluation.

Example:

JSONCode
[ { "connector": "stripe", "merchant_connector_id": "mca_123" } ]
​RoutableConnectorChoice[] · required

RoutingKind

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · requires: merchant_id, records
type = array
Properties for Variant 1:
Routing dictionary for a merchant. Contains all routing configurations created by the merchant, along with the currently active routing configuration.
merchant_id
​string · required

Unique merchant identifier.

Example:

JSONCode
"merchant_789"
Example: merchant_789
​RoutingDictionaryRecord[] · required

List of all routing configuration records associated with this merchant.

active_id
​string | null

Currently active routing configuration ID.

Example:

JSONCode
"routing_abc123"
Example: routing_abc123

RoutingRetrieveResponse

Response returned when retrieving routing configuration for a merchant account.
​object

Routing algorithm configuration created for a merchant.

Represents a fully defined routing strategy scoped to a profile and transaction type.

RoutingVolumeSplitResponse

split
​integer · int32 · min: 0 · required

RuleConnectorCostConfigs

name
​string · required
​ConnectorCostConfigs · required
​IfStatement[] · required

RuleConnectorSelection

Represents a rule ```text rule_name: [stripe, adyen, checkout] { payment.method = card { payment.method.cardtype = (credit, debit) { payment.method.network = (amex, rupay, diners) } payment.method.cardtype = credit } } ```
name
​string · required
​ConnectorSelection · required
​IfStatement[] · required

RuleMerchantCommissionConfigs

name
​string · required
​MerchantCommissionConfigs · required
​IfStatement[] · required

RuleThreeDsDecisionRule

name
​string · required
connectorSelection
​ThreeDSDecision · enum · required

Enum representing the possible outcomes of the 3DS Decision Rule Engine.

Enum values:
no_three_ds
challenge_requested
challenge_preferred
three_ds_exemption_requested_tra
three_ds_exemption_requested_low_value
issuer_three_ds_exemption_requested
​IfStatement[] · required

SamsungPayAmountDetails

option
​SamsungPayAmountFormat · enum · required
Enum values:
FORMAT_TOTAL_PRICE_ONLY
FORMAT_TOTAL_ESTIMATED_AMOUNT
currency_code
​Currency · enum · required

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

Enum values:
AED
AFN
ALL
AMD
ANG
AOA
ARS
AUD
total
​string · required

The total amount of the transaction

Example: 38.02

SamsungPayAmountFormat

string · enum
Enum values:
FORMAT_TOTAL_PRICE_ONLY
FORMAT_TOTAL_ESTIMATED_AMOUNT

SamsungPayAppWalletData

​SamsungPayTokenData · required
payment_card_brand
​SamsungPayCardBrand · enum · required
Enum values:
visa
mastercard
amex
discover
unknown
payment_currency_type
​string · required

Currency type of the payment

payment_last4_fpan
​string · required

Last 4 digits of the card number

payment_last4_dpan
​string | null

Last 4 digits of the device specific card number

merchant_ref
​string | null

Merchant reference id that was passed in the session call request

method
​string | null

Specifies authentication method used

recurring_payment
​boolean | null

Value if credential is enabled for recurring payment

SamsungPayCardBrand

string · enum
Enum values:
visa
mastercard
amex
discover
unknown

SamsungPayMerchantPaymentInformation

name
​string · required

Merchant name, this will be displayed on the Samsung Pay screen

country_code
​CountryAlpha2 · enum · required
Enum values:
AF
AX
AL
DZ
AS
AD
AO
AI
url
​string | null

Merchant domain that process payments, required for web payments

SamsungPayProtocolType

string · enum
Enum values:
PROTOCOL3DS

SamsungPaySessionTokenResponse

version
​string · required

Samsung Pay API version

service_id
​string · required

Samsung Pay service ID to which session call needs to be made

order_number
​string · required

Order number of the transaction

​SamsungPayMerchantPaymentInformation · required
​SamsungPayAmountDetails · required
protocol
​SamsungPayProtocolType · enum · required
Enum values:
PROTOCOL3DS
allowed_brands
​string[] · required

List of supported card brands

billing_address_required
​boolean · required

Is billing address required to be collected from wallet

shipping_address_required
​boolean · required

Is shipping address required to be collected from wallet

SamsungPayTokenData

version
​string · required

3DS version used by Samsung Pay

data
​string · required

Samsung Pay encrypted payment credential data

type
​string | null

3DS type used by Samsung Pay

SamsungPayWalletCredentials

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · requires: card_brand, card_last4digits, 3_d_s
type = object · requires: 3_d_s, payment_card_brand, payment_currency_type +1 more
Properties for Variant 1:
card_brand
​SamsungPayCardBrand · enum · required
Enum values:
visa
mastercard
amex
discover
unknown
card_last4digits
​string · required

Last 4 digits of the card number

​SamsungPayTokenData · required
method
​string | null

Specifies authentication method used

recurring_payment
​boolean | null

Value if credential is enabled for recurring payment

SamsungPayWalletData

​SamsungPayWalletCredentials · required

SamsungPayWebWalletData

card_brand
​SamsungPayCardBrand · enum · required
Enum values:
visa
mastercard
amex
discover
unknown
card_last4digits
​string · required

Last 4 digits of the card number

​SamsungPayTokenData · required
method
​string | null

Specifies authentication method used

recurring_payment
​boolean | null

Value if credential is enabled for recurring payment

SantanderData

end_to_end_id
​string | null

ScaExemptionType

string · enum
Enum values:
low_value
transaction_risk_analysis

SCA Exemptions types available for authentication

ScheduledExpirationTime

date
​string · required

Expiration time in terms of date, format: YYYY-MM-DD

Example: 2026-07-08
validity_after_expiration
​integer | null · int32 · min: 0

Days after expiration date for which the QR code remains valid

Example: 10
​

SdkDisplayMode

string · enum
Enum values:
default_sdk_message
custom_message
hidden

Display mode options for controlling how messages are shown.

SdkInformation

SDK Information if request is from SDK
sdk_app_id
​string · required

Unique ID created on installations of the 3DS Requestor App on a Consumer Device

sdk_enc_data
​string · required

JWE Object containing data encrypted by the SDK for the DS to decrypt

​object · required

Public key component of the ephemeral key pair generated by the 3DS SDK

sdk_trans_id
​string · required

Unique transaction identifier assigned by the 3DS SDK

sdk_reference_number
​string · required

Identifies the vendor and version for the 3DS SDK that is integrated in a 3DS Requestor App

sdk_max_timeout
​integer · int32 · min: 0 · required

Indicates maximum amount of time in minutes

sdk_type
​string · enum

Enum representing the type of 3DS SDK.

Enum values:
01
02
03
04
05
​object

Device details for collecting Device information

SdkNextAction

​NextActionCall · required

SdkNextActionData

​NextActionCall · required
order_id
​string | null

SdkType

string · enum
Enum values:
01
02
03
04
05

Enum representing the type of 3DS SDK.

SecretInfoToInitiateSdk

display
​string · required
payment
​string · required

SepaAndBacsBillingDetails

email
​string | null

The Email ID for SEPA and BACS billing

Example: example@me.com
name
​string | null

The billing name for SEPA and BACS billing

Example: Jane Doe

SepaBankDebitAdditionalData

iban
​string · required

Partially masked international bank account number (iban) for SEPA

Example: DE8937******013000
bank_account_holder_name
​string | null

Bank account's owner name

Example: John Doe

SepaBankTransfer

iban
​string · required

International Bank Account Number (iban) - used in many countries for identifying a bank along with it's customer.

Example: DE89370400440532013000
bic
​string · required

[8 / 11 digits] Bank Identifier Code (bic) / Swift Code - used in many countries for identifying a bank and it's branches

Example: HSBCGB2LXXX
bank_name
​string | null

Bank name

Example: Deutsche Bank
bank_country_code
​string · enum
Enum values:
AF
AX
AL
DZ
AS
AD
AO
AI
bank_city
​string | null

Bank city

Example: California

SepaBankTransferAdditionalData

Masked payout method details for sepa bank transfer payout method
iban
​string · required

Partially masked international bank account number (iban) for SEPA

Example: DE8937******013000
bank_name
​string | null

Bank name

Example: Deutsche Bank
bank_country_code
​string · enum
Enum values:
AF
AX
AL
DZ
AS
AD
AO
AI
bank_city
​string | null

Bank city

Example: California
bic
​string | null

[8 / 11 digits] Bank Identifier Code (bic) / Swift Code - used in many countries for identifying a bank and it's branches

Example: HSBCGB2LXXX

SepaBankTransferInstructions

account_holder_name
​string · required
bic
​string · required
country
​string · required
iban
​string · required
reference
​string · required

SepaBankTransferPaymentAdditionalData

debitor_iban
​string | null

debitor IBAN

Example: DE89370400440532013000
debitor_bic
​string | null

debitor BIC

Example: MARKDEF1100
debitor_name
​string | null

debitor name

Example: John Doe
debitor_email
​string | null

debitor email

Example: johndoe@example.com

SessionToken

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · wallet_name="google_pay"
type = object · wallet_name="samsung_pay" · requires: version, service_id, order_number +6 more
type = object · wallet_name="klarna" · requires: session_token, session_id
type = object · wallet_name="paypal" · requires: connector, session_token, sdk_next_action
type = object · wallet_name="apple_pay" · requires: connector, delayed_session_token, sdk_next_action
type = object · wallet_name="open_banking" · requires: open_banking_session_token
type = object · wallet_name="paze" · requires: client_id, client_name, client_profile_id +2 more
type = object · wallet_name="click_to_pay" · requires: dpa_id, dpa_name, locale +6 more
type = object · wallet_name="amazon_pay" · requires: merchant_id, ledger_currency, store_id +5 more
type = object · wallet_name="no_session_token_received"
Properties for Variant 1:
wallet_name
​string · enum · required
Enum values:
google_pay
oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · requires: delayed_session_token, connector, sdk_next_action
type = object · requires: merchant_info, shipping_address_required, email_required +6 more
Properties for Variant 1:
delayed_session_token
​boolean · required

Identifier for the delayed session response

connector
​string · required

The name of the connector

​SdkNextAction · required

SessionTokenInfo

certificate
​string · required
certificate_keys
​string · required
merchant_identifier
​string · required
display_name
​string · required
initiative
​ApplepayInitiative · enum · required
Enum values:
web
ios
initiative_context
​string | null
merchant_business_country
​string · enum
Enum values:
AF
AX
AL
DZ
AS
AD
AO
AI
oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · payment_processing_details_at="Hyperswitch" · requires: payment_processing_certificate, payment_processing_certificate_key
type = object · payment_processing_details_at="Connector"
Properties for Variant 1:
payment_processing_certificate
​string · required
payment_processing_certificate_key
​string · required
payment_processing_details_at
​string · enum · required
Enum values:
Hyperswitch

SizeVariants

string · enum
Enum values:
cover
contain

SkrillData

SortBy

string · enum
Enum values:
asc
desc

SortOn

string · enum
Enum values:
amount
created
modified

SplitPaymentsRequest

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · requires: stripe_split_payment
type = object · requires: adyen_split_payment
type = object · requires: xendit_split_payment
Properties for Variant 1:
​StripeSplitPaymentRequest · required

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

SplitRefund

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · requires: stripe_split_refund
type = object · requires: adyen_split_refund
type = object · requires: xendit_split_refund
Properties for Variant 1:
​StripeSplitRefundRequest · required

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

StandardisedCode

string · enum
Enum values:
account_closed_or_invalid
authentication_failed
authentication_required
authorization_missing_or_revoked
card_lost_or_stolen
card_not_supported_restricted
cfg_pm_not_enabled_or_misconfigured
compliance_or_sanctions_restriction

StaticRoutingAlgorithm

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · type="single" · requires: data
type = object · type="priority" · requires: data
type = object · type="volume_split" · requires: data
type = object · type="advanced" · requires: data
type = object · type="three_ds_decision_rule" · requires: data
Properties for Variant 1:
type
​string · enum · required
Enum values:
single
​RoutableConnectorChoice · required

Routable Connector chosen for a payment

StraightThroughAlgorithm

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · type="single" · requires: data
type = object · type="priority" · requires: data
type = object · type="volume_split" · requires: data
Properties for Single:
type
​string · enum · required
Enum values:
single
​RoutableConnectorChoice · required

Routable Connector chosen for a payment

StraightThroughAlgorithmInfo

Human-readable summary of the routing decision that was applied to a specific payment attempt. The raw `straight_through_algorithm` JSON stored in `payment_attempts` is deserialized here so dashboards can render the connector order, algorithm type, and the connector that was actually selected. `algorithm` uses [`StraightThroughAlgorithmInner`] rather than [`StraightThroughAlgorithm`] so that it serialises directly as `{"type": "single", "data": ...}`. [`StraightThroughAlgorithm`] wraps through [`StraightThroughAlgorithmSerde::Nested`] which would produce an extra `{"algorithm": {...}}` nesting layer in the JSON response.
algorithm
​
routed_through
​string | null

The connector identifier that the routing algorithm ultimately selected. Corresponds to RoutingData::routed_through in the domain model.

StringMinorUnit

string

Connector specific types to send

StripeChargeResponseData

Fee information to be charged on the payment being collected via Stripe
​PaymentChargeType · required
application_fees
​integer · int64 · required

Platform fees collected on the payment

Example: 6540
transfer_account_id
​string · required

Identifier for the reseller's account where the funds were transferred

charge_id
​string | null

Identifier for charge created for the payment

StripeChargeType

string · enum
Enum values:
direct
destination

StripeSplitPaymentRequest

Fee information for Split Payments to be charged on the payment being collected for Stripe
​PaymentChargeType · required
application_fees
​integer · int64 · required

Platform fees to be collected on the payment

Example: 6540
transfer_account_id
​string · required

Identifier for the reseller's account where the funds were transferred

StripeSplitRefundRequest

Charge specific fields for controlling the revert of funds from either platform or connected account for Stripe. Check sub-fields for more details.
revert_platform_fee
​boolean | null

Toggle for reverting the application fee that was collected for the payment. If set to false, the funds are pulled from the destination account.

revert_transfer
​boolean | null

Toggle for reverting the transfer that was made during the charge. If set to false, the funds are pulled from the main platform's account.

SubscriptionId

string

A type for subscription_id that can be used for subscription ids

SubscriptionItemPrices

price_id
​string · required
amount
​MinorUnit · int64 · required

This Unit struct represents MinorUnit in which core amount works

currency
​Currency · enum · required

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

Enum values:
AED
AFN
ALL
AMD
ANG
AOA
ARS
AUD
interval
​PeriodUnit · enum · required
Enum values:
Day
Week
Month
Year
interval_count
​integer · int64 · required
item_id
​string | null
trial_period
​integer | null · int64
trial_period_unit
​string · enum
Enum values:
Day
Week
Month
Year

SubscriptionItemType

string · enum
Enum values:
plan
addon

SubscriptionLineItem

item_id
​string · required

Unique identifier for the line item.

item_type
​string · required

Type of the line item.

description
​string · required

Description of the line item.

amount
​MinorUnit · int64 · required

This Unit struct represents MinorUnit in which core amount works

currency
​Currency · enum · required

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

Enum values:
AED
AFN
ALL
AMD
ANG
AOA
ARS
AUD
quantity
​integer · int64 · required

Quantity of the line item.

SubscriptionResponse

Response payload returned after successfully creating a subscription. Includes details such as subscription ID, status, plan, merchant, and customer info.
id
​SubscriptionId · required

A type for subscription_id that can be used for subscription ids

status
​SubscriptionStatus · enum · required

Possible states of a subscription lifecycle.

  • Created: Subscription was created but not yet activated.
  • Active: Subscription is currently active.
  • InActive: Subscription is inactive.
  • Pending: Subscription is pending activation.
  • Trial: Subscription is in a trial period.
  • Paused: Subscription is paused.
  • Unpaid: Subscription is unpaid.
  • Onetime: Subscription is a one-time payment.
  • Cancelled: Subscription has been cancelled.
  • Failed: Subscription has failed.
Enum values:
active
created
in_active
pending
trial
paused
unpaid
onetime
profile_id
​ProfileId · required

A type for profile_id that can be used for business profile ids

merchant_id
​MerchantId · required

A type for merchant_id that can be used for merchant ids

customer_id
​CustomerId · required

A type for customer_id that can be used for customer ids

merchant_reference_id
​string | null

Merchant specific Unique identifier.

plan_id
​string | null

Identifier for the associated subscription plan.

item_price_id
​string | null

Identifier for the associated item_price_id for the subscription.

client_secret
​string | null

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

coupon_code
​string | null

Optional coupon code applied to this subscription.

​object
​object

SubscriptionStatus

string · enum
Enum values:
active
created
in_active
pending
trial
paused
unpaid
onetime

Possible states of a subscription lifecycle.

  • Created: Subscription was created but not yet activated.
  • Active: Subscription is currently active.
  • InActive: Subscription is inactive.
  • Pending: Subscription is pending activation.
  • Trial: Subscription is in a trial period.
  • Paused: Subscription is paused.
  • Unpaid: Subscription is unpaid.
  • Onetime: Subscription is a one-time payment.
  • Cancelled: Subscription has been cancelled.
  • Failed: Subscription has failed.

SuccessBasedRoutingConfig

​DecisionEngineSuccessRateData · required

Configuration for Decision Engine success rate based routing

​object

SuccessBasedRoutingConfigBody

min_aggregates_size
​integer | null · int32 · min: 0
default_success_rate
​number | null · double
max_aggregates_size
​integer | null · int32 · min: 0
​object
specificity_level
​SuccessRateSpecificityLevel · enum
Enum values:
merchant
global
exploration_percent
​number | null · double
shuffle_on_tie_during_exploitation
​boolean | null

SuccessRateSpecificityLevel

string · enum
Enum values:
merchant
global

SupportedPaymentMethod

payment_method
​PaymentMethod · enum · required

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

Enum values:
card
card_redirect
pay_later
wallet
bank_redirect
bank_transfer
crypto
bank_debit
payment_method_type
​PaymentMethodType · enum · required

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

Enum values:
ach
affirm
afterpay_clearpay
alfamart
ali_pay
ali_pay_hk
alma
amazon_pay
payment_method_type_display_name
​string · required

The display name of the payment method type

mandates
​FeatureStatus · enum · required

The status of the feature

Enum values:
not_supported
supported
refunds
​FeatureStatus · enum · required

The status of the feature

Enum values:
not_supported
supported
supported_capture_methods
​CaptureMethod[] · required

List of supported capture methods supported by the payment method type

Enum values:
automatic
manual
manual_multiple
scheduled
sequential_automatic
supported_countries
​array | null · unique

List of countries supported by the payment method type via the connector

Enum values:
AFG
ALA
ALB
DZA
ASM
AND
AGO
AIA
supported_currencies
​array | null · unique

List of currencies supported by the payment method type via the connector

Enum values:
AED
AFN
ALL
AMD
ANG
AOA
ARS
AUD
oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · requires: three_ds, no_three_ds, supported_card_networks
Properties for Variant 1:
three_ds
​FeatureStatus · enum · required

The status of the feature

Enum values:
not_supported
supported
no_three_ds
​FeatureStatus · enum · required

The status of the feature

Enum values:
not_supported
supported
supported_card_networks
​CardNetwork[] · required

List of supported card networks

Enum values:
Visa
Mastercard
AmericanExpress
JCB
DinersClub
Discover
CartesBancaires
UnionPay

SurchargeDetailsResponse

​SurchargeResponse · required
display_surcharge_amount
​number · double · required

surcharge amount for this payment

display_tax_on_surcharge_amount
​number · double · required

tax on surcharge amount for this payment

display_total_surcharge_amount
​number · double · required

sum of display_surcharge_amount and display_tax_on_surcharge_amount

​object

SurchargePercentage

percentage
​number · float · required

SurchargeResponse

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · type="fixed" · requires: value
type = object · type="rate" · requires: value
Properties for Variant 1:
type
​string · enum · required
Enum values:
fixed
value
​MinorUnit · int64 · required

This Unit struct represents MinorUnit in which core amount works

SwishQrData

TaxStatus

string · enum
Enum values:
taxable
exempt

ThirdPartySdkSessionResponse

​SecretInfoToInitiateSdk · required

ThreeDSDecision

string · enum
Enum values:
no_three_ds
challenge_requested
challenge_preferred
three_ds_exemption_requested_tra
three_ds_exemption_requested_low_value
issuer_three_ds_exemption_requested

Enum representing the possible outcomes of the 3DS Decision Rule Engine.

ThreeDSDecisionRule

Struct representing the output configuration for the 3DS Decision Rule Engine.
decision
​ThreeDSDecision · enum · required

Enum representing the possible outcomes of the 3DS Decision Rule Engine.

Enum values:
no_three_ds
challenge_requested
challenge_preferred
three_ds_exemption_requested_tra
three_ds_exemption_requested_low_value
issuer_three_ds_exemption_requested

ThreeDsCompletionIndicator

string · enum
Enum values:
Y
N
U

Indicates if 3DS method data was successfully completed or not

ThreeDsData

three_ds_server_transaction_id
​string · required

The unique identifier for this authentication from the 3DS server.

maximum_supported_3ds_version
​string · required

The maximum supported 3DS version.

connector_authentication_id
​string · required

The unique identifier for this authentication from the connector.

three_ds_method_data
​string · required

The data required to perform the 3DS method.

three_ds_method_url
​string · required

The URL to which the user should be redirected after authentication.

Example: https://example.com/redirect
message_version
​string · required

The version of the message.

directory_server_id
​string · required

The unique identifier for this authentication.

ThreeDsDecisionRuleExecuteRequest

Represents the request to execute a 3DS decision rule.
routing_id
​string · required

The ID of the routing algorithm to be executed.

​PaymentData · required

Represents the payment data used in the 3DS decision rule.

​object

Represents metadata about the payment method used in the 3DS decision rule.

​object

Represents data about the customer's device used in the 3DS decision rule.

​object

Represents data about the issuer used in the 3DS decision rule.

​object

Represents data about the acquirer used in the 3DS decision rule.

ThreeDsDecisionRuleExecuteResponse

Represents the response from executing a 3DS decision rule.
decision
​ThreeDSDecision · enum · required

Enum representing the possible outcomes of the 3DS Decision Rule Engine.

Enum values:
no_three_ds
challenge_requested
challenge_preferred
three_ds_exemption_requested_tra
three_ds_exemption_requested_low_value
issuer_three_ds_exemption_requested

ThreeDsMethodData

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · requires: three_ds_method_data_submission, consume_post_message_for_three_ds_method_completion
Properties for Variant 1:
three_ds_method_data_submission
​boolean · required

Whether ThreeDS method data submission is required

consume_post_message_for_three_ds_method_completion
​boolean · required

Indicates whether to wait for Post message after 3DS method data submission

three_ds_method_data
​string | null

ThreeDS method data

three_ds_method_url
​string | null

ThreeDS method url

three_ds_method_key
​string · enum
Enum values:
threeDSMethodData
JWT

ThreeDsMethodKey

string · enum
Enum values:
threeDSMethodData
JWT

Threshold

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · requires: count
type = object · requires: amount
Properties for Variant 1:
count
​integer · int64 · required

TimeRange

A type representing a range of time for filtering, including a mandatory start time and an optional end time.
start_time
​string · date-time · required

The start time to filter payments list or to get list of filters. To get list of filters start time is needed to be passed

end_time
​string | null · date-time

The end time to filter payments list or to get list of filters. If not passed the default time is now

TimeWindow

string · enum
Enum values:
hour
day
month
lifetime

ToggleBlocklistQuery

status
​boolean · required
scope
​BlocklistScope · enum

Ownership scope for a blocklist entry (org / merchant / connector MCA).

Enum values:
organization
merchant
connector
merchant_connector_id
​string | null

Required when scope is connector.

ToggleBlocklistResponse

blocklist_guard_status
​string · required
scope
​string · enum

Ownership scope for a blocklist entry (org / merchant / connector MCA).

Enum values:
organization
merchant
connector
merchant_connector_id
​string | null

ToggleDynamicRoutingPath

profile_id
​string · required

ToggleDynamicRoutingQuery

enable
​DynamicRoutingFeatures · enum · required
Enum values:
metrics
dynamic_connector_selection
none

ToggleKVRequest

kv_enabled
​boolean · required

Status of KV for the specific merchant

Example: true

ToggleKVResponse

merchant_id
​string · maxLength: 255 · required

The identifier for the Merchant Account

Example: y3oqhf46pyzuxjbcn2giaqnb44
kv_enabled
​boolean · required

Status of KV for the specific merchant

Example: true

TogglePaymentFieldValidationQuery

status
​boolean · required
scope
​PaymentFieldValidationScope · enum

Ownership scope for payment field validation rules.

Enum values:
organization
merchant
connector
merchant_connector_id
​string | null

TogglePaymentFieldValidationResponse

payment_field_validation_guard_status
​string · required
scope
​string · enum

Ownership scope for payment field validation rules.

Enum values:
organization
merchant
connector
merchant_connector_id
​string | null

ToggleWhitelistQuery

merchant_connector_id
​string · required
status
​boolean · required

ToggleWhitelistResponse

whitelist_guard_status
​string · required

TokenDataType

string · enum
Enum values:
single_use_token
multi_use_token
network_token

The type of token data to fetch for get-token endpoint

TokenSource

string · enum
Enum values:
google_pay
apple_pay

Source of the token

Example: google_pay, apple_pay

Tokenization

string · enum
Enum values:
skip_psp
tokenize_at_psp

The type of tokenization to use for the payment method

TokenizeCardRequest

raw_card_number
​string · required

Card Number

Example: 4111111145551142
card_expiry_month
​string · required

Card Expiry Month

Example: 10
card_expiry_year
​string · required

Card Expiry Year

Example: 25
card_cvc
​string | null

The CVC number for the card

Example: 242
card_holder_name
​string | null

Card Holder Name

Example: John Doe
nick_name
​string | null

Card Holder's Nick Name

Example: John Doe
card_issuing_country
​string | null

Card Issuing Country

card_issuing_country_code
​string | null

Card Issuing Country

card_network
​string · enum

Indicates the card network.

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

Issuer Bank for Card

card_type
​string · enum
Enum values:
credit
debit

TokenizeDataRequest

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · requires: card
type = object · requires: existing_payment_method
Properties for Variant 1:
​TokenizeCardRequest · required

TokenizePaymentMethodRequest

card_cvc
​string | null

The CVC number for the card

Example: 242

TotalEventsResponse

The response body of list initial delivery attempts api call.
​EventListItemResponse[] · required

The list of events

total_count
​integer · int64 · required

Count of total events

TouchNGoRedirection

TransactionCheckDecisionConfigReq

name
​string | null
​array | null

TransactionCheckDecisionManagerRecord

name
​string · required
​TransactionCheckRule[] · required
created_at
​integer · int64 · required
modified_at
​integer · int64 · required

TransactionCheckRule

name
​string · required
​IfStatement[] · required
id
​string | null
enabled
​boolean

TransactionDetailsUiConfiguration

position
​integer | null · int32

Position of the key-value pair in the UI

Example: 5
is_key_bold
​boolean | null

Whether the key should be bold

Example: true
Default: false
is_value_bold
​boolean | null

Whether the value should be bold

Example: true
Default: false

TransactionStatus

string · enum
Enum values:
Y
N
U
A
R
C
D
I

Indicates the transaction status

TransactionType

string · enum
Enum values:
payment
payout
three_ds_authentication

TriggeredBy

string · enum
Enum values:
internal
external

TxnStatus

string · enum
Enum values:
STARTED
AUTHENTICATION_FAILED
JUSPAY_DECLINED
PENDING_VBV
V_B_V_SUCCESSFUL
AUTHORIZED
AUTHORIZATION_FAILED
CHARGED

UIWidgetFormLayout

string · enum
Enum values:
tabs
journey

UnbilledChargesOption

string · enum
Enum values:
invoice
delete

UnifiedCode

string · enum
Enum values:
UE_1000
UE_2000
UE_3000
UE_4000
UE_9000

UnpaidInvoicesHandling

string · enum
Enum values:
no_action
schedule_payment_collection

UpdateApiKeyRequest

The request body for updating an API Key.
name
​string | null · maxLength: 64

A unique name for the API Key to help you identify it.

Example: Sandbox integration key
description
​string | null · maxLength: 256

A description to provide more context about the API Key.

Example: Key used by our developers to integrate with the sandbox environment
​

JSON column value: explicit non-empty grants for the key.

whitelisted_ips
​array | null

When set, replaces the whitelisted IP addresses. Pass an empty list to allow all IPs.

UpdateScorePayload

Request payload to update gateway performance score based on transaction outcome
merchantId
​string · required

Profile ID of the merchant

Example: pro_aMoPnEkgCVnh2WVsFe32
gateway
​string · required

Payment Gateway identifier

Example: stripe:mca1
status
​TxnStatus · enum · required
Enum values:
STARTED
AUTHENTICATION_FAILED
JUSPAY_DECLINED
PENDING_VBV
V_B_V_SUCCESSFUL
AUTHORIZED
AUTHORIZATION_FAILED
CHARGED
paymentId
​string · required

Payment ID associated with the transaction

Example: pay_1234

UpdateScoreResponse

Response after updating gateway score
message
​string · required

Status message indicating the result of the score update

Example: Gateway score updated successfully

UpdateSubscriptionRequest

plan_id
​string · required

Identifier for the associated plan_id.

item_price_id
​string · required

Identifier for the associated item_price_id for the subscription.

UpiAdditionalData

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · requires: upi_collect
type = object · requires: upi_intent
type = object · requires: upi_qr
Properties for Variant 1:
​UpiCollectAdditionalData · required

UpiCollectAdditionalData

vpa_id
​string | null

Masked VPA ID

Example: ab********@okhdfcbank
upi_source
​string · enum

The source type for UPI payments. This indicates what payment source is being used for the UPI transaction.

Enum values:
UPI_CC
UPI_CL
UPI_ACCOUNT
UPI_CC_CL
UPI_PPI
UPI_VOUCHER

UpiCollectData

vpa_id
​string | null

The Virtual Payment Address (VPA) for UPI collect payment

Example: successtest@iata
upi_source
​string · enum

The source type for UPI payments. This indicates what payment source is being used for the UPI transaction.

Enum values:
UPI_CC
UPI_CL
UPI_ACCOUNT
UPI_CC_CL
UPI_PPI
UPI_VOUCHER

UpiData

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · requires: upi_collect
type = object · requires: upi_intent
type = object · requires: upi_qr
Properties for Variant 1:
​UpiCollectData · required

UpiIntentData

upi_source
​string · enum

The source type for UPI payments. This indicates what payment source is being used for the UPI transaction.

Enum values:
UPI_CC
UPI_CL
UPI_ACCOUNT
UPI_CC_CL
UPI_PPI
UPI_VOUCHER
app_name
​string | null

App name for UPI intent payment

UpiQrData

upi_source
​string · enum

The source type for UPI payments. This indicates what payment source is being used for the UPI transaction.

Enum values:
UPI_CC
UPI_CL
UPI_ACCOUNT
UPI_CC_CL
UPI_PPI
UPI_VOUCHER

UpiResponse

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · requires: upi_collect
type = object · requires: upi_intent
type = object · requires: upi_qr
Properties for Variant 1:
​UpiCollectAdditionalData · required

UpiSource

string · enum
Enum values:
UPI_CC
UPI_CL
UPI_ACCOUNT
UPI_CC_CL
UPI_PPI
UPI_VOUCHER

The source type for UPI payments. This indicates what payment source is being used for the UPI transaction.

ValueType

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · type="number" · requires: value
type = object · type="enum_variant" · requires: value
type = object · type="metadata_variant" · requires: value
type = object · type="str_value" · requires: value
type = object · type="str_value_array" · requires: value
type = object · type="global_ref" · requires: value
type = object · type="number_array" · requires: value
type = object · type="enum_variant_array" · requires: value
type = object · type="number_comparison_array" · requires: value
Properties for Variant 1:
type
​string · enum · required
Enum values:
number
value
​integer · int64 · min: 0 · required

Represents a number literal

VaultSdk

string · enum
Enum values:
vgs_sdk
hyperswitch_sdk

VaultTokenField

token_type
​string · enum

Fields that can be tokenized with vault

Enum values:
card_number
card_cvc
card_expiry_year
card_expiry_month
network_token
network_token_expiry_year
network_token_expiry_month
network_token_cryptogram

VaultTokenType

string · enum
Enum values:
card_number
card_cvc
card_expiry_year
card_expiry_month
network_token
network_token_expiry_year
network_token_expiry_month
network_token_cryptogram

Fields that can be tokenized with vault

VelocityAction

string · enum
Enum values:
block
flag
three_ds

VelocityMetric

string · enum
Enum values:
completed_deposits_per_shop
completed_deposits_for_card
declined_deposits_for_card
attempts_for_card
completed_deposits_for_email
declined_deposits_for_email
attempts_for_email
success_for_email

VelocityMockConfig

​MockMode · required
​MockMode · required
​MockMode · required

VelocityRule

metric
​VelocityMetric · enum · required
Enum values:
completed_deposits_per_shop
completed_deposits_for_card
declined_deposits_for_card
attempts_for_card
completed_deposits_for_email
declined_deposits_for_email
attempts_for_email
success_for_email
window
​TimeWindow · enum · required
Enum values:
hour
day
month
lifetime
​Threshold · required
id
​string | null

Stable live-rule id (vr_...). Assigned on profile or MCA ingest. Templates omit this field; copy-and-activate creates a new id.

period_count
​integer · int32 · min: 0

Rule spans period_count * window. Defaults to 1.

action
​VelocityAction · enum
Enum values:
block
flag
three_ds
currency
​string · enum

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

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

Merchant-facing label, surfaced in the VEL_01 message.

is_enabled
​boolean

Operator toggle. A disabled rule is neither evaluated nor recorded.

status
​VelocityRuleStatus · enum
Enum values:
active
draft
archived

VelocityRuleCreate

​VelocityRule · required

VelocityRuleDeleteResponse

id
​string · required
deleted
​boolean · required

VelocityRuleStatus

string · enum
Enum values:
active
draft
archived

VelocityRuleTemplateCreate

name
​string · required
​VelocityRule · required
description
​string | null

VelocityRuleTemplateDeleteResponse

id
​string · required
deleted
​boolean · required

VelocityRuleTemplateResponse

id
​string · required
merchant_id
​string · required
name
​string · required
​VelocityRule · required
created_at
​string · date-time · required
modified_at
​string · date-time · required
description
​string | null

VelocityRuleTemplateUpdate

name
​string | null
description
​string | null
​object

VelocityRuleUpdate

Replaces the complete live rule. Partial rule edits are not supported.
​VelocityRule · required

Venmo

telephone_number
​string · required

mobile number linked to venmo account

Example: 16608213349

VenmoAdditionalData

Masked payout method details for venmo wallet payout method
telephone_number
​string | null

mobile number linked to venmo account

Example: ******* 3349

VisaEligibilityCheckData

consumerPresent
​boolean · required
consumerStatus
​string | null
​object

Browser information to be used for 3DS 2.0

VoucherData

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · requires: boleto
type = string
type = string
type = string
type = string
type = object · requires: alfamart
type = object · requires: indomaret
type = string
type = object · requires: seven_eleven
type = object · requires: lawson
type = object · requires: mini_stop
type = object · requires: family_mart
type = object · requires: seicomart
type = object · requires: pay_easy
Properties for Variant 1:
​BoletoVoucherData · required

VoucherResponse

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · requires: boleto
type = string
type = string
type = string
type = string
type = object · requires: alfamart
type = object · requires: indomaret
type = string
type = object · requires: seven_eleven
type = object · requires: lawson
type = object · requires: mini_stop
type = object · requires: family_mart
type = object · requires: seicomart
type = object · requires: pay_easy
Properties for Variant 1:
​BoletoVoucherData · required

Wallet

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · requires: apple_pay_decrypt
type = object · requires: paypal
type = object · requires: venmo
Properties for Variant 1:
​ApplePayDecrypt · required

WalletAdditionalData

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object
type = object
type = object · requires: card_exp_month, card_exp_year, card_holder_name
Properties for Variant 1:
Masked payout method details for paypal wallet payout method
email
​string | null

Email linked with paypal account

Example: john.doe@example.com
telephone_number
​string | null

mobile number linked to paypal account

Example: ******* 3349
paypal_id
​string | null

id of the paypal account

Example: G83K ***** HCQ2

WalletAdditionalDataForCard

last4
​string · required

Last 4 digits of the card number

card_network
​string · required

The information of the payment method

type
​string | null

The type of payment method

card_exp_month
​string | null

The card's expiry month

Example: 03
card_exp_year
​string | null

The card's expiry year

Example: 25
auth_code
​string | null

Unique authorisation code generated for the payment

Example: 009825

WalletData

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · requires: ali_pay_hk_redirect
type = object · requires: ali_pay_qr
type = object · requires: ali_pay_redirect
type = object · requires: amazon_pay
type = object · requires: amazon_pay_redirect
type = object · requires: apple_pay
type = object · requires: apple_pay_redirect
type = object · requires: apple_pay_third_party_sdk
type = object · requires: bluecode_redirect
type = object · requires: cashapp_qr
type = object · requires: dana_redirect
type = object · requires: gcash_redirect
type = object · requires: go_pay_redirect
type = object · requires: google_pay
type = object · requires: google_pay_redirect
type = object · requires: google_pay_third_party_sdk
type = object · requires: kakao_pay_redirect
type = object · requires: mb_way_redirect
type = object · requires: mifinity
type = object · requires: mobile_pay_redirect
type = object · requires: momo_redirect
type = object · requires: paypal_redirect
type = object · requires: paypal_sdk
type = object · requires: paysera
type = object · requires: paze
type = object · requires: revolut_pay
type = object · requires: samsung_pay
type = object · requires: skrill
type = object · requires: swish_qr
type = object · requires: touch_n_go_redirect
type = object · requires: twint_redirect
type = object · requires: vipps_redirect
type = object · requires: we_chat_pay_qr
type = object · requires: we_chat_pay_redirect
Properties for AliPayHkRedirect:
ali_pay_hk_redirect
​AliPayHkRedirection · required

WalletResponse

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · requires: apple_pay
type = object · requires: google_pay
type = object · requires: samsung_pay
Properties for Variant 1:
​WalletAdditionalDataForCard · required

WalletResponseData

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · requires: apple_pay
type = object · requires: google_pay
type = object · requires: samsung_pay
Properties for Variant 1:
​WalletAdditionalDataForCard · required

WeChatPay

WeChatPayQr

WeChatPayRedirection

WebhookConfigType

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = string
type = object · requires: CustomEvents
Properties for Variant 1:
string · enum
Enum values:
AllEvents

Standard webhook configuration supporting all events hyperswitch provides

WebhookDeliveryAttempt

string · enum
Enum values:
initial_attempt
automatic_retry
manual_retry

WebhookDeliveryAttemptDetail

One webhook delivery attempt record, merging data from two sources: - **Postgres `events` table** (always present): retry sequencing, the full encrypted request/response payloads, and delivery outcome flags. - **ClickHouse `outgoing_webhook_events_audit`** (present when the analytics pipeline is active): HTTP status code returned by the merchant endpoint, `is_error` flag, and the raw error string if delivery failed. Multiple records may share the same `initial_attempt_id`.
event_id
​string · required
event_type
​EventType · enum · required
Enum values:
payment_succeeded
payment_failed
payment_processing
payment_cancelled
payment_cancelled_post_capture
payment_authorized
payment_partially_authorized
payment_captured
is_webhook_notified
​boolean · required

Whether the webhook endpoint acknowledged this attempt successfully.

created_at
​string · required

Timestamp when this delivery attempt was created/dispatched.

Example: 2024-01-01T00:00:00Z
initial_attempt_id
​string | null
delivery_attempt
​string · enum
Enum values:
initial_attempt
automatic_retry
manual_retry
is_overall_delivery_successful
​boolean | null
request
​string | null

The raw request payload that was sent to the merchant's endpoint.

response
​string | null

The raw response payload received from the merchant's endpoint, if any.

status_code
​integer | null · int32 · min: 0

Clickhouse-sourced HTTP status code returned by the merchant's endpoint, if any.

is_error
​boolean | null

Clickhouse-sourced Whether the delivery resulted in an error at the HTTP transport level.

error
​string | null

Clickhouse-sourced Human-readable error string from the analytics pipeline, if any.

WebhookDetails

payment_statuses_enabled
​IntentStatus[] · required

List of payment statuses that triggers a webhook for payment intents

Enum values:
succeeded
failed
cancelled
cancelled_post_capture
processing
requires_customer_action
requires_merchant_action
requires_payment_method
Example: ["succeeded","failed","partially_captured","requires_merchant_action"]
refund_statuses_enabled
​IntentStatus[] · required

List of refund statuses that triggers a webhook for refunds

Enum values:
succeeded
failed
cancelled
cancelled_post_capture
processing
requires_customer_action
requires_merchant_action
requires_payment_method
Example: ["success","failure"]
webhook_version
​string | null · maxLength: 255

The version for Webhook

Example: 1.0.2
webhook_username
​string | null · maxLength: 255

The user name for Webhook login

Example: ekart_retail
webhook_password
​string | null · maxLength: 255

The password for Webhook login

Example: ekart@123
webhook_url
​string | null

The url for the webhook endpoint

Example: www.ekart.com/webhooks
payment_created_enabled
​boolean | null

If this property is true, a webhook message is posted whenever a new payment is created

Example: true
payment_succeeded_enabled
​boolean | null

If this property is true, a webhook message is posted whenever a payment is successful

Example: true
payment_failed_enabled
​boolean | null

If this property is true, a webhook message is posted whenever a payment fails

Example: true
payout_statuses_enabled
​array | null

List of payout statuses that triggers a webhook for payouts

Enum values:
success
failed
cancelled
initiated
expired
reversed
pending
ineligible
Example: ["success","failed"]
webhook_endpoint_status
​string · enum
Enum values:
active
inactive
deprecated

WebhookRegistrationStatus

string · enum
Enum values:
Success
Failure

The status of webhook registration

WebhookSetupCapabilities

Connector details for webhook configuration via hyperswitch API
is_webhook_auto_configuration_supported
​boolean · required

Indicates if the connector supports webhooks configuration via API

requires_webhook_secret
​boolean | null

Indicates whether a webhook secret must be collected from the merchant for verification

​

Enum to represent the type of webhook configuration

WhitelistMcaQuery

merchant_connector_id
​string · required

WhitelistRequest

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · type="card_bin" · requires: data
type = object · type="fingerprint" · requires: data
type = object · type="extended_card_bin" · requires: data
type = object · type="email" · requires: data
type = object · type="card_number" · requires: data
type = object · type="card_pan_masked" · requires: data
type = object · type="phone" · requires: data
Properties for Variant 1:
type
​string · enum · required
Enum values:
card_bin
data
​string · required

WhitelistResponse

fingerprint_id
​string · required
data_kind
​BlocklistDataKind · enum · required
Enum values:
payment_method
card_bin
extended_card_bin
email
card_number
card_pan_masked
phone
merchant_connector_id
​string · required
created_at
​string · date-time · required
added_by
​string | null
description
​string | null
card_pan_bin
​string | null
card_pan_suffix
​string | null

XenditChargeResponseData

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · requires: multiple_splits
type = object · requires: single_split
Properties for Variant 1:
​XenditMultipleSplitResponse · required

Fee information charged on the payment being collected via xendit

XenditMultipleSplitRequest

Fee information to be charged on the payment being collected via xendit
name
​string · required

Name to identify split rule. Not required to be unique. Typically based on transaction and/or sub-merchant types.

description
​string · required

Description to identify fee rule

​XenditSplitRoute[] · required

Array of objects that define how the platform wants to route the fees and to which accounts.

for_user_id
​string | null

The sub-account user-id that you want to make this transaction for.

XenditMultipleSplitResponse

Fee information charged on the payment being collected via xendit
split_rule_id
​string · required

Identifier for split rule created for the payment

name
​string · required

Name to identify split rule. Not required to be unique. Typically based on transaction and/or sub-merchant types.

description
​string · required

Description to identify fee rule

​XenditSplitRoute[] · required

Array of objects that define how the platform wants to route the fees and to which accounts.

for_user_id
​string | null

The sub-account user-id that you want to make this transaction for.

XenditSplitRequest

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · requires: multiple_splits
type = object · requires: single_split
Properties for Variant 1:
​XenditMultipleSplitRequest · required

Fee information to be charged on the payment being collected via xendit

XenditSplitRoute

Fee information to be charged on the payment being collected via xendit
currency
​Currency · enum · required

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

Enum values:
AED
AFN
ALL
AMD
ANG
AOA
ARS
AUD
destination_account_id
​string · required

ID of the destination account where the amount will be routed to

reference_id
​string · required

Reference ID which acts as an identifier of the route itself

flat_amount
​integer · int64

This Unit struct represents MinorUnit in which core amount works

percent_amount
​integer | null · int64

Amount of payments to be split, using a percent rate as unit

XenditSplitSubMerchantData

Fee information to be charged on the payment being collected for sub-merchant via xendit
for_user_id
​string · required

The sub-account user-id that you want to make this transaction for.