Payments

Create and manage one-time payments, recurring payments and mandates

Payments - Create

POST

https://paysw-wiki.lab.next-on.pro/dev-router

/payments

api-key (header)

Creates a payment resource, which represents a customer's intent to pay. This endpoint is the starting point for various payment flows:

Payments - Create › Request Body

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:

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

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

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:

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.

Payments - Create › Responses

Payment created

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

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

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.

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:

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

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

POST/payments

curl https://paysw-wiki.lab.next-on.pro/dev-router/payments \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'api-key: <api-key>' \
  --data '{
  "amount": 6540,
  "currency": "USD"
}'

Example Request Body

{
  "amount": 6540,
  "currency": "USD"
}

json

application/json

Example Responses

{
  "amount": 6540,
  "amount_capturable": 6540,
  "attempt_count": 1,
  "client_secret": "pay_syxxxxxxxxxxxx_secret_szzzzzzzzzzz",
  "created": "2023-10-26T10:00:00Z",
  "currency": "USD",
  "expires_on": "2023-10-26T10:15:00Z",
  "merchant_id": "merchant_myyyyyyyyyyyy",
  "payment_id": "pay_syxxxxxxxxxxxx",
  "profile_id": "pro_pzzzzzzzzzzz",
  "status": "requires_payment_method"
}

json

application/json

Payments - Retrieve

GET

https://paysw-wiki.lab.next-on.pro/dev-router

/payments/{payment_id}

api-key (header)

Retrieves a Payment. This API can also be used to get the status of a previously initiated payment or next action for an ongoing payment

Payments - Retrieve › path Parameters

payment_id

string · required

The identifier for payment

Payments - Retrieve › query Parameters

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_attempts

boolean | null

If enabled provides list of attempts linked to payment intent

expand_captures

boolean | null

If enabled provides list of captures linked to latest attempt

expand_customer_statistics

boolean | null

When true, includes customer statistics for the payment profile (OLAP)

Payments - Retrieve › Responses

Gets the payment with final status

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

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

Example: 6540

amount_capturable

integer · int64 · min: 100 · required

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

Example: 6540

initiator

string · enum

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

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

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

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.

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

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:

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

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

network_transaction_id

string | null

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

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

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

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

GET/payments/{payment_id}

curl https://paysw-wiki.lab.next-on.pro/dev-router/payments/:payment_id \
  --header 'api-key: <api-key>'

Example Responses

{
  "payment_id": "pay_mbabizu24mvu3mela5njyhpit4",
  "merchant_id": "merchant_1668273825",
  "status": "requires_confirmation",
  "amount": 6540,
  "net_amount": 6540,
  "shipping_cost": 6540,
  "amount_capturable": 6540,
  "amount_received": 6540,
  "processor_merchant_id": "merchant_1689512302",
  "initiator": "platform",
  "sdk_authorization": "cHJvZmlsZV9pZD1wcm9mXzEyMyxwdWJsaXNoYWJsZV9rZXk9cGtfbGl2ZV8xMjM=",
  "connector": "stripe",
  "state_metadata": {
    "total_refunded_amount": 0,
    "total_disputed_amount": 0,
    "post_capture_void": {
      "status": "succeeded",
      "connector_reference_id": "connector_reference_id",
      "description": "description",
      "updated_at": "2024-08-25T15:00:00Z"
    }
  },
  "client_secret": "pay_U42c409qyHwOkWo3vK60_secret_el9ksDkiB8hi6j9N78yo",
  "created": "2022-09-10T10:11:12Z",
  "modified_at": "2022-09-10T10:11:12Z",
  "currency": "AED",
  "customer_id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
  "customer": {
    "id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
    "name": "John Doe",
    "email": "johntest@test.com",
    "phone": "9123456789",
    "phone_country_code": "+1",
    "customer_document_details": {
      "document_type": "cpf",
      "document_number": "12345678911"
    }
  },
  "description": "It's my first payment request",
  "refunds": [
    {
      "refund_id": "refund_id",
      "payment_id": "payment_id",
      "amount": 6540,
      "currency": "currency",
      "status": "succeeded",
      "reason": "reason",
      "metadata": {},
      "error_message": "error_message",
      "error_code": "error_code",
      "unified_code": "unified_code",
      "unified_message": "unified_message",
      "created_at": "2024-08-25T15:00:00Z",
      "updated_at": "2024-08-25T15:00:00Z",
      "connector": "stripe",
      "profile_id": "profile_id",
      "merchant_connector_id": "merchant_connector_id",
      "split_refunds": {
        "stripe_split_refund": {
          "revert_platform_fee": true,
          "revert_transfer": true
        }
      },
      "issuer_error_code": "issuer_error_code",
      "issuer_error_message": "issuer_error_message",
      "raw_connector_response": "raw_connector_response",
      "connector_refund_id": "connector_refund_id",
      "fee_summary": {
        "currency": "currency",
        "base_amount": 0,
        "merchant_commission_amount": 0,
        "provider_cost": 0,
        "margin": 0,
        "merchant_commission_rate": {},
        "provider_cost_rate": {},
        "merchant_commission_rule": "merchant_commission_rule",
        "provider_cost_rule": "provider_cost_rule"
      }
    }
  ],
  "disputes": [
    {
      "dispute_id": "dispute_id",
      "amount": "amount",
      "dispute_stage": "pre_dispute",
      "dispute_status": "dispute_opened",
      "connector_status": "connector_status",
      "connector_dispute_id": "connector_dispute_id",
      "connector_reason": "connector_reason",
      "connector_reason_code": "connector_reason_code",
      "challenge_required_by": "2024-08-25T15:00:00Z",
      "connector_created_at": "2024-08-25T15:00:00Z",
      "connector_updated_at": "2024-08-25T15:00:00Z",
      "created_at": "2024-08-25T15:00:00Z"
    }
  ],
  "attempts": [
    {
      "attempt_id": "attempt_id",
      "status": "started",
      "amount": 6540,
      "order_tax_amount": 6540,
      "currency": "AED",
      "connector": "connector",
      "merchant_connector_id": "merchant_connector_id",
      "error_message": "error_message",
      "payment_method": "card",
      "connector_transaction_id": "connector_transaction_id",
      "capture_method": "automatic",
      "authentication_type": "three_ds",
      "created_at": "2022-09-10T10:11:12Z",
      "modified_at": "2022-09-10T10:11:12Z",
      "cancellation_reason": "cancellation_reason",
      "mandate_id": "mandate_id",
      "error_code": "error_code",
      "payment_token": "payment_token",
      "connector_metadata": {},
      "payment_experience": "redirect_to_url",
      "payment_method_type": "ach",
      "reference_id": "993672945374576J",
      "unified_code": "unified_code",
      "unified_message": "unified_message",
      "client_source": "client_source",
      "client_version": "client_version",
      "error_details": {
        "unified_details": {
          "category": "UE_1000",
          "message": "message",
          "standardised_code": "account_closed_or_invalid",
          "description": "description",
          "user_guidance_message": "user_guidance_message",
          "recommended_action": "do_not_retry"
        },
        "issuer_details": {
          "code": "code",
          "message": "message",
          "network_details": {
            "name": "Visa",
            "advice_code": "advice_code",
            "advice_message": "advice_message"
          }
        },
        "connector_details": {
          "code": "code",
          "message": "message",
          "reason": "reason"
        }
      },
      "fee_details": [
        {
          "capture_id": "capture_id",
          "reference_id": "reference_id",
          "created_at": "2024-01-01T00:00:00Z",
          "currency": "currency",
          "base_amount": 0,
          "merchant_commission_amount": 0,
          "provider_cost": 0,
          "margin": 0,
          "merchant_commission_rate": {},
          "provider_cost_rate": {},
          "merchant_commission_rule": "merchant_commission_rule",
          "provider_cost_rule": "provider_cost_rule"
        }
      ]
    }
  ],
  "captures": [
    {
      "capture_id": "capture_id",
      "status": "started",
      "amount": 6540,
      "currency": "AED",
      "connector": "connector",
      "authorized_attempt_id": "authorized_attempt_id",
      "connector_capture_id": "connector_capture_id",
      "capture_sequence": 0,
      "error_message": "error_message",
      "error_code": "error_code",
      "error_reason": "error_reason",
      "reference_id": "reference_id"
    }
  ],
  "mandate_id": "mandate_iwer89rnjef349dni3",
  "mandate_data": {
    "update_mandate_id": "update_mandate_id",
    "customer_acceptance": {
      "acceptance_type": "online",
      "accepted_at": "2022-09-10T10:11:12Z",
      "online": {
        "ip_address": "123.32.25.123",
        "user_agent": "user_agent"
      }
    },
    "mandate_type": {
      "single_use": {
        "amount": 6540,
        "currency": "AED",
        "start_date": "2022-09-10T00:00:00Z",
        "end_date": "2023-09-10T23:59:59Z",
        "metadata": {}
      }
    }
  },
  "setup_future_usage": "off_session",
  "off_session": true,
  "capture_on": "2022-09-10T10:11:12Z",
  "capture_method": "automatic",
  "payment_method": "card",
  "payment_method_data": {
    "billing": {
      "address": {
        "city": "New York",
        "country": "AF",
        "line1": "123, King Street",
        "line2": "Powelson Avenue",
        "line3": "Bridgewater",
        "zip": "08807",
        "state": "New York",
        "first_name": "John",
        "last_name": "Doe",
        "origin_zip": "08807"
      },
      "phone": {
        "number": "9123456789",
        "country_code": "+1"
      },
      "email": "email"
    }
  },
  "payment_token": "187282ab-40ef-47a9-9206-5099ba31e432",
  "shipping": {
    "address": {
      "city": "New York",
      "country": "AF",
      "line1": "123, King Street",
      "line2": "Powelson Avenue",
      "line3": "Bridgewater",
      "zip": "08807",
      "state": "New York",
      "first_name": "John",
      "last_name": "Doe",
      "origin_zip": "08807"
    },
    "phone": {
      "number": "9123456789",
      "country_code": "+1"
    },
    "email": "email"
  },
  "billing": {
    "address": {
      "city": "New York",
      "country": "AF",
      "line1": "123, King Street",
      "line2": "Powelson Avenue",
      "line3": "Bridgewater",
      "zip": "08807",
      "state": "New York",
      "first_name": "John",
      "last_name": "Doe",
      "origin_zip": "08807"
    },
    "phone": {
      "number": "9123456789",
      "country_code": "+1"
    },
    "email": "email"
  },
  "order_details": "[{\n        \"product_name\": \"gillete creme\",\n        \"quantity\": 15,\n        \"amount\" : 900\n    }]",
  "email": "johntest@test.com",
  "name": "John Test",
  "phone": "9123456789",
  "return_url": "https://hyperswitch.io",
  "authentication_type": "three_ds",
  "statement_descriptor_name": "Hyperswitch Router",
  "statement_descriptor_suffix": "Payment for shoes purchase",
  "next_action": {
    "redirect_to_url": "redirect_to_url",
    "type": "redirect_to_url"
  },
  "cancellation_reason": "cancellation_reason",
  "error_code": "E0001",
  "error_message": "Failed while verifying the card",
  "unified_code": "unified_code",
  "unified_message": "unified_message",
  "error_details": {
    "unified_details": {
      "category": "UE_1000",
      "message": "message",
      "standardised_code": "account_closed_or_invalid",
      "description": "description",
      "user_guidance_message": "user_guidance_message",
      "recommended_action": "do_not_retry"
    },
    "issuer_details": {
      "code": "code",
      "message": "message",
      "network_details": {
        "name": "Visa",
        "advice_code": "advice_code",
        "advice_message": "advice_message"
      }
    },
    "connector_details": {
      "code": "code",
      "message": "message",
      "reason": "reason"
    }
  },
  "payment_experience": "redirect_to_url",
  "payment_method_type": "ach",
  "connector_label": "stripe_US_food",
  "business_country": "AF",
  "business_label": "business_label",
  "business_sub_label": "business_sub_label",
  "allowed_payment_method_types": [
    "ach"
  ],
  "manual_retry_allowed": true,
  "connector_transaction_id": "993672945374576J",
  "frm_message": {
    "frm_name": "frm_name",
    "frm_transaction_id": "frm_transaction_id",
    "frm_transaction_type": "frm_transaction_type",
    "frm_status": "frm_status",
    "frm_score": 0,
    "frm_reason": {},
    "frm_error": "frm_error"
  },
  "metadata": {},
  "connector_metadata": {
    "apple_pay": {
      "session_token_data": {
        "certificate": "certificate",
        "certificate_keys": "certificate_keys",
        "merchant_identifier": "merchant_identifier",
        "display_name": "display_name",
        "initiative": "web",
        "initiative_context": "initiative_context",
        "merchant_business_country": "AF"
      }
    },
    "airwallex": {
      "payload": "payload"
    },
    "noon": {
      "order_category": "order_category"
    },
    "braintree": {
      "merchant_account_id": "merchant_account_id",
      "merchant_config_currency": "merchant_config_currency"
    },
    "adyen": {
      "testing": {
        "holder_name": "holder_name"
      }
    },
    "peachpayments": {
      "rrn": "rrn"
    }
  },
  "connector_response_metadata": {
    "santander": {
      "end_to_end_id": "end_to_end_id"
    }
  },
  "feature_metadata": {
    "redirect_response": {
      "param": "param",
      "json_payload": {}
    },
    "search_tags": [
      "string"
    ],
    "apple_pay_recurring_details": {
      "payment_description": "payment_description",
      "regular_billing": {
        "label": "label",
        "recurring_payment_start_date": "2023-09-10T23:59:59Z",
        "recurring_payment_end_date": "2023-09-10T23:59:59Z",
        "recurring_payment_interval_unit": "year",
        "recurring_payment_interval_count": 0
      },
      "billing_agreement": "billing_agreement",
      "management_url": "https://hyperswitch.io"
    },
    "pix_additional_details": {
      "immediate": {
        "time": 0,
        "pix_key": {
          "type": "cpf",
          "value": "value"
        }
      }
    },
    "boleto_additional_details": {
      "due_date": "2026-12-31",
      "document_kind": "commercial_invoice",
      "payment_type": "fixed_amount",
      "covenant_code": "3568253",
      "pix_key": {
        "type": "cpf",
        "value": "value"
      }
    }
  },
  "reference_id": "993672945374576J",
  "payment_link": {
    "link": "link",
    "secure_link": "secure_link",
    "payment_link_id": "payment_link_id"
  },
  "profile_id": "profile_id",
  "surcharge_details": {
    "surcharge_amount": 6540,
    "tax_amount": 0
  },
  "attempt_count": 0,
  "merchant_decision": "merchant_decision",
  "merchant_connector_id": "merchant_connector_id",
  "incremental_authorization_allowed": true,
  "authorization_count": 0,
  "incremental_authorizations": [
    {
      "authorization_id": "authorization_id",
      "amount": 6540,
      "status": "success",
      "error_code": "error_code",
      "error_message": "error_message",
      "previously_authorized_amount": 0
    }
  ],
  "external_authentication_details": {
    "authentication_flow": "challenge",
    "electronic_commerce_indicator": "electronic_commerce_indicator",
    "status": "started",
    "ds_transaction_id": "ds_transaction_id",
    "version": "version",
    "error_code": "error_code",
    "error_message": "error_message"
  },
  "external_3ds_authentication_attempted": true,
  "expires_on": "2022-09-10T10:11:12Z",
  "fingerprint": "fingerprint",
  "browser_info": {
    "color_depth": 0,
    "java_enabled": true,
    "java_script_enabled": true,
    "language": "language",
    "screen_height": 0,
    "screen_width": 0,
    "time_zone": 0,
    "ip_address": "ip_address",
    "accept_header": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8",
    "user_agent": "user_agent",
    "os_type": "os_type",
    "os_version": "os_version",
    "device_model": "device_model",
    "accept_language": "accept_language",
    "referer": "referer"
  },
  "payment_channel": "ecommerce",
  "payment_method_id": "payment_method_id",
  "network_transaction_id": "network_transaction_id",
  "payment_method_status": "active",
  "updated": "2022-09-10T10:11:12Z",
  "split_payments": {
    "stripe_split_payment": {
      "charge_id": "charge_id",
      "charge_type": {
        "Stripe": "direct"
      },
      "application_fees": 6540,
      "transfer_account_id": "transfer_account_id"
    }
  },
  "frm_metadata": {},
  "extended_authorization_applied": true,
  "extended_authorization_last_applied_at": "2022-09-10T10:11:12Z",
  "request_extended_authorization": false,
  "capture_before": "2024-08-25T15:00:00Z",
  "merchant_order_reference_id": "Custom_Order_id_123",
  "order_tax_amount": 0,
  "connector_mandate_id": "connector_mandate_id",
  "card_discovery": "manual",
  "force_3ds_challenge": true,
  "force_3ds_challenge_trigger": true,
  "issuer_error_code": "issuer_error_code",
  "issuer_error_message": "issuer_error_message",
  "is_iframe_redirection_enabled": true,
  "whole_connector_response": "whole_connector_response",
  "enable_partial_authorization": false,
  "enable_overcapture": true,
  "is_overcapture_enabled": true,
  "network_details": {
    "network_advice_code": "network_advice_code"
  },
  "is_stored_credential": true,
  "mit_category": "installment",
  "billing_descriptor": {
    "name": "The Online Retailer",
    "city": "San Francisco",
    "phone": "9123456789",
    "statement_descriptor": "statement_descriptor",
    "statement_descriptor_suffix": "statement_descriptor_suffix",
    "reference": "reference"
  },
  "tokenization": "skip_psp",
  "partner_merchant_identifier_details": {
    "partner_details": {
      "name": "name",
      "version": "1.0.0",
      "integrator": "integrator"
    },
    "merchant_details": {
      "name": "name",
      "version": "version"
    }
  },
  "payment_method_tokenization_details": {
    "payment_method_id": "payment_method_id",
    "payment_method_status": "active",
    "psp_tokenization": true,
    "network_tokenization": true,
    "network_transaction_id": "network_transaction_id",
    "is_eligible_for_mit_payment": true
  },
  "installment_options": [
    {
      "payment_method": "card",
      "installments": [
        {
          "number_of_installments": "number_of_installments",
          "billing_frequency": "month",
          "interest_rate": 0
        }
      ]
    }
  ],
  "installment_data": {
    "number_of_installments": 0,
    "billing_frequency": "month",
    "installment_interest": 0
  },
  "customer_statistics": {
    "profile_id": "profile_id",
    "profile_name": "profile_name",
    "first_successful_payment_at": "first_successful_payment_at",
    "payments_count": 0,
    "payments_amount": 0,
    "refunds_count": 0,
    "refunds_amount": 0,
    "payouts_count": 0,
    "payouts_amount": 0,
    "currency": "AED"
  },
  "fee_summary": {
    "currency": "currency",
    "base_amount": 0,
    "merchant_commission_amount": 0,
    "provider_cost": 0,
    "margin": 0,
    "merchant_commission_rate": {},
    "provider_cost_rate": {},
    "merchant_commission_rule": "merchant_commission_rule",
    "provider_cost_rule": "provider_cost_rule"
  }
}

json

application/json

Payments - Update

POST

https://paysw-wiki.lab.next-on.pro/dev-router

/payments/{payment_id}

api-key (header)

To update the properties of a PaymentIntent object. This may include attaching a payment method, or attaching customer object or metadata fields after the Payment is created

Payments - Update › path Parameters

payment_id

string · required

The identifier for payment

Payments - Update › Request Body

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

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

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.

Enum values:

three_ds

no_three_ds

Default: three_ds

object

confirm

boolean | null

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

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

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

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

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

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:

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

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.

Payments - Update › Responses

Payment updated

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

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

Example: 6540

amount_capturable

integer · int64 · min: 100 · required

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

Example: 6540

initiator

string · enum

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

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

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

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.

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

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:

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

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

network_transaction_id

string | null

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

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

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

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

POST/payments/{payment_id}

curl https://paysw-wiki.lab.next-on.pro/dev-router/payments/:payment_id \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'api-key: <api-key>' \
  --data '{
  "amount": 7654
}'

Example Request Body

{
  "amount": 7654
}

json

application/json

Example Responses

{
  "payment_id": "pay_mbabizu24mvu3mela5njyhpit4",
  "merchant_id": "merchant_1668273825",
  "status": "requires_confirmation",
  "amount": 6540,
  "net_amount": 6540,
  "shipping_cost": 6540,
  "amount_capturable": 6540,
  "amount_received": 6540,
  "processor_merchant_id": "merchant_1689512302",
  "initiator": "platform",
  "sdk_authorization": "cHJvZmlsZV9pZD1wcm9mXzEyMyxwdWJsaXNoYWJsZV9rZXk9cGtfbGl2ZV8xMjM=",
  "connector": "stripe",
  "state_metadata": {
    "total_refunded_amount": 0,
    "total_disputed_amount": 0,
    "post_capture_void": {
      "status": "succeeded",
      "connector_reference_id": "connector_reference_id",
      "description": "description",
      "updated_at": "2024-08-25T15:00:00Z"
    }
  },
  "client_secret": "pay_U42c409qyHwOkWo3vK60_secret_el9ksDkiB8hi6j9N78yo",
  "created": "2022-09-10T10:11:12Z",
  "modified_at": "2022-09-10T10:11:12Z",
  "currency": "AED",
  "customer_id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
  "description": "It's my first payment request",
  "refunds": [
    {
      "refund_id": "refund_id",
      "payment_id": "payment_id",
      "amount": 6540,
      "currency": "currency",
      "status": "succeeded",
      "reason": "reason",
      "metadata": {},
      "error_message": "error_message",
      "error_code": "error_code",
      "unified_code": "unified_code",
      "unified_message": "unified_message",
      "created_at": "2024-08-25T15:00:00Z",
      "updated_at": "2024-08-25T15:00:00Z",
      "connector": "stripe",
      "profile_id": "profile_id",
      "merchant_connector_id": "merchant_connector_id",
      "split_refunds": {
        "stripe_split_refund": {
          "revert_platform_fee": true,
          "revert_transfer": true
        }
      },
      "issuer_error_code": "issuer_error_code",
      "issuer_error_message": "issuer_error_message",
      "raw_connector_response": "raw_connector_response",
      "connector_refund_id": "connector_refund_id",
      "fee_summary": {
        "currency": "currency",
        "base_amount": 0,
        "merchant_commission_amount": 0,
        "provider_cost": 0,
        "margin": 0,
        "merchant_commission_rate": {},
        "provider_cost_rate": {},
        "merchant_commission_rule": "merchant_commission_rule",
        "provider_cost_rule": "provider_cost_rule"
      }
    }
  ],
  "disputes": [
    {
      "dispute_id": "dispute_id",
      "amount": "amount",
      "dispute_stage": "pre_dispute",
      "dispute_status": "dispute_opened",
      "connector_status": "connector_status",
      "connector_dispute_id": "connector_dispute_id",
      "connector_reason": "connector_reason",
      "connector_reason_code": "connector_reason_code",
      "challenge_required_by": "2024-08-25T15:00:00Z",
      "connector_created_at": "2024-08-25T15:00:00Z",
      "connector_updated_at": "2024-08-25T15:00:00Z",
      "created_at": "2024-08-25T15:00:00Z"
    }
  ],
  "attempts": [
    {
      "attempt_id": "attempt_id",
      "status": "started",
      "amount": 6540,
      "order_tax_amount": 6540,
      "currency": "AED",
      "connector": "connector",
      "merchant_connector_id": "merchant_connector_id",
      "error_message": "error_message",
      "payment_method": "card",
      "connector_transaction_id": "connector_transaction_id",
      "capture_method": "automatic",
      "authentication_type": "three_ds",
      "created_at": "2022-09-10T10:11:12Z",
      "modified_at": "2022-09-10T10:11:12Z",
      "cancellation_reason": "cancellation_reason",
      "mandate_id": "mandate_id",
      "error_code": "error_code",
      "payment_token": "payment_token",
      "connector_metadata": {},
      "payment_experience": "redirect_to_url",
      "payment_method_type": "ach",
      "reference_id": "993672945374576J",
      "unified_code": "unified_code",
      "unified_message": "unified_message",
      "client_source": "client_source",
      "client_version": "client_version",
      "error_details": {
        "unified_details": {
          "category": "UE_1000",
          "message": "message",
          "standardised_code": "account_closed_or_invalid",
          "description": "description",
          "user_guidance_message": "user_guidance_message",
          "recommended_action": "do_not_retry"
        },
        "issuer_details": {
          "code": "code",
          "message": "message",
          "network_details": {
            "name": "Visa",
            "advice_code": "advice_code",
            "advice_message": "advice_message"
          }
        },
        "connector_details": {
          "code": "code",
          "message": "message",
          "reason": "reason"
        }
      },
      "fee_details": [
        {
          "capture_id": "capture_id",
          "reference_id": "reference_id",
          "created_at": "2024-01-01T00:00:00Z",
          "currency": "currency",
          "base_amount": 0,
          "merchant_commission_amount": 0,
          "provider_cost": 0,
          "margin": 0,
          "merchant_commission_rate": {},
          "provider_cost_rate": {},
          "merchant_commission_rule": "merchant_commission_rule",
          "provider_cost_rule": "provider_cost_rule"
        }
      ]
    }
  ],
  "captures": [
    {
      "capture_id": "capture_id",
      "status": "started",
      "amount": 6540,
      "currency": "AED",
      "connector": "connector",
      "authorized_attempt_id": "authorized_attempt_id",
      "connector_capture_id": "connector_capture_id",
      "capture_sequence": 0,
      "error_message": "error_message",
      "error_code": "error_code",
      "error_reason": "error_reason",
      "reference_id": "reference_id"
    }
  ],
  "mandate_id": "mandate_iwer89rnjef349dni3",
  "mandate_data": {
    "update_mandate_id": "update_mandate_id",
    "customer_acceptance": {
      "acceptance_type": "online",
      "accepted_at": "2022-09-10T10:11:12Z",
      "online": {
        "ip_address": "123.32.25.123",
        "user_agent": "user_agent"
      }
    },
    "mandate_type": {
      "single_use": {
        "amount": 6540,
        "currency": "AED",
        "start_date": "2022-09-10T00:00:00Z",
        "end_date": "2023-09-10T23:59:59Z",
        "metadata": {}
      }
    }
  },
  "setup_future_usage": "off_session",
  "off_session": true,
  "capture_method": "automatic",
  "payment_method": "card",
  "payment_method_data": {
    "billing": {
      "address": {
        "city": "New York",
        "country": "AF",
        "line1": "123, King Street",
        "line2": "Powelson Avenue",
        "line3": "Bridgewater",
        "zip": "08807",
        "state": "New York",
        "first_name": "John",
        "last_name": "Doe",
        "origin_zip": "08807"
      },
      "phone": {
        "number": "9123456789",
        "country_code": "+1"
      },
      "email": "email"
    }
  },
  "payment_token": "187282ab-40ef-47a9-9206-5099ba31e432",
  "shipping": {
    "address": {
      "city": "New York",
      "country": "AF",
      "line1": "123, King Street",
      "line2": "Powelson Avenue",
      "line3": "Bridgewater",
      "zip": "08807",
      "state": "New York",
      "first_name": "John",
      "last_name": "Doe",
      "origin_zip": "08807"
    },
    "phone": {
      "number": "9123456789",
      "country_code": "+1"
    },
    "email": "email"
  },
  "billing": {
    "address": {
      "city": "New York",
      "country": "AF",
      "line1": "123, King Street",
      "line2": "Powelson Avenue",
      "line3": "Bridgewater",
      "zip": "08807",
      "state": "New York",
      "first_name": "John",
      "last_name": "Doe",
      "origin_zip": "08807"
    },
    "phone": {
      "number": "9123456789",
      "country_code": "+1"
    },
    "email": "email"
  },
  "order_details": "[{\n        \"product_name\": \"gillete creme\",\n        \"quantity\": 15,\n        \"amount\" : 900\n    }]",
  "email": "johntest@test.com",
  "name": "John Test",
  "phone": "9123456789",
  "return_url": "https://hyperswitch.io",
  "authentication_type": "three_ds",
  "statement_descriptor_name": "Hyperswitch Router",
  "statement_descriptor_suffix": "Payment for shoes purchase",
  "next_action": {
    "redirect_to_url": "redirect_to_url",
    "type": "redirect_to_url"
  },
  "cancellation_reason": "cancellation_reason",
  "error_code": "E0001",
  "error_message": "Failed while verifying the card",
  "error_details": {
    "unified_details": {
      "category": "UE_1000",
      "message": "message",
      "standardised_code": "account_closed_or_invalid",
      "description": "description",
      "user_guidance_message": "user_guidance_message",
      "recommended_action": "do_not_retry"
    },
    "issuer_details": {
      "code": "code",
      "message": "message",
      "network_details": {
        "name": "Visa",
        "advice_code": "advice_code",
        "advice_message": "advice_message"
      }
    },
    "connector_details": {
      "code": "code",
      "message": "message",
      "reason": "reason"
    }
  },
  "payment_experience": "redirect_to_url",
  "payment_method_type": "ach",
  "connector_label": "stripe_US_food",
  "business_country": "AF",
  "business_label": "business_label",
  "business_sub_label": "business_sub_label",
  "allowed_payment_method_types": [
    "ach"
  ],
  "manual_retry_allowed": true,
  "connector_transaction_id": "993672945374576J",
  "frm_message": {
    "frm_name": "frm_name",
    "frm_transaction_id": "frm_transaction_id",
    "frm_transaction_type": "frm_transaction_type",
    "frm_status": "frm_status",
    "frm_score": 0,
    "frm_reason": {},
    "frm_error": "frm_error"
  },
  "metadata": {},
  "connector_metadata": {
    "apple_pay": {
      "session_token_data": {
        "certificate": "certificate",
        "certificate_keys": "certificate_keys",
        "merchant_identifier": "merchant_identifier",
        "display_name": "display_name",
        "initiative": "web",
        "initiative_context": "initiative_context",
        "merchant_business_country": "AF"
      }
    },
    "airwallex": {
      "payload": "payload"
    },
    "noon": {
      "order_category": "order_category"
    },
    "braintree": {
      "merchant_account_id": "merchant_account_id",
      "merchant_config_currency": "merchant_config_currency"
    },
    "adyen": {
      "testing": {
        "holder_name": "holder_name"
      }
    },
    "peachpayments": {
      "rrn": "rrn"
    }
  },
  "connector_response_metadata": {
    "santander": {
      "end_to_end_id": "end_to_end_id"
    }
  },
  "feature_metadata": {
    "redirect_response": {
      "param": "param",
      "json_payload": {}
    },
    "search_tags": [
      "string"
    ],
    "apple_pay_recurring_details": {
      "payment_description": "payment_description",
      "regular_billing": {
        "label": "label",
        "recurring_payment_start_date": "2023-09-10T23:59:59Z",
        "recurring_payment_end_date": "2023-09-10T23:59:59Z",
        "recurring_payment_interval_unit": "year",
        "recurring_payment_interval_count": 0
      },
      "billing_agreement": "billing_agreement",
      "management_url": "https://hyperswitch.io"
    },
    "pix_additional_details": {
      "immediate": {
        "time": 0,
        "pix_key": {
          "type": "cpf",
          "value": "value"
        }
      }
    },
    "boleto_additional_details": {
      "due_date": "2026-12-31",
      "document_kind": "commercial_invoice",
      "payment_type": "fixed_amount",
      "covenant_code": "3568253",
      "pix_key": {
        "type": "cpf",
        "value": "value"
      }
    }
  },
  "reference_id": "993672945374576J",
  "payment_link": {
    "link": "link",
    "secure_link": "secure_link",
    "payment_link_id": "payment_link_id"
  },
  "profile_id": "profile_id",
  "surcharge_details": {
    "surcharge_amount": 6540,
    "tax_amount": 0
  },
  "attempt_count": 0,
  "merchant_decision": "merchant_decision",
  "merchant_connector_id": "merchant_connector_id",
  "incremental_authorization_allowed": true,
  "authorization_count": 0,
  "incremental_authorizations": [
    {
      "authorization_id": "authorization_id",
      "amount": 6540,
      "status": "success",
      "error_code": "error_code",
      "error_message": "error_message",
      "previously_authorized_amount": 0
    }
  ],
  "external_authentication_details": {
    "authentication_flow": "challenge",
    "electronic_commerce_indicator": "electronic_commerce_indicator",
    "status": "started",
    "ds_transaction_id": "ds_transaction_id",
    "version": "version",
    "error_code": "error_code",
    "error_message": "error_message"
  },
  "external_3ds_authentication_attempted": true,
  "expires_on": "2022-09-10T10:11:12Z",
  "fingerprint": "fingerprint",
  "browser_info": {
    "color_depth": 0,
    "java_enabled": true,
    "java_script_enabled": true,
    "language": "language",
    "screen_height": 0,
    "screen_width": 0,
    "time_zone": 0,
    "ip_address": "ip_address",
    "accept_header": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8",
    "user_agent": "user_agent",
    "os_type": "os_type",
    "os_version": "os_version",
    "device_model": "device_model",
    "accept_language": "accept_language",
    "referer": "referer"
  },
  "payment_channel": "ecommerce",
  "payment_method_id": "payment_method_id",
  "network_transaction_id": "network_transaction_id",
  "payment_method_status": "active",
  "updated": "2022-09-10T10:11:12Z",
  "split_payments": {
    "stripe_split_payment": {
      "charge_id": "charge_id",
      "charge_type": {
        "Stripe": "direct"
      },
      "application_fees": 6540,
      "transfer_account_id": "transfer_account_id"
    }
  },
  "frm_metadata": {},
  "extended_authorization_applied": true,
  "extended_authorization_last_applied_at": "2022-09-10T10:11:12Z",
  "request_extended_authorization": false,
  "capture_before": "2024-08-25T15:00:00Z",
  "merchant_order_reference_id": "Custom_Order_id_123",
  "order_tax_amount": 0,
  "connector_mandate_id": "connector_mandate_id",
  "card_discovery": "manual",
  "force_3ds_challenge": true,
  "force_3ds_challenge_trigger": true,
  "issuer_error_code": "issuer_error_code",
  "issuer_error_message": "issuer_error_message",
  "is_iframe_redirection_enabled": true,
  "whole_connector_response": "whole_connector_response",
  "enable_partial_authorization": false,
  "enable_overcapture": true,
  "is_overcapture_enabled": true,
  "network_details": {
    "network_advice_code": "network_advice_code"
  },
  "is_stored_credential": true,
  "mit_category": "installment",
  "billing_descriptor": {
    "name": "The Online Retailer",
    "city": "San Francisco",
    "phone": "9123456789",
    "statement_descriptor": "statement_descriptor",
    "statement_descriptor_suffix": "statement_descriptor_suffix",
    "reference": "reference"
  },
  "tokenization": "skip_psp",
  "partner_merchant_identifier_details": {
    "partner_details": {
      "name": "name",
      "version": "1.0.0",
      "integrator": "integrator"
    },
    "merchant_details": {
      "name": "name",
      "version": "version"
    }
  },
  "payment_method_tokenization_details": {
    "payment_method_id": "payment_method_id",
    "payment_method_status": "active",
    "psp_tokenization": true,
    "network_tokenization": true,
    "network_transaction_id": "network_transaction_id",
    "is_eligible_for_mit_payment": true
  },
  "installment_options": [
    {
      "payment_method": "card",
      "installments": [
        {
          "number_of_installments": "number_of_installments",
          "billing_frequency": "month",
          "interest_rate": 0
        }
      ]
    }
  ],
  "installment_data": {
    "number_of_installments": 0,
    "billing_frequency": "month",
    "installment_interest": 0
  },
  "customer_statistics": {
    "profile_id": "profile_id",
    "profile_name": "profile_name",
    "first_successful_payment_at": "first_successful_payment_at",
    "payments_count": 0,
    "payments_amount": 0,
    "refunds_count": 0,
    "refunds_amount": 0,
    "payouts_count": 0,
    "payouts_amount": 0,
    "currency": "AED"
  },
  "fee_summary": {
    "currency": "currency",
    "base_amount": 0,
    "merchant_commission_amount": 0,
    "provider_cost": 0,
    "margin": 0,
    "merchant_commission_rate": {},
    "provider_cost_rate": {},
    "merchant_commission_rule": "merchant_commission_rule",
    "provider_cost_rule": "provider_cost_rule"
  }
}

json

application/json

Payments - Confirm

POST

https://paysw-wiki.lab.next-on.pro/dev-router

/payments/{payment_id}/confirm

api-key (header)

Confirms a payment intent that was previously created with confirm: false. This action attempts to authorize the payment with the payment processor.

Expected status transitions after confirmation:

succeeded: If authorization is successful and capture_method is automatic.
requires_capture: If authorization is successful and capture_method is manual.
failed: If authorization fails.

Payments - Confirm › path Parameters

payment_id

string · required

The identifier for payment

Payments - Confirm › Request Body

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

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

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.

Enum values:

three_ds

no_three_ds

Default: three_ds

object

confirm

boolean | null

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

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

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

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

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:

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

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.

Payments - Confirm › Responses

Payment confirmed

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

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

Example: 6540

amount_capturable

integer · int64 · min: 100 · required

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

Example: 6540

initiator

string · enum

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

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

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

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.

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

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:

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

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

network_transaction_id

string | null

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

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

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

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

POST/payments/{payment_id}/confirm

curl https://paysw-wiki.lab.next-on.pro/dev-router/payments/:payment_id/confirm \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'api-key: <api-key>' \
  --data '{
  "customer_acceptance": {
    "acceptance_type": "online",
    "accepted_at": "1963-05-03T04:07:52.723Z",
    "online": {
      "ip_address": "127.0.0.1",
      "user_agent": "amet irure esse"
    }
  },
  "payment_method": "card",
  "payment_method_data": {
    "card": {
      "card_cvc": "123",
      "card_exp_month": "10",
      "card_exp_year": "25",
      "card_holder_name": "joseph Doe",
      "card_number": "4242424242424242"
    }
  },
  "payment_method_type": "credit"
}'

Example Request Body

{
  "customer_acceptance": {
    "acceptance_type": "online",
    "accepted_at": "1963-05-03T04:07:52.723Z",
    "online": {
      "ip_address": "127.0.0.1",
      "user_agent": "amet irure esse"
    }
  },
  "payment_method": "card",
  "payment_method_data": {
    "card": {
      "card_cvc": "123",
      "card_exp_month": "10",
      "card_exp_year": "25",
      "card_holder_name": "joseph Doe",
      "card_number": "4242424242424242"
    }
  },
  "payment_method_type": "credit"
}

json

application/json

Example Responses

{
  "payment_id": "pay_mbabizu24mvu3mela5njyhpit4",
  "merchant_id": "merchant_1668273825",
  "status": "requires_confirmation",
  "amount": 6540,
  "net_amount": 6540,
  "shipping_cost": 6540,
  "amount_capturable": 6540,
  "amount_received": 6540,
  "processor_merchant_id": "merchant_1689512302",
  "initiator": "platform",
  "sdk_authorization": "cHJvZmlsZV9pZD1wcm9mXzEyMyxwdWJsaXNoYWJsZV9rZXk9cGtfbGl2ZV8xMjM=",
  "connector": "stripe",
  "state_metadata": {
    "total_refunded_amount": 0,
    "total_disputed_amount": 0,
    "post_capture_void": {
      "status": "succeeded",
      "connector_reference_id": "connector_reference_id",
      "description": "description",
      "updated_at": "2024-08-25T15:00:00Z"
    }
  },
  "client_secret": "pay_U42c409qyHwOkWo3vK60_secret_el9ksDkiB8hi6j9N78yo",
  "created": "2022-09-10T10:11:12Z",
  "modified_at": "2022-09-10T10:11:12Z",
  "currency": "AED",
  "customer_id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
  "description": "It's my first payment request",
  "refunds": [
    {
      "refund_id": "refund_id",
      "payment_id": "payment_id",
      "amount": 6540,
      "currency": "currency",
      "status": "succeeded",
      "reason": "reason",
      "metadata": {},
      "error_message": "error_message",
      "error_code": "error_code",
      "unified_code": "unified_code",
      "unified_message": "unified_message",
      "created_at": "2024-08-25T15:00:00Z",
      "updated_at": "2024-08-25T15:00:00Z",
      "connector": "stripe",
      "profile_id": "profile_id",
      "merchant_connector_id": "merchant_connector_id",
      "split_refunds": {
        "stripe_split_refund": {
          "revert_platform_fee": true,
          "revert_transfer": true
        }
      },
      "issuer_error_code": "issuer_error_code",
      "issuer_error_message": "issuer_error_message",
      "raw_connector_response": "raw_connector_response",
      "connector_refund_id": "connector_refund_id",
      "fee_summary": {
        "currency": "currency",
        "base_amount": 0,
        "merchant_commission_amount": 0,
        "provider_cost": 0,
        "margin": 0,
        "merchant_commission_rate": {},
        "provider_cost_rate": {},
        "merchant_commission_rule": "merchant_commission_rule",
        "provider_cost_rule": "provider_cost_rule"
      }
    }
  ],
  "disputes": [
    {
      "dispute_id": "dispute_id",
      "amount": "amount",
      "dispute_stage": "pre_dispute",
      "dispute_status": "dispute_opened",
      "connector_status": "connector_status",
      "connector_dispute_id": "connector_dispute_id",
      "connector_reason": "connector_reason",
      "connector_reason_code": "connector_reason_code",
      "challenge_required_by": "2024-08-25T15:00:00Z",
      "connector_created_at": "2024-08-25T15:00:00Z",
      "connector_updated_at": "2024-08-25T15:00:00Z",
      "created_at": "2024-08-25T15:00:00Z"
    }
  ],
  "attempts": [
    {
      "attempt_id": "attempt_id",
      "status": "started",
      "amount": 6540,
      "order_tax_amount": 6540,
      "currency": "AED",
      "connector": "connector",
      "merchant_connector_id": "merchant_connector_id",
      "error_message": "error_message",
      "payment_method": "card",
      "connector_transaction_id": "connector_transaction_id",
      "capture_method": "automatic",
      "authentication_type": "three_ds",
      "created_at": "2022-09-10T10:11:12Z",
      "modified_at": "2022-09-10T10:11:12Z",
      "cancellation_reason": "cancellation_reason",
      "mandate_id": "mandate_id",
      "error_code": "error_code",
      "payment_token": "payment_token",
      "connector_metadata": {},
      "payment_experience": "redirect_to_url",
      "payment_method_type": "ach",
      "reference_id": "993672945374576J",
      "unified_code": "unified_code",
      "unified_message": "unified_message",
      "client_source": "client_source",
      "client_version": "client_version",
      "error_details": {
        "unified_details": {
          "category": "UE_1000",
          "message": "message",
          "standardised_code": "account_closed_or_invalid",
          "description": "description",
          "user_guidance_message": "user_guidance_message",
          "recommended_action": "do_not_retry"
        },
        "issuer_details": {
          "code": "code",
          "message": "message",
          "network_details": {
            "name": "Visa",
            "advice_code": "advice_code",
            "advice_message": "advice_message"
          }
        },
        "connector_details": {
          "code": "code",
          "message": "message",
          "reason": "reason"
        }
      },
      "fee_details": [
        {
          "capture_id": "capture_id",
          "reference_id": "reference_id",
          "created_at": "2024-01-01T00:00:00Z",
          "currency": "currency",
          "base_amount": 0,
          "merchant_commission_amount": 0,
          "provider_cost": 0,
          "margin": 0,
          "merchant_commission_rate": {},
          "provider_cost_rate": {},
          "merchant_commission_rule": "merchant_commission_rule",
          "provider_cost_rule": "provider_cost_rule"
        }
      ]
    }
  ],
  "captures": [
    {
      "capture_id": "capture_id",
      "status": "started",
      "amount": 6540,
      "currency": "AED",
      "connector": "connector",
      "authorized_attempt_id": "authorized_attempt_id",
      "connector_capture_id": "connector_capture_id",
      "capture_sequence": 0,
      "error_message": "error_message",
      "error_code": "error_code",
      "error_reason": "error_reason",
      "reference_id": "reference_id"
    }
  ],
  "mandate_id": "mandate_iwer89rnjef349dni3",
  "mandate_data": {
    "update_mandate_id": "update_mandate_id",
    "customer_acceptance": {
      "acceptance_type": "online",
      "accepted_at": "2022-09-10T10:11:12Z",
      "online": {
        "ip_address": "123.32.25.123",
        "user_agent": "user_agent"
      }
    },
    "mandate_type": {
      "single_use": {
        "amount": 6540,
        "currency": "AED",
        "start_date": "2022-09-10T00:00:00Z",
        "end_date": "2023-09-10T23:59:59Z",
        "metadata": {}
      }
    }
  },
  "setup_future_usage": "off_session",
  "off_session": true,
  "capture_method": "automatic",
  "payment_method": "card",
  "payment_method_data": {
    "billing": {
      "address": {
        "city": "New York",
        "country": "AF",
        "line1": "123, King Street",
        "line2": "Powelson Avenue",
        "line3": "Bridgewater",
        "zip": "08807",
        "state": "New York",
        "first_name": "John",
        "last_name": "Doe",
        "origin_zip": "08807"
      },
      "phone": {
        "number": "9123456789",
        "country_code": "+1"
      },
      "email": "email"
    }
  },
  "payment_token": "187282ab-40ef-47a9-9206-5099ba31e432",
  "shipping": {
    "address": {
      "city": "New York",
      "country": "AF",
      "line1": "123, King Street",
      "line2": "Powelson Avenue",
      "line3": "Bridgewater",
      "zip": "08807",
      "state": "New York",
      "first_name": "John",
      "last_name": "Doe",
      "origin_zip": "08807"
    },
    "phone": {
      "number": "9123456789",
      "country_code": "+1"
    },
    "email": "email"
  },
  "billing": {
    "address": {
      "city": "New York",
      "country": "AF",
      "line1": "123, King Street",
      "line2": "Powelson Avenue",
      "line3": "Bridgewater",
      "zip": "08807",
      "state": "New York",
      "first_name": "John",
      "last_name": "Doe",
      "origin_zip": "08807"
    },
    "phone": {
      "number": "9123456789",
      "country_code": "+1"
    },
    "email": "email"
  },
  "order_details": "[{\n        \"product_name\": \"gillete creme\",\n        \"quantity\": 15,\n        \"amount\" : 900\n    }]",
  "email": "johntest@test.com",
  "name": "John Test",
  "phone": "9123456789",
  "return_url": "https://hyperswitch.io",
  "authentication_type": "three_ds",
  "statement_descriptor_name": "Hyperswitch Router",
  "statement_descriptor_suffix": "Payment for shoes purchase",
  "next_action": {
    "redirect_to_url": "redirect_to_url",
    "type": "redirect_to_url"
  },
  "cancellation_reason": "cancellation_reason",
  "error_code": "E0001",
  "error_message": "Failed while verifying the card",
  "error_details": {
    "unified_details": {
      "category": "UE_1000",
      "message": "message",
      "standardised_code": "account_closed_or_invalid",
      "description": "description",
      "user_guidance_message": "user_guidance_message",
      "recommended_action": "do_not_retry"
    },
    "issuer_details": {
      "code": "code",
      "message": "message",
      "network_details": {
        "name": "Visa",
        "advice_code": "advice_code",
        "advice_message": "advice_message"
      }
    },
    "connector_details": {
      "code": "code",
      "message": "message",
      "reason": "reason"
    }
  },
  "payment_experience": "redirect_to_url",
  "payment_method_type": "ach",
  "connector_label": "stripe_US_food",
  "business_country": "AF",
  "business_label": "business_label",
  "business_sub_label": "business_sub_label",
  "allowed_payment_method_types": [
    "ach"
  ],
  "manual_retry_allowed": true,
  "connector_transaction_id": "993672945374576J",
  "frm_message": {
    "frm_name": "frm_name",
    "frm_transaction_id": "frm_transaction_id",
    "frm_transaction_type": "frm_transaction_type",
    "frm_status": "frm_status",
    "frm_score": 0,
    "frm_reason": {},
    "frm_error": "frm_error"
  },
  "metadata": {},
  "connector_metadata": {
    "apple_pay": {
      "session_token_data": {
        "certificate": "certificate",
        "certificate_keys": "certificate_keys",
        "merchant_identifier": "merchant_identifier",
        "display_name": "display_name",
        "initiative": "web",
        "initiative_context": "initiative_context",
        "merchant_business_country": "AF"
      }
    },
    "airwallex": {
      "payload": "payload"
    },
    "noon": {
      "order_category": "order_category"
    },
    "braintree": {
      "merchant_account_id": "merchant_account_id",
      "merchant_config_currency": "merchant_config_currency"
    },
    "adyen": {
      "testing": {
        "holder_name": "holder_name"
      }
    },
    "peachpayments": {
      "rrn": "rrn"
    }
  },
  "connector_response_metadata": {
    "santander": {
      "end_to_end_id": "end_to_end_id"
    }
  },
  "feature_metadata": {
    "redirect_response": {
      "param": "param",
      "json_payload": {}
    },
    "search_tags": [
      "string"
    ],
    "apple_pay_recurring_details": {
      "payment_description": "payment_description",
      "regular_billing": {
        "label": "label",
        "recurring_payment_start_date": "2023-09-10T23:59:59Z",
        "recurring_payment_end_date": "2023-09-10T23:59:59Z",
        "recurring_payment_interval_unit": "year",
        "recurring_payment_interval_count": 0
      },
      "billing_agreement": "billing_agreement",
      "management_url": "https://hyperswitch.io"
    },
    "pix_additional_details": {
      "immediate": {
        "time": 0,
        "pix_key": {
          "type": "cpf",
          "value": "value"
        }
      }
    },
    "boleto_additional_details": {
      "due_date": "2026-12-31",
      "document_kind": "commercial_invoice",
      "payment_type": "fixed_amount",
      "covenant_code": "3568253",
      "pix_key": {
        "type": "cpf",
        "value": "value"
      }
    }
  },
  "reference_id": "993672945374576J",
  "payment_link": {
    "link": "link",
    "secure_link": "secure_link",
    "payment_link_id": "payment_link_id"
  },
  "profile_id": "profile_id",
  "surcharge_details": {
    "surcharge_amount": 6540,
    "tax_amount": 0
  },
  "attempt_count": 0,
  "merchant_decision": "merchant_decision",
  "merchant_connector_id": "merchant_connector_id",
  "incremental_authorization_allowed": true,
  "authorization_count": 0,
  "incremental_authorizations": [
    {
      "authorization_id": "authorization_id",
      "amount": 6540,
      "status": "success",
      "error_code": "error_code",
      "error_message": "error_message",
      "previously_authorized_amount": 0
    }
  ],
  "external_authentication_details": {
    "authentication_flow": "challenge",
    "electronic_commerce_indicator": "electronic_commerce_indicator",
    "status": "started",
    "ds_transaction_id": "ds_transaction_id",
    "version": "version",
    "error_code": "error_code",
    "error_message": "error_message"
  },
  "external_3ds_authentication_attempted": true,
  "expires_on": "2022-09-10T10:11:12Z",
  "fingerprint": "fingerprint",
  "browser_info": {
    "color_depth": 0,
    "java_enabled": true,
    "java_script_enabled": true,
    "language": "language",
    "screen_height": 0,
    "screen_width": 0,
    "time_zone": 0,
    "ip_address": "ip_address",
    "accept_header": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8",
    "user_agent": "user_agent",
    "os_type": "os_type",
    "os_version": "os_version",
    "device_model": "device_model",
    "accept_language": "accept_language",
    "referer": "referer"
  },
  "payment_channel": "ecommerce",
  "payment_method_id": "payment_method_id",
  "network_transaction_id": "network_transaction_id",
  "payment_method_status": "active",
  "updated": "2022-09-10T10:11:12Z",
  "split_payments": {
    "stripe_split_payment": {
      "charge_id": "charge_id",
      "charge_type": {
        "Stripe": "direct"
      },
      "application_fees": 6540,
      "transfer_account_id": "transfer_account_id"
    }
  },
  "frm_metadata": {},
  "extended_authorization_applied": true,
  "extended_authorization_last_applied_at": "2022-09-10T10:11:12Z",
  "request_extended_authorization": false,
  "capture_before": "2024-08-25T15:00:00Z",
  "merchant_order_reference_id": "Custom_Order_id_123",
  "order_tax_amount": 0,
  "connector_mandate_id": "connector_mandate_id",
  "card_discovery": "manual",
  "force_3ds_challenge": true,
  "force_3ds_challenge_trigger": true,
  "issuer_error_code": "issuer_error_code",
  "issuer_error_message": "issuer_error_message",
  "is_iframe_redirection_enabled": true,
  "whole_connector_response": "whole_connector_response",
  "enable_partial_authorization": false,
  "enable_overcapture": true,
  "is_overcapture_enabled": true,
  "network_details": {
    "network_advice_code": "network_advice_code"
  },
  "is_stored_credential": true,
  "mit_category": "installment",
  "billing_descriptor": {
    "name": "The Online Retailer",
    "city": "San Francisco",
    "phone": "9123456789",
    "statement_descriptor": "statement_descriptor",
    "statement_descriptor_suffix": "statement_descriptor_suffix",
    "reference": "reference"
  },
  "tokenization": "skip_psp",
  "partner_merchant_identifier_details": {
    "partner_details": {
      "name": "name",
      "version": "1.0.0",
      "integrator": "integrator"
    },
    "merchant_details": {
      "name": "name",
      "version": "version"
    }
  },
  "payment_method_tokenization_details": {
    "payment_method_id": "payment_method_id",
    "payment_method_status": "active",
    "psp_tokenization": true,
    "network_tokenization": true,
    "network_transaction_id": "network_transaction_id",
    "is_eligible_for_mit_payment": true
  },
  "installment_options": [
    {
      "payment_method": "card",
      "installments": [
        {
          "number_of_installments": "number_of_installments",
          "billing_frequency": "month",
          "interest_rate": 0
        }
      ]
    }
  ],
  "installment_data": {
    "number_of_installments": 0,
    "billing_frequency": "month",
    "installment_interest": 0
  },
  "customer_statistics": {
    "profile_id": "profile_id",
    "profile_name": "profile_name",
    "first_successful_payment_at": "first_successful_payment_at",
    "payments_count": 0,
    "payments_amount": 0,
    "refunds_count": 0,
    "refunds_amount": 0,
    "payouts_count": 0,
    "payouts_amount": 0,
    "currency": "AED"
  },
  "fee_summary": {
    "currency": "currency",
    "base_amount": 0,
    "merchant_commission_amount": 0,
    "provider_cost": 0,
    "margin": 0,
    "merchant_commission_rate": {},
    "provider_cost_rate": {},
    "merchant_commission_rule": "merchant_commission_rule",
    "provider_cost_rule": "provider_cost_rule"
  }
}

json

application/json

Payments — detailed read model (OLAP)

GET

https://paysw-wiki.lab.next-on.pro/dev-router

/payments/{payment_id}/details

api-key (header)

Returns an expanded payment record: intent, attempts, refunds, disputes, webhook history, etc.

Payments — detailed read model (OLAP) › path Parameters

payment_id

string · required

The identifier for payment

Payments — detailed read model (OLAP) › query Parameters

expand_customer_statistics

boolean | null

When true, includes customer statistics for the payment profile (OLAP)

Payments — detailed read model (OLAP) › Responses

Payment details

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.

PaymentDetailedResponse

payment_id

string · required

merchant_id

string · required

status

IntentStatus · enum · required

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

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

GET/payments/{payment_id}/details

curl https://paysw-wiki.lab.next-on.pro/dev-router/payments/:payment_id/details \
  --header 'api-key: <api-key>'

Example Responses

{
  "payment_id": "payment_id",
  "merchant_id": "merchant_id",
  "status": "succeeded",
  "amount": 0,
  "net_amount": 0,
  "shipping_cost": 0,
  "amount_capturable": 0,
  "amount_received": 0,
  "currency": "currency",
  "description": "description",
  "metadata": {},
  "created": "2024-01-01T00:00:00Z",
  "modified_at": "2024-01-01T00:00:00Z",
  "customer": {
    "id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
    "name": "John Doe",
    "email": "johntest@test.com",
    "phone": "9123456789",
    "phone_country_code": "+1",
    "customer_document_details": {
      "document_type": "cpf",
      "document_number": "12345678911"
    }
  },
  "billing": {
    "address": {
      "city": "New York",
      "country": "AF",
      "line1": "123, King Street",
      "line2": "Powelson Avenue",
      "line3": "Bridgewater",
      "zip": "08807",
      "state": "New York",
      "first_name": "John",
      "last_name": "Doe",
      "origin_zip": "08807"
    },
    "phone": {
      "number": "9123456789",
      "country_code": "+1"
    },
    "email": "email"
  },
  "shipping": {
    "address": {
      "city": "New York",
      "country": "AF",
      "line1": "123, King Street",
      "line2": "Powelson Avenue",
      "line3": "Bridgewater",
      "zip": "08807",
      "state": "New York",
      "first_name": "John",
      "last_name": "Doe",
      "origin_zip": "08807"
    },
    "phone": {
      "number": "9123456789",
      "country_code": "+1"
    },
    "email": "email"
  },
  "attempts": [
    {
      "attempt_id": "attempt_id",
      "status": "started",
      "amount": 0,
      "order_tax_amount": 0,
      "currency": "AED",
      "connector": "connector",
      "merchant_connector_id": "merchant_connector_id",
      "error_message": "error_message",
      "payment_method": "card",
      "connector_transaction_id": "connector_transaction_id",
      "capture_method": "automatic",
      "authentication_type": "three_ds",
      "created_at": "2024-01-01T00:00:00Z",
      "modified_at": "2024-01-01T00:00:00Z",
      "cancellation_reason": "cancellation_reason",
      "mandate_id": "mandate_id",
      "error_code": "error_code",
      "payment_token": "payment_token",
      "connector_metadata": {},
      "payment_experience": "redirect_to_url",
      "payment_method_type": "ach",
      "reference_id": "reference_id",
      "unified_code": "unified_code",
      "unified_message": "unified_message",
      "client_source": "client_source",
      "client_version": "client_version",
      "error_details": {
        "unified_details": {
          "category": "UE_1000",
          "message": "message",
          "standardised_code": "account_closed_or_invalid",
          "description": "description",
          "user_guidance_message": "user_guidance_message",
          "recommended_action": "do_not_retry"
        },
        "issuer_details": {
          "code": "code",
          "message": "message",
          "network_details": {
            "name": "Visa",
            "advice_code": "advice_code",
            "advice_message": "advice_message"
          }
        },
        "connector_details": {
          "code": "code",
          "message": "message",
          "reason": "reason"
        }
      },
      "routing_details": {
        "algorithm": {},
        "routed_through": "routed_through"
      },
      "surcharge_details": {
        "surcharge_amount": 6540,
        "tax_amount": 0
      },
      "fee_details": [
        {
          "capture_id": "capture_id",
          "reference_id": "reference_id",
          "created_at": "2024-01-01T00:00:00Z",
          "currency": "currency",
          "base_amount": 0,
          "merchant_commission_amount": 0,
          "provider_cost": 0,
          "margin": 0,
          "merchant_commission_rate": {},
          "provider_cost_rate": {},
          "merchant_commission_rule": "merchant_commission_rule",
          "provider_cost_rule": "provider_cost_rule"
        }
      ]
    }
  ],
  "refunds": [
    {
      "refund_id": "refund_id",
      "payment_id": "payment_id",
      "amount": 6540,
      "currency": "currency",
      "status": "succeeded",
      "reason": "reason",
      "metadata": {},
      "error_message": "error_message",
      "error_code": "error_code",
      "unified_code": "unified_code",
      "unified_message": "unified_message",
      "created_at": "2024-08-25T15:00:00Z",
      "updated_at": "2024-08-25T15:00:00Z",
      "connector": "stripe",
      "profile_id": "profile_id",
      "merchant_connector_id": "merchant_connector_id",
      "split_refunds": {
        "stripe_split_refund": {
          "revert_platform_fee": true,
          "revert_transfer": true
        }
      },
      "issuer_error_code": "issuer_error_code",
      "issuer_error_message": "issuer_error_message",
      "raw_connector_response": "raw_connector_response",
      "connector_refund_id": "connector_refund_id",
      "fee_summary": {
        "currency": "currency",
        "base_amount": 0,
        "merchant_commission_amount": 0,
        "provider_cost": 0,
        "margin": 0,
        "merchant_commission_rate": {},
        "provider_cost_rate": {},
        "merchant_commission_rule": "merchant_commission_rule",
        "provider_cost_rule": "provider_cost_rule"
      }
    }
  ],
  "disputes": [
    {
      "dispute_id": "dispute_id",
      "amount": "amount",
      "dispute_stage": "pre_dispute",
      "dispute_status": "dispute_opened",
      "connector_status": "connector_status",
      "connector_dispute_id": "connector_dispute_id",
      "connector_reason": "connector_reason",
      "connector_reason_code": "connector_reason_code",
      "challenge_required_by": "2024-08-25T15:00:00Z",
      "connector_created_at": "2024-08-25T15:00:00Z",
      "connector_updated_at": "2024-08-25T15:00:00Z",
      "created_at": "2024-08-25T15:00:00Z"
    }
  ],
  "webhook_execution_history": [
    {
      "event_id": "event_id",
      "initial_attempt_id": "initial_attempt_id",
      "event_type": "payment_succeeded",
      "delivery_attempt": "initial_attempt",
      "is_webhook_notified": true,
      "is_overall_delivery_successful": true,
      "created_at": "2024-01-01T00:00:00Z",
      "request": "request",
      "response": "response",
      "status_code": 0,
      "is_error": true,
      "error": "error"
    }
  ],
  "field_origins": {
    "key": "passed_by_merchant"
  },
  "customer_statistics": {
    "profile_id": "profile_id",
    "profile_name": "profile_name",
    "first_successful_payment_at": "first_successful_payment_at",
    "payments_count": 0,
    "payments_amount": 0,
    "refunds_count": 0,
    "refunds_amount": 0,
    "payouts_count": 0,
    "payouts_amount": 0,
    "currency": "AED"
  },
  "fee_summary": {
    "currency": "currency",
    "base_amount": 0,
    "merchant_commission_amount": 0,
    "provider_cost": 0,
    "margin": 0,
    "merchant_commission_rate": {},
    "provider_cost_rate": {},
    "merchant_commission_rule": "merchant_commission_rule",
    "provider_cost_rule": "provider_cost_rule"
  }
}

json

application/json

Payments - Capture

POST

https://paysw-wiki.lab.next-on.pro/dev-router

/payments/{payment_id}/capture

api-key (header)

Captures the funds for a previously authorized payment intent where capture_method was set to manual and the payment is in a requires_capture state.

Upon successful capture, the payment status usually transitions to succeeded. The amount_to_capture can be specified in the request body; it must be less than or equal to the payment's amount_capturable. If omitted, the full capturable amount is captured.

A payment must be in a capturable state (e.g., requires_capture). Attempting to capture an already succeeded (and fully captured) payment or one in an invalid state will lead to an error.

Payments - Capture › path Parameters

payment_id

string · required

The identifier for payment

Payments - Capture › Request Body

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

Payments - Capture › Responses

Payment captured

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

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

Example: 6540

amount_capturable

integer · int64 · min: 100 · required

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

Example: 6540

initiator

string · enum

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

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

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

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.

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

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:

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

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

network_transaction_id

string | null

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

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

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

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

POST/payments/{payment_id}/capture

curl https://paysw-wiki.lab.next-on.pro/dev-router/payments/:payment_id/capture \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'api-key: <api-key>' \
  --data '{
  "amount_to_capture": 654
}'

Example Request Body

{
  "amount_to_capture": 654
}

json

application/json

Example Responses

{
  "payment_id": "pay_mbabizu24mvu3mela5njyhpit4",
  "merchant_id": "merchant_1668273825",
  "status": "requires_confirmation",
  "amount": 6540,
  "net_amount": 6540,
  "shipping_cost": 6540,
  "amount_capturable": 6540,
  "amount_received": 6540,
  "processor_merchant_id": "merchant_1689512302",
  "initiator": "platform",
  "sdk_authorization": "cHJvZmlsZV9pZD1wcm9mXzEyMyxwdWJsaXNoYWJsZV9rZXk9cGtfbGl2ZV8xMjM=",
  "connector": "stripe",
  "state_metadata": {
    "total_refunded_amount": 0,
    "total_disputed_amount": 0,
    "post_capture_void": {
      "status": "succeeded",
      "connector_reference_id": "connector_reference_id",
      "description": "description",
      "updated_at": "2024-08-25T15:00:00Z"
    }
  },
  "client_secret": "pay_U42c409qyHwOkWo3vK60_secret_el9ksDkiB8hi6j9N78yo",
  "created": "2022-09-10T10:11:12Z",
  "modified_at": "2022-09-10T10:11:12Z",
  "currency": "AED",
  "customer_id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
  "customer": {
    "id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
    "name": "John Doe",
    "email": "johntest@test.com",
    "phone": "9123456789",
    "phone_country_code": "+1",
    "customer_document_details": {
      "document_type": "cpf",
      "document_number": "12345678911"
    }
  },
  "description": "It's my first payment request",
  "refunds": [
    {
      "refund_id": "refund_id",
      "payment_id": "payment_id",
      "amount": 6540,
      "currency": "currency",
      "status": "succeeded",
      "reason": "reason",
      "metadata": {},
      "error_message": "error_message",
      "error_code": "error_code",
      "unified_code": "unified_code",
      "unified_message": "unified_message",
      "created_at": "2024-08-25T15:00:00Z",
      "updated_at": "2024-08-25T15:00:00Z",
      "connector": "stripe",
      "profile_id": "profile_id",
      "merchant_connector_id": "merchant_connector_id",
      "split_refunds": {
        "stripe_split_refund": {
          "revert_platform_fee": true,
          "revert_transfer": true
        }
      },
      "issuer_error_code": "issuer_error_code",
      "issuer_error_message": "issuer_error_message",
      "raw_connector_response": "raw_connector_response",
      "connector_refund_id": "connector_refund_id",
      "fee_summary": {
        "currency": "currency",
        "base_amount": 0,
        "merchant_commission_amount": 0,
        "provider_cost": 0,
        "margin": 0,
        "merchant_commission_rate": {},
        "provider_cost_rate": {},
        "merchant_commission_rule": "merchant_commission_rule",
        "provider_cost_rule": "provider_cost_rule"
      }
    }
  ],
  "disputes": [
    {
      "dispute_id": "dispute_id",
      "amount": "amount",
      "dispute_stage": "pre_dispute",
      "dispute_status": "dispute_opened",
      "connector_status": "connector_status",
      "connector_dispute_id": "connector_dispute_id",
      "connector_reason": "connector_reason",
      "connector_reason_code": "connector_reason_code",
      "challenge_required_by": "2024-08-25T15:00:00Z",
      "connector_created_at": "2024-08-25T15:00:00Z",
      "connector_updated_at": "2024-08-25T15:00:00Z",
      "created_at": "2024-08-25T15:00:00Z"
    }
  ],
  "attempts": [
    {
      "attempt_id": "attempt_id",
      "status": "started",
      "amount": 6540,
      "order_tax_amount": 6540,
      "currency": "AED",
      "connector": "connector",
      "merchant_connector_id": "merchant_connector_id",
      "error_message": "error_message",
      "payment_method": "card",
      "connector_transaction_id": "connector_transaction_id",
      "capture_method": "automatic",
      "authentication_type": "three_ds",
      "created_at": "2022-09-10T10:11:12Z",
      "modified_at": "2022-09-10T10:11:12Z",
      "cancellation_reason": "cancellation_reason",
      "mandate_id": "mandate_id",
      "error_code": "error_code",
      "payment_token": "payment_token",
      "connector_metadata": {},
      "payment_experience": "redirect_to_url",
      "payment_method_type": "ach",
      "reference_id": "993672945374576J",
      "unified_code": "unified_code",
      "unified_message": "unified_message",
      "client_source": "client_source",
      "client_version": "client_version",
      "error_details": {
        "unified_details": {
          "category": "UE_1000",
          "message": "message",
          "standardised_code": "account_closed_or_invalid",
          "description": "description",
          "user_guidance_message": "user_guidance_message",
          "recommended_action": "do_not_retry"
        },
        "issuer_details": {
          "code": "code",
          "message": "message",
          "network_details": {
            "name": "Visa",
            "advice_code": "advice_code",
            "advice_message": "advice_message"
          }
        },
        "connector_details": {
          "code": "code",
          "message": "message",
          "reason": "reason"
        }
      },
      "fee_details": [
        {
          "capture_id": "capture_id",
          "reference_id": "reference_id",
          "created_at": "2024-01-01T00:00:00Z",
          "currency": "currency",
          "base_amount": 0,
          "merchant_commission_amount": 0,
          "provider_cost": 0,
          "margin": 0,
          "merchant_commission_rate": {},
          "provider_cost_rate": {},
          "merchant_commission_rule": "merchant_commission_rule",
          "provider_cost_rule": "provider_cost_rule"
        }
      ]
    }
  ],
  "captures": [
    {
      "capture_id": "capture_id",
      "status": "started",
      "amount": 6540,
      "currency": "AED",
      "connector": "connector",
      "authorized_attempt_id": "authorized_attempt_id",
      "connector_capture_id": "connector_capture_id",
      "capture_sequence": 0,
      "error_message": "error_message",
      "error_code": "error_code",
      "error_reason": "error_reason",
      "reference_id": "reference_id"
    }
  ],
  "mandate_id": "mandate_iwer89rnjef349dni3",
  "mandate_data": {
    "update_mandate_id": "update_mandate_id",
    "customer_acceptance": {
      "acceptance_type": "online",
      "accepted_at": "2022-09-10T10:11:12Z",
      "online": {
        "ip_address": "123.32.25.123",
        "user_agent": "user_agent"
      }
    },
    "mandate_type": {
      "single_use": {
        "amount": 6540,
        "currency": "AED",
        "start_date": "2022-09-10T00:00:00Z",
        "end_date": "2023-09-10T23:59:59Z",
        "metadata": {}
      }
    }
  },
  "setup_future_usage": "off_session",
  "off_session": true,
  "capture_on": "2022-09-10T10:11:12Z",
  "capture_method": "automatic",
  "payment_method": "card",
  "payment_method_data": {
    "billing": {
      "address": {
        "city": "New York",
        "country": "AF",
        "line1": "123, King Street",
        "line2": "Powelson Avenue",
        "line3": "Bridgewater",
        "zip": "08807",
        "state": "New York",
        "first_name": "John",
        "last_name": "Doe",
        "origin_zip": "08807"
      },
      "phone": {
        "number": "9123456789",
        "country_code": "+1"
      },
      "email": "email"
    }
  },
  "payment_token": "187282ab-40ef-47a9-9206-5099ba31e432",
  "shipping": {
    "address": {
      "city": "New York",
      "country": "AF",
      "line1": "123, King Street",
      "line2": "Powelson Avenue",
      "line3": "Bridgewater",
      "zip": "08807",
      "state": "New York",
      "first_name": "John",
      "last_name": "Doe",
      "origin_zip": "08807"
    },
    "phone": {
      "number": "9123456789",
      "country_code": "+1"
    },
    "email": "email"
  },
  "billing": {
    "address": {
      "city": "New York",
      "country": "AF",
      "line1": "123, King Street",
      "line2": "Powelson Avenue",
      "line3": "Bridgewater",
      "zip": "08807",
      "state": "New York",
      "first_name": "John",
      "last_name": "Doe",
      "origin_zip": "08807"
    },
    "phone": {
      "number": "9123456789",
      "country_code": "+1"
    },
    "email": "email"
  },
  "order_details": "[{\n        \"product_name\": \"gillete creme\",\n        \"quantity\": 15,\n        \"amount\" : 900\n    }]",
  "email": "johntest@test.com",
  "name": "John Test",
  "phone": "9123456789",
  "return_url": "https://hyperswitch.io",
  "authentication_type": "three_ds",
  "statement_descriptor_name": "Hyperswitch Router",
  "statement_descriptor_suffix": "Payment for shoes purchase",
  "next_action": {
    "redirect_to_url": "redirect_to_url",
    "type": "redirect_to_url"
  },
  "cancellation_reason": "cancellation_reason",
  "error_code": "E0001",
  "error_message": "Failed while verifying the card",
  "unified_code": "unified_code",
  "unified_message": "unified_message",
  "error_details": {
    "unified_details": {
      "category": "UE_1000",
      "message": "message",
      "standardised_code": "account_closed_or_invalid",
      "description": "description",
      "user_guidance_message": "user_guidance_message",
      "recommended_action": "do_not_retry"
    },
    "issuer_details": {
      "code": "code",
      "message": "message",
      "network_details": {
        "name": "Visa",
        "advice_code": "advice_code",
        "advice_message": "advice_message"
      }
    },
    "connector_details": {
      "code": "code",
      "message": "message",
      "reason": "reason"
    }
  },
  "payment_experience": "redirect_to_url",
  "payment_method_type": "ach",
  "connector_label": "stripe_US_food",
  "business_country": "AF",
  "business_label": "business_label",
  "business_sub_label": "business_sub_label",
  "allowed_payment_method_types": [
    "ach"
  ],
  "manual_retry_allowed": true,
  "connector_transaction_id": "993672945374576J",
  "frm_message": {
    "frm_name": "frm_name",
    "frm_transaction_id": "frm_transaction_id",
    "frm_transaction_type": "frm_transaction_type",
    "frm_status": "frm_status",
    "frm_score": 0,
    "frm_reason": {},
    "frm_error": "frm_error"
  },
  "metadata": {},
  "connector_metadata": {
    "apple_pay": {
      "session_token_data": {
        "certificate": "certificate",
        "certificate_keys": "certificate_keys",
        "merchant_identifier": "merchant_identifier",
        "display_name": "display_name",
        "initiative": "web",
        "initiative_context": "initiative_context",
        "merchant_business_country": "AF"
      }
    },
    "airwallex": {
      "payload": "payload"
    },
    "noon": {
      "order_category": "order_category"
    },
    "braintree": {
      "merchant_account_id": "merchant_account_id",
      "merchant_config_currency": "merchant_config_currency"
    },
    "adyen": {
      "testing": {
        "holder_name": "holder_name"
      }
    },
    "peachpayments": {
      "rrn": "rrn"
    }
  },
  "connector_response_metadata": {
    "santander": {
      "end_to_end_id": "end_to_end_id"
    }
  },
  "feature_metadata": {
    "redirect_response": {
      "param": "param",
      "json_payload": {}
    },
    "search_tags": [
      "string"
    ],
    "apple_pay_recurring_details": {
      "payment_description": "payment_description",
      "regular_billing": {
        "label": "label",
        "recurring_payment_start_date": "2023-09-10T23:59:59Z",
        "recurring_payment_end_date": "2023-09-10T23:59:59Z",
        "recurring_payment_interval_unit": "year",
        "recurring_payment_interval_count": 0
      },
      "billing_agreement": "billing_agreement",
      "management_url": "https://hyperswitch.io"
    },
    "pix_additional_details": {
      "immediate": {
        "time": 0,
        "pix_key": {
          "type": "cpf",
          "value": "value"
        }
      }
    },
    "boleto_additional_details": {
      "due_date": "2026-12-31",
      "document_kind": "commercial_invoice",
      "payment_type": "fixed_amount",
      "covenant_code": "3568253",
      "pix_key": {
        "type": "cpf",
        "value": "value"
      }
    }
  },
  "reference_id": "993672945374576J",
  "payment_link": {
    "link": "link",
    "secure_link": "secure_link",
    "payment_link_id": "payment_link_id"
  },
  "profile_id": "profile_id",
  "surcharge_details": {
    "surcharge_amount": 6540,
    "tax_amount": 0
  },
  "attempt_count": 0,
  "merchant_decision": "merchant_decision",
  "merchant_connector_id": "merchant_connector_id",
  "incremental_authorization_allowed": true,
  "authorization_count": 0,
  "incremental_authorizations": [
    {
      "authorization_id": "authorization_id",
      "amount": 6540,
      "status": "success",
      "error_code": "error_code",
      "error_message": "error_message",
      "previously_authorized_amount": 0
    }
  ],
  "external_authentication_details": {
    "authentication_flow": "challenge",
    "electronic_commerce_indicator": "electronic_commerce_indicator",
    "status": "started",
    "ds_transaction_id": "ds_transaction_id",
    "version": "version",
    "error_code": "error_code",
    "error_message": "error_message"
  },
  "external_3ds_authentication_attempted": true,
  "expires_on": "2022-09-10T10:11:12Z",
  "fingerprint": "fingerprint",
  "browser_info": {
    "color_depth": 0,
    "java_enabled": true,
    "java_script_enabled": true,
    "language": "language",
    "screen_height": 0,
    "screen_width": 0,
    "time_zone": 0,
    "ip_address": "ip_address",
    "accept_header": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8",
    "user_agent": "user_agent",
    "os_type": "os_type",
    "os_version": "os_version",
    "device_model": "device_model",
    "accept_language": "accept_language",
    "referer": "referer"
  },
  "payment_channel": "ecommerce",
  "payment_method_id": "payment_method_id",
  "network_transaction_id": "network_transaction_id",
  "payment_method_status": "active",
  "updated": "2022-09-10T10:11:12Z",
  "split_payments": {
    "stripe_split_payment": {
      "charge_id": "charge_id",
      "charge_type": {
        "Stripe": "direct"
      },
      "application_fees": 6540,
      "transfer_account_id": "transfer_account_id"
    }
  },
  "frm_metadata": {},
  "extended_authorization_applied": true,
  "extended_authorization_last_applied_at": "2022-09-10T10:11:12Z",
  "request_extended_authorization": false,
  "capture_before": "2024-08-25T15:00:00Z",
  "merchant_order_reference_id": "Custom_Order_id_123",
  "order_tax_amount": 0,
  "connector_mandate_id": "connector_mandate_id",
  "card_discovery": "manual",
  "force_3ds_challenge": true,
  "force_3ds_challenge_trigger": true,
  "issuer_error_code": "issuer_error_code",
  "issuer_error_message": "issuer_error_message",
  "is_iframe_redirection_enabled": true,
  "whole_connector_response": "whole_connector_response",
  "enable_partial_authorization": false,
  "enable_overcapture": true,
  "is_overcapture_enabled": true,
  "network_details": {
    "network_advice_code": "network_advice_code"
  },
  "is_stored_credential": true,
  "mit_category": "installment",
  "billing_descriptor": {
    "name": "The Online Retailer",
    "city": "San Francisco",
    "phone": "9123456789",
    "statement_descriptor": "statement_descriptor",
    "statement_descriptor_suffix": "statement_descriptor_suffix",
    "reference": "reference"
  },
  "tokenization": "skip_psp",
  "partner_merchant_identifier_details": {
    "partner_details": {
      "name": "name",
      "version": "1.0.0",
      "integrator": "integrator"
    },
    "merchant_details": {
      "name": "name",
      "version": "version"
    }
  },
  "payment_method_tokenization_details": {
    "payment_method_id": "payment_method_id",
    "payment_method_status": "active",
    "psp_tokenization": true,
    "network_tokenization": true,
    "network_transaction_id": "network_transaction_id",
    "is_eligible_for_mit_payment": true
  },
  "installment_options": [
    {
      "payment_method": "card",
      "installments": [
        {
          "number_of_installments": "number_of_installments",
          "billing_frequency": "month",
          "interest_rate": 0
        }
      ]
    }
  ],
  "installment_data": {
    "number_of_installments": 0,
    "billing_frequency": "month",
    "installment_interest": 0
  },
  "customer_statistics": {
    "profile_id": "profile_id",
    "profile_name": "profile_name",
    "first_successful_payment_at": "first_successful_payment_at",
    "payments_count": 0,
    "payments_amount": 0,
    "refunds_count": 0,
    "refunds_amount": 0,
    "payouts_count": 0,
    "payouts_amount": 0,
    "currency": "AED"
  },
  "fee_summary": {
    "currency": "currency",
    "base_amount": 0,
    "merchant_commission_amount": 0,
    "provider_cost": 0,
    "margin": 0,
    "merchant_commission_rate": {},
    "provider_cost_rate": {},
    "merchant_commission_rule": "merchant_commission_rule",
    "provider_cost_rule": "provider_cost_rule"
  }
}

json

application/json

Payments - Session token

POST

https://paysw-wiki.lab.next-on.pro/dev-router

/payments/session_tokens

api-key (header)

Creates a session object or a session token for wallets like Apple Pay, Google Pay, etc. These tokens are used by Hyperswitch's SDK to initiate these wallets' SDK.

Payments - Session token › Request Body

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.

Payments - Session token › Responses

Payment session object created or session token was retrieved from wallets

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

POST/payments/session_tokens

curl https://paysw-wiki.lab.next-on.pro/dev-router/payments/session_tokens \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'api-key: <api-key>' \
  --data '{
  "payment_id": "payment_id",
  "client_secret": "client_secret",
  "wallets": [
    "ach"
  ],
  "merchant_connector_details": {
    "creds_identifier": "creds_identifier",
    "encoded_data": {
      "connector_account_details": {},
      "metadata": {},
      "card_testing_guard_config": {}
    }
  }
}'

Example Request Body

{
  "payment_id": "payment_id",
  "client_secret": "client_secret",
  "wallets": [
    "ach"
  ],
  "merchant_connector_details": {
    "creds_identifier": "creds_identifier",
    "encoded_data": {
      "connector_account_details": {},
      "metadata": {},
      "card_testing_guard_config": {}
    }
  }
}

json

Example Responses

{
  "payment_id": "payment_id",
  "client_secret": "client_secret",
  "session_token": [
    {
      "wallet_name": "google_pay"
    }
  ]
}

json

application/json

Payments - Cancel

POST

https://paysw-wiki.lab.next-on.pro/dev-router

/payments/{payment_id}/cancel

api-key (header)

A Payment could can be cancelled when it is in one of these statuses: requires_payment_method, requires_capture, requires_confirmation, requires_customer_action.

Payments - Cancel › path Parameters

payment_id

string · required

The identifier for payment

Payments - Cancel › Request Body

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

Payments - Cancel › Responses

Payment canceled

No data returned

Payments - Cancel Post Capture

POST

https://paysw-wiki.lab.next-on.pro/dev-router

/payments/{payment_id}/cancel_post_capture

api-key (header)

A Payment could can be cancelled when it is in one of these statuses: succeeded, partially_captured, partially_captured_and_capturable.

Payments - Cancel Post Capture › path Parameters

payment_id

string · required

The identifier for payment

Payments - Cancel Post Capture › Request Body

Request to cancel a payment when the payment is already captured

PaymentsCancelPostCaptureRequest

cancellation_reason

string | null

The reason for the payment cancel

Payments - Cancel Post Capture › Responses

Payment canceled post capture

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

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

Example: 6540

amount_capturable

integer · int64 · min: 100 · required

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

Example: 6540

initiator

string · enum

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

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

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

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.

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

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:

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

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

network_transaction_id

string | null

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

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

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

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

POST/payments/{payment_id}/cancel_post_capture

curl https://paysw-wiki.lab.next-on.pro/dev-router/payments/:payment_id/cancel_post_capture \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'api-key: <api-key>' \
  --data '{
  "cancellation_reason": "requested_by_customer"
}'

Example Request Body

{
  "cancellation_reason": "requested_by_customer"
}

json

application/json

Example Responses

{
  "payment_id": "pay_mbabizu24mvu3mela5njyhpit4",
  "merchant_id": "merchant_1668273825",
  "status": "requires_confirmation",
  "amount": 6540,
  "net_amount": 6540,
  "shipping_cost": 6540,
  "amount_capturable": 6540,
  "amount_received": 6540,
  "processor_merchant_id": "merchant_1689512302",
  "initiator": "platform",
  "sdk_authorization": "cHJvZmlsZV9pZD1wcm9mXzEyMyxwdWJsaXNoYWJsZV9rZXk9cGtfbGl2ZV8xMjM=",
  "connector": "stripe",
  "state_metadata": {
    "total_refunded_amount": 0,
    "total_disputed_amount": 0,
    "post_capture_void": {
      "status": "succeeded",
      "connector_reference_id": "connector_reference_id",
      "description": "description",
      "updated_at": "2024-08-25T15:00:00Z"
    }
  },
  "client_secret": "pay_U42c409qyHwOkWo3vK60_secret_el9ksDkiB8hi6j9N78yo",
  "created": "2022-09-10T10:11:12Z",
  "modified_at": "2022-09-10T10:11:12Z",
  "currency": "AED",
  "customer_id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
  "customer": {
    "id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
    "name": "John Doe",
    "email": "johntest@test.com",
    "phone": "9123456789",
    "phone_country_code": "+1",
    "customer_document_details": {
      "document_type": "cpf",
      "document_number": "12345678911"
    }
  },
  "description": "It's my first payment request",
  "refunds": [
    {
      "refund_id": "refund_id",
      "payment_id": "payment_id",
      "amount": 6540,
      "currency": "currency",
      "status": "succeeded",
      "reason": "reason",
      "metadata": {},
      "error_message": "error_message",
      "error_code": "error_code",
      "unified_code": "unified_code",
      "unified_message": "unified_message",
      "created_at": "2024-08-25T15:00:00Z",
      "updated_at": "2024-08-25T15:00:00Z",
      "connector": "stripe",
      "profile_id": "profile_id",
      "merchant_connector_id": "merchant_connector_id",
      "split_refunds": {
        "stripe_split_refund": {
          "revert_platform_fee": true,
          "revert_transfer": true
        }
      },
      "issuer_error_code": "issuer_error_code",
      "issuer_error_message": "issuer_error_message",
      "raw_connector_response": "raw_connector_response",
      "connector_refund_id": "connector_refund_id",
      "fee_summary": {
        "currency": "currency",
        "base_amount": 0,
        "merchant_commission_amount": 0,
        "provider_cost": 0,
        "margin": 0,
        "merchant_commission_rate": {},
        "provider_cost_rate": {},
        "merchant_commission_rule": "merchant_commission_rule",
        "provider_cost_rule": "provider_cost_rule"
      }
    }
  ],
  "disputes": [
    {
      "dispute_id": "dispute_id",
      "amount": "amount",
      "dispute_stage": "pre_dispute",
      "dispute_status": "dispute_opened",
      "connector_status": "connector_status",
      "connector_dispute_id": "connector_dispute_id",
      "connector_reason": "connector_reason",
      "connector_reason_code": "connector_reason_code",
      "challenge_required_by": "2024-08-25T15:00:00Z",
      "connector_created_at": "2024-08-25T15:00:00Z",
      "connector_updated_at": "2024-08-25T15:00:00Z",
      "created_at": "2024-08-25T15:00:00Z"
    }
  ],
  "attempts": [
    {
      "attempt_id": "attempt_id",
      "status": "started",
      "amount": 6540,
      "order_tax_amount": 6540,
      "currency": "AED",
      "connector": "connector",
      "merchant_connector_id": "merchant_connector_id",
      "error_message": "error_message",
      "payment_method": "card",
      "connector_transaction_id": "connector_transaction_id",
      "capture_method": "automatic",
      "authentication_type": "three_ds",
      "created_at": "2022-09-10T10:11:12Z",
      "modified_at": "2022-09-10T10:11:12Z",
      "cancellation_reason": "cancellation_reason",
      "mandate_id": "mandate_id",
      "error_code": "error_code",
      "payment_token": "payment_token",
      "connector_metadata": {},
      "payment_experience": "redirect_to_url",
      "payment_method_type": "ach",
      "reference_id": "993672945374576J",
      "unified_code": "unified_code",
      "unified_message": "unified_message",
      "client_source": "client_source",
      "client_version": "client_version",
      "error_details": {
        "unified_details": {
          "category": "UE_1000",
          "message": "message",
          "standardised_code": "account_closed_or_invalid",
          "description": "description",
          "user_guidance_message": "user_guidance_message",
          "recommended_action": "do_not_retry"
        },
        "issuer_details": {
          "code": "code",
          "message": "message",
          "network_details": {
            "name": "Visa",
            "advice_code": "advice_code",
            "advice_message": "advice_message"
          }
        },
        "connector_details": {
          "code": "code",
          "message": "message",
          "reason": "reason"
        }
      },
      "fee_details": [
        {
          "capture_id": "capture_id",
          "reference_id": "reference_id",
          "created_at": "2024-01-01T00:00:00Z",
          "currency": "currency",
          "base_amount": 0,
          "merchant_commission_amount": 0,
          "provider_cost": 0,
          "margin": 0,
          "merchant_commission_rate": {},
          "provider_cost_rate": {},
          "merchant_commission_rule": "merchant_commission_rule",
          "provider_cost_rule": "provider_cost_rule"
        }
      ]
    }
  ],
  "captures": [
    {
      "capture_id": "capture_id",
      "status": "started",
      "amount": 6540,
      "currency": "AED",
      "connector": "connector",
      "authorized_attempt_id": "authorized_attempt_id",
      "connector_capture_id": "connector_capture_id",
      "capture_sequence": 0,
      "error_message": "error_message",
      "error_code": "error_code",
      "error_reason": "error_reason",
      "reference_id": "reference_id"
    }
  ],
  "mandate_id": "mandate_iwer89rnjef349dni3",
  "mandate_data": {
    "update_mandate_id": "update_mandate_id",
    "customer_acceptance": {
      "acceptance_type": "online",
      "accepted_at": "2022-09-10T10:11:12Z",
      "online": {
        "ip_address": "123.32.25.123",
        "user_agent": "user_agent"
      }
    },
    "mandate_type": {
      "single_use": {
        "amount": 6540,
        "currency": "AED",
        "start_date": "2022-09-10T00:00:00Z",
        "end_date": "2023-09-10T23:59:59Z",
        "metadata": {}
      }
    }
  },
  "setup_future_usage": "off_session",
  "off_session": true,
  "capture_on": "2022-09-10T10:11:12Z",
  "capture_method": "automatic",
  "payment_method": "card",
  "payment_method_data": {
    "billing": {
      "address": {
        "city": "New York",
        "country": "AF",
        "line1": "123, King Street",
        "line2": "Powelson Avenue",
        "line3": "Bridgewater",
        "zip": "08807",
        "state": "New York",
        "first_name": "John",
        "last_name": "Doe",
        "origin_zip": "08807"
      },
      "phone": {
        "number": "9123456789",
        "country_code": "+1"
      },
      "email": "email"
    }
  },
  "payment_token": "187282ab-40ef-47a9-9206-5099ba31e432",
  "shipping": {
    "address": {
      "city": "New York",
      "country": "AF",
      "line1": "123, King Street",
      "line2": "Powelson Avenue",
      "line3": "Bridgewater",
      "zip": "08807",
      "state": "New York",
      "first_name": "John",
      "last_name": "Doe",
      "origin_zip": "08807"
    },
    "phone": {
      "number": "9123456789",
      "country_code": "+1"
    },
    "email": "email"
  },
  "billing": {
    "address": {
      "city": "New York",
      "country": "AF",
      "line1": "123, King Street",
      "line2": "Powelson Avenue",
      "line3": "Bridgewater",
      "zip": "08807",
      "state": "New York",
      "first_name": "John",
      "last_name": "Doe",
      "origin_zip": "08807"
    },
    "phone": {
      "number": "9123456789",
      "country_code": "+1"
    },
    "email": "email"
  },
  "order_details": "[{\n        \"product_name\": \"gillete creme\",\n        \"quantity\": 15,\n        \"amount\" : 900\n    }]",
  "email": "johntest@test.com",
  "name": "John Test",
  "phone": "9123456789",
  "return_url": "https://hyperswitch.io",
  "authentication_type": "three_ds",
  "statement_descriptor_name": "Hyperswitch Router",
  "statement_descriptor_suffix": "Payment for shoes purchase",
  "next_action": {
    "redirect_to_url": "redirect_to_url",
    "type": "redirect_to_url"
  },
  "cancellation_reason": "cancellation_reason",
  "error_code": "E0001",
  "error_message": "Failed while verifying the card",
  "unified_code": "unified_code",
  "unified_message": "unified_message",
  "error_details": {
    "unified_details": {
      "category": "UE_1000",
      "message": "message",
      "standardised_code": "account_closed_or_invalid",
      "description": "description",
      "user_guidance_message": "user_guidance_message",
      "recommended_action": "do_not_retry"
    },
    "issuer_details": {
      "code": "code",
      "message": "message",
      "network_details": {
        "name": "Visa",
        "advice_code": "advice_code",
        "advice_message": "advice_message"
      }
    },
    "connector_details": {
      "code": "code",
      "message": "message",
      "reason": "reason"
    }
  },
  "payment_experience": "redirect_to_url",
  "payment_method_type": "ach",
  "connector_label": "stripe_US_food",
  "business_country": "AF",
  "business_label": "business_label",
  "business_sub_label": "business_sub_label",
  "allowed_payment_method_types": [
    "ach"
  ],
  "manual_retry_allowed": true,
  "connector_transaction_id": "993672945374576J",
  "frm_message": {
    "frm_name": "frm_name",
    "frm_transaction_id": "frm_transaction_id",
    "frm_transaction_type": "frm_transaction_type",
    "frm_status": "frm_status",
    "frm_score": 0,
    "frm_reason": {},
    "frm_error": "frm_error"
  },
  "metadata": {},
  "connector_metadata": {
    "apple_pay": {
      "session_token_data": {
        "certificate": "certificate",
        "certificate_keys": "certificate_keys",
        "merchant_identifier": "merchant_identifier",
        "display_name": "display_name",
        "initiative": "web",
        "initiative_context": "initiative_context",
        "merchant_business_country": "AF"
      }
    },
    "airwallex": {
      "payload": "payload"
    },
    "noon": {
      "order_category": "order_category"
    },
    "braintree": {
      "merchant_account_id": "merchant_account_id",
      "merchant_config_currency": "merchant_config_currency"
    },
    "adyen": {
      "testing": {
        "holder_name": "holder_name"
      }
    },
    "peachpayments": {
      "rrn": "rrn"
    }
  },
  "connector_response_metadata": {
    "santander": {
      "end_to_end_id": "end_to_end_id"
    }
  },
  "feature_metadata": {
    "redirect_response": {
      "param": "param",
      "json_payload": {}
    },
    "search_tags": [
      "string"
    ],
    "apple_pay_recurring_details": {
      "payment_description": "payment_description",
      "regular_billing": {
        "label": "label",
        "recurring_payment_start_date": "2023-09-10T23:59:59Z",
        "recurring_payment_end_date": "2023-09-10T23:59:59Z",
        "recurring_payment_interval_unit": "year",
        "recurring_payment_interval_count": 0
      },
      "billing_agreement": "billing_agreement",
      "management_url": "https://hyperswitch.io"
    },
    "pix_additional_details": {
      "immediate": {
        "time": 0,
        "pix_key": {
          "type": "cpf",
          "value": "value"
        }
      }
    },
    "boleto_additional_details": {
      "due_date": "2026-12-31",
      "document_kind": "commercial_invoice",
      "payment_type": "fixed_amount",
      "covenant_code": "3568253",
      "pix_key": {
        "type": "cpf",
        "value": "value"
      }
    }
  },
  "reference_id": "993672945374576J",
  "payment_link": {
    "link": "link",
    "secure_link": "secure_link",
    "payment_link_id": "payment_link_id"
  },
  "profile_id": "profile_id",
  "surcharge_details": {
    "surcharge_amount": 6540,
    "tax_amount": 0
  },
  "attempt_count": 0,
  "merchant_decision": "merchant_decision",
  "merchant_connector_id": "merchant_connector_id",
  "incremental_authorization_allowed": true,
  "authorization_count": 0,
  "incremental_authorizations": [
    {
      "authorization_id": "authorization_id",
      "amount": 6540,
      "status": "success",
      "error_code": "error_code",
      "error_message": "error_message",
      "previously_authorized_amount": 0
    }
  ],
  "external_authentication_details": {
    "authentication_flow": "challenge",
    "electronic_commerce_indicator": "electronic_commerce_indicator",
    "status": "started",
    "ds_transaction_id": "ds_transaction_id",
    "version": "version",
    "error_code": "error_code",
    "error_message": "error_message"
  },
  "external_3ds_authentication_attempted": true,
  "expires_on": "2022-09-10T10:11:12Z",
  "fingerprint": "fingerprint",
  "browser_info": {
    "color_depth": 0,
    "java_enabled": true,
    "java_script_enabled": true,
    "language": "language",
    "screen_height": 0,
    "screen_width": 0,
    "time_zone": 0,
    "ip_address": "ip_address",
    "accept_header": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8",
    "user_agent": "user_agent",
    "os_type": "os_type",
    "os_version": "os_version",
    "device_model": "device_model",
    "accept_language": "accept_language",
    "referer": "referer"
  },
  "payment_channel": "ecommerce",
  "payment_method_id": "payment_method_id",
  "network_transaction_id": "network_transaction_id",
  "payment_method_status": "active",
  "updated": "2022-09-10T10:11:12Z",
  "split_payments": {
    "stripe_split_payment": {
      "charge_id": "charge_id",
      "charge_type": {
        "Stripe": "direct"
      },
      "application_fees": 6540,
      "transfer_account_id": "transfer_account_id"
    }
  },
  "frm_metadata": {},
  "extended_authorization_applied": true,
  "extended_authorization_last_applied_at": "2022-09-10T10:11:12Z",
  "request_extended_authorization": false,
  "capture_before": "2024-08-25T15:00:00Z",
  "merchant_order_reference_id": "Custom_Order_id_123",
  "order_tax_amount": 0,
  "connector_mandate_id": "connector_mandate_id",
  "card_discovery": "manual",
  "force_3ds_challenge": true,
  "force_3ds_challenge_trigger": true,
  "issuer_error_code": "issuer_error_code",
  "issuer_error_message": "issuer_error_message",
  "is_iframe_redirection_enabled": true,
  "whole_connector_response": "whole_connector_response",
  "enable_partial_authorization": false,
  "enable_overcapture": true,
  "is_overcapture_enabled": true,
  "network_details": {
    "network_advice_code": "network_advice_code"
  },
  "is_stored_credential": true,
  "mit_category": "installment",
  "billing_descriptor": {
    "name": "The Online Retailer",
    "city": "San Francisco",
    "phone": "9123456789",
    "statement_descriptor": "statement_descriptor",
    "statement_descriptor_suffix": "statement_descriptor_suffix",
    "reference": "reference"
  },
  "tokenization": "skip_psp",
  "partner_merchant_identifier_details": {
    "partner_details": {
      "name": "name",
      "version": "1.0.0",
      "integrator": "integrator"
    },
    "merchant_details": {
      "name": "name",
      "version": "version"
    }
  },
  "payment_method_tokenization_details": {
    "payment_method_id": "payment_method_id",
    "payment_method_status": "active",
    "psp_tokenization": true,
    "network_tokenization": true,
    "network_transaction_id": "network_transaction_id",
    "is_eligible_for_mit_payment": true
  },
  "installment_options": [
    {
      "payment_method": "card",
      "installments": [
        {
          "number_of_installments": "number_of_installments",
          "billing_frequency": "month",
          "interest_rate": 0
        }
      ]
    }
  ],
  "installment_data": {
    "number_of_installments": 0,
    "billing_frequency": "month",
    "installment_interest": 0
  },
  "customer_statistics": {
    "profile_id": "profile_id",
    "profile_name": "profile_name",
    "first_successful_payment_at": "first_successful_payment_at",
    "payments_count": 0,
    "payments_amount": 0,
    "refunds_count": 0,
    "refunds_amount": 0,
    "payouts_count": 0,
    "payouts_amount": 0,
    "currency": "AED"
  },
  "fee_summary": {
    "currency": "currency",
    "base_amount": 0,
    "merchant_commission_amount": 0,
    "provider_cost": 0,
    "margin": 0,
    "merchant_commission_rate": {},
    "provider_cost_rate": {},
    "merchant_commission_rule": "merchant_commission_rule",
    "provider_cost_rule": "provider_cost_rule"
  }
}

json

application/json

Payments - Extended Authorization

POST

https://paysw-wiki.lab.next-on.pro/dev-router

/payments/{payment_id}/extend_authorization

api-key (header)

Extended authorization is available for payments currently in the requires_capture status Call this endpoint to increase the authorization validity period

Payments - Extended Authorization › path Parameters

payment_id

string · required

The identifier for payment

Payments - Extended Authorization › Responses

Extended authorization for the payment

No data returned

Payments - List

GET

https://paysw-wiki.lab.next-on.pro/dev-router

/payments/list

api-key (header)

To list the payments

Payments - List › query Parameters

customer_id

string | null

The identifier for the customer

starting_after

string | null

A cursor for use in pagination, fetch the next list after some object

ending_before

string | null

A cursor for use in pagination, fetch the previous list before some object

limit

integer | null · int64

Limit on the number of objects to return

created

string | null · date-time

The time at which payment is created

created_lt

string | null · date-time

Time less than the payment created time

created_gt

string | null · date-time

Time greater than the payment created time

created_lte

string | null · date-time

Time less than or equals to the payment created time

created_gte

string | null · date-time

Time greater than or equals to the payment created time

Payments - List › Responses

Successfully retrieved a payment list

PaymentListResponse[]

PaymentListResponse

size

integer · min: 0 · required

The number of payments included in the list

PaymentsResponse[] · required

GET/payments/list

curl https://paysw-wiki.lab.next-on.pro/dev-router/payments/list \
  --header 'api-key: <api-key>'

Example Responses

[
  {
    "size": 0,
    "data": [
      {
        "payment_id": "pay_mbabizu24mvu3mela5njyhpit4",
        "merchant_id": "merchant_1668273825",
        "status": "requires_confirmation",
        "amount": 6540,
        "net_amount": 6540,
        "shipping_cost": 6540,
        "amount_capturable": 6540,
        "amount_received": 6540,
        "processor_merchant_id": "merchant_1689512302",
        "initiator": "platform",
        "sdk_authorization": "cHJvZmlsZV9pZD1wcm9mXzEyMyxwdWJsaXNoYWJsZV9rZXk9cGtfbGl2ZV8xMjM=",
        "connector": "stripe",
        "state_metadata": {
          "total_refunded_amount": 0,
          "total_disputed_amount": 0,
          "post_capture_void": {
            "status": "succeeded",
            "connector_reference_id": "connector_reference_id",
            "description": "description",
            "updated_at": "2024-08-25T15:00:00Z"
          }
        },
        "client_secret": "pay_U42c409qyHwOkWo3vK60_secret_el9ksDkiB8hi6j9N78yo",
        "created": "2022-09-10T10:11:12Z",
        "modified_at": "2022-09-10T10:11:12Z",
        "currency": "AED",
        "customer_id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
        "customer": {
          "id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
          "name": "John Doe",
          "email": "johntest@test.com",
          "phone": "9123456789",
          "phone_country_code": "+1",
          "customer_document_details": {
            "document_type": "cpf",
            "document_number": "12345678911"
          }
        },
        "description": "It's my first payment request",
        "refunds": [
          {
            "refund_id": "refund_id",
            "payment_id": "payment_id",
            "amount": 6540,
            "currency": "currency",
            "status": "succeeded",
            "reason": "reason",
            "metadata": {},
            "error_message": "error_message",
            "error_code": "error_code",
            "unified_code": "unified_code",
            "unified_message": "unified_message",
            "created_at": "2024-08-25T15:00:00Z",
            "updated_at": "2024-08-25T15:00:00Z",
            "connector": "stripe",
            "profile_id": "profile_id",
            "merchant_connector_id": "merchant_connector_id",
            "split_refunds": {
              "stripe_split_refund": {
                "revert_platform_fee": true,
                "revert_transfer": true
              }
            },
            "issuer_error_code": "issuer_error_code",
            "issuer_error_message": "issuer_error_message",
            "raw_connector_response": "raw_connector_response",
            "connector_refund_id": "connector_refund_id",
            "fee_summary": {
              "currency": "currency",
              "base_amount": 0,
              "merchant_commission_amount": 0,
              "provider_cost": 0,
              "margin": 0,
              "merchant_commission_rate": {},
              "provider_cost_rate": {},
              "merchant_commission_rule": "merchant_commission_rule",
              "provider_cost_rule": "provider_cost_rule"
            }
          }
        ],
        "disputes": [
          {
            "dispute_id": "dispute_id",
            "amount": "amount",
            "dispute_stage": "pre_dispute",
            "dispute_status": "dispute_opened",
            "connector_status": "connector_status",
            "connector_dispute_id": "connector_dispute_id",
            "connector_reason": "connector_reason",
            "connector_reason_code": "connector_reason_code",
            "challenge_required_by": "2024-08-25T15:00:00Z",
            "connector_created_at": "2024-08-25T15:00:00Z",
            "connector_updated_at": "2024-08-25T15:00:00Z",
            "created_at": "2024-08-25T15:00:00Z"
          }
        ],
        "attempts": [
          {
            "attempt_id": "attempt_id",
            "status": "started",
            "amount": 6540,
            "order_tax_amount": 6540,
            "currency": "AED",
            "connector": "connector",
            "merchant_connector_id": "merchant_connector_id",
            "error_message": "error_message",
            "payment_method": "card",
            "connector_transaction_id": "connector_transaction_id",
            "capture_method": "automatic",
            "authentication_type": "three_ds",
            "created_at": "2022-09-10T10:11:12Z",
            "modified_at": "2022-09-10T10:11:12Z",
            "cancellation_reason": "cancellation_reason",
            "mandate_id": "mandate_id",
            "error_code": "error_code",
            "payment_token": "payment_token",
            "connector_metadata": {},
            "payment_experience": "redirect_to_url",
            "payment_method_type": "ach",
            "reference_id": "993672945374576J",
            "unified_code": "unified_code",
            "unified_message": "unified_message",
            "client_source": "client_source",
            "client_version": "client_version",
            "error_details": {
              "unified_details": {
                "category": "UE_1000",
                "message": "message",
                "standardised_code": "account_closed_or_invalid",
                "description": "description",
                "user_guidance_message": "user_guidance_message",
                "recommended_action": "do_not_retry"
              },
              "issuer_details": {
                "code": "code",
                "message": "message",
                "network_details": {
                  "name": "Visa",
                  "advice_code": "advice_code",
                  "advice_message": "advice_message"
                }
              },
              "connector_details": {
                "code": "code",
                "message": "message",
                "reason": "reason"
              }
            },
            "fee_details": [
              {
                "capture_id": "capture_id",
                "reference_id": "reference_id",
                "created_at": "2024-01-01T00:00:00Z",
                "currency": "currency",
                "base_amount": 0,
                "merchant_commission_amount": 0,
                "provider_cost": 0,
                "margin": 0,
                "merchant_commission_rate": {},
                "provider_cost_rate": {},
                "merchant_commission_rule": "merchant_commission_rule",
                "provider_cost_rule": "provider_cost_rule"
              }
            ]
          }
        ],
        "captures": [
          {
            "capture_id": "capture_id",
            "status": "started",
            "amount": 6540,
            "currency": "AED",
            "connector": "connector",
            "authorized_attempt_id": "authorized_attempt_id",
            "connector_capture_id": "connector_capture_id",
            "capture_sequence": 0,
            "error_message": "error_message",
            "error_code": "error_code",
            "error_reason": "error_reason",
            "reference_id": "reference_id"
          }
        ],
        "mandate_id": "mandate_iwer89rnjef349dni3",
        "mandate_data": {
          "update_mandate_id": "update_mandate_id",
          "customer_acceptance": {
            "acceptance_type": "online",
            "accepted_at": "2022-09-10T10:11:12Z",
            "online": {
              "ip_address": "123.32.25.123",
              "user_agent": "user_agent"
            }
          },
          "mandate_type": {
            "single_use": {
              "amount": 6540,
              "currency": "AED",
              "start_date": "2022-09-10T00:00:00Z",
              "end_date": "2023-09-10T23:59:59Z",
              "metadata": {}
            }
          }
        },
        "setup_future_usage": "off_session",
        "off_session": true,
        "capture_on": "2022-09-10T10:11:12Z",
        "capture_method": "automatic",
        "payment_method": "card",
        "payment_method_data": {
          "billing": {
            "address": {
              "city": "New York",
              "country": "AF",
              "line1": "123, King Street",
              "line2": "Powelson Avenue",
              "line3": "Bridgewater",
              "zip": "08807",
              "state": "New York",
              "first_name": "John",
              "last_name": "Doe",
              "origin_zip": "08807"
            },
            "phone": {
              "number": "9123456789",
              "country_code": "+1"
            },
            "email": "email"
          }
        },
        "payment_token": "187282ab-40ef-47a9-9206-5099ba31e432",
        "shipping": {
          "address": {
            "city": "New York",
            "country": "AF",
            "line1": "123, King Street",
            "line2": "Powelson Avenue",
            "line3": "Bridgewater",
            "zip": "08807",
            "state": "New York",
            "first_name": "John",
            "last_name": "Doe",
            "origin_zip": "08807"
          },
          "phone": {
            "number": "9123456789",
            "country_code": "+1"
          },
          "email": "email"
        },
        "billing": {
          "address": {
            "city": "New York",
            "country": "AF",
            "line1": "123, King Street",
            "line2": "Powelson Avenue",
            "line3": "Bridgewater",
            "zip": "08807",
            "state": "New York",
            "first_name": "John",
            "last_name": "Doe",
            "origin_zip": "08807"
          },
          "phone": {
            "number": "9123456789",
            "country_code": "+1"
          },
          "email": "email"
        },
        "order_details": "[{\n        \"product_name\": \"gillete creme\",\n        \"quantity\": 15,\n        \"amount\" : 900\n    }]",
        "email": "johntest@test.com",
        "name": "John Test",
        "phone": "9123456789",
        "return_url": "https://hyperswitch.io",
        "authentication_type": "three_ds",
        "statement_descriptor_name": "Hyperswitch Router",
        "statement_descriptor_suffix": "Payment for shoes purchase",
        "next_action": {
          "redirect_to_url": "redirect_to_url",
          "type": "redirect_to_url"
        },
        "cancellation_reason": "cancellation_reason",
        "error_code": "E0001",
        "error_message": "Failed while verifying the card",
        "unified_code": "unified_code",
        "unified_message": "unified_message",
        "error_details": {
          "unified_details": {
            "category": "UE_1000",
            "message": "message",
            "standardised_code": "account_closed_or_invalid",
            "description": "description",
            "user_guidance_message": "user_guidance_message",
            "recommended_action": "do_not_retry"
          },
          "issuer_details": {
            "code": "code",
            "message": "message",
            "network_details": {
              "name": "Visa",
              "advice_code": "advice_code",
              "advice_message": "advice_message"
            }
          },
          "connector_details": {
            "code": "code",
            "message": "message",
            "reason": "reason"
          }
        },
        "payment_experience": "redirect_to_url",
        "payment_method_type": "ach",
        "connector_label": "stripe_US_food",
        "business_country": "AF",
        "business_label": "business_label",
        "business_sub_label": "business_sub_label",
        "allowed_payment_method_types": [
          "ach"
        ],
        "manual_retry_allowed": true,
        "connector_transaction_id": "993672945374576J",
        "frm_message": {
          "frm_name": "frm_name",
          "frm_transaction_id": "frm_transaction_id",
          "frm_transaction_type": "frm_transaction_type",
          "frm_status": "frm_status",
          "frm_score": 0,
          "frm_reason": {},
          "frm_error": "frm_error"
        },
        "metadata": {},
        "connector_metadata": {
          "apple_pay": {
            "session_token_data": {
              "certificate": "certificate",
              "certificate_keys": "certificate_keys",
              "merchant_identifier": "merchant_identifier",
              "display_name": "display_name",
              "initiative": "web",
              "initiative_context": "initiative_context",
              "merchant_business_country": "AF"
            }
          },
          "airwallex": {
            "payload": "payload"
          },
          "noon": {
            "order_category": "order_category"
          },
          "braintree": {
            "merchant_account_id": "merchant_account_id",
            "merchant_config_currency": "merchant_config_currency"
          },
          "adyen": {
            "testing": {
              "holder_name": "holder_name"
            }
          },
          "peachpayments": {
            "rrn": "rrn"
          }
        },
        "connector_response_metadata": {
          "santander": {
            "end_to_end_id": "end_to_end_id"
          }
        },
        "feature_metadata": {
          "redirect_response": {
            "param": "param",
            "json_payload": {}
          },
          "search_tags": [
            "string"
          ],
          "apple_pay_recurring_details": {
            "payment_description": "payment_description",
            "regular_billing": {
              "label": "label",
              "recurring_payment_start_date": "2023-09-10T23:59:59Z",
              "recurring_payment_end_date": "2023-09-10T23:59:59Z",
              "recurring_payment_interval_unit": "year",
              "recurring_payment_interval_count": 0
            },
            "billing_agreement": "billing_agreement",
            "management_url": "https://hyperswitch.io"
          },
          "pix_additional_details": {
            "immediate": {
              "time": 0,
              "pix_key": {
                "type": "cpf",
                "value": "value"
              }
            }
          },
          "boleto_additional_details": {
            "due_date": "2026-12-31",
            "document_kind": "commercial_invoice",
            "payment_type": "fixed_amount",
            "covenant_code": "3568253",
            "pix_key": {
              "type": "cpf",
              "value": "value"
            }
          }
        },
        "reference_id": "993672945374576J",
        "payment_link": {
          "link": "link",
          "secure_link": "secure_link",
          "payment_link_id": "payment_link_id"
        },
        "profile_id": "profile_id",
        "surcharge_details": {
          "surcharge_amount": 6540,
          "tax_amount": 0
        },
        "attempt_count": 0,
        "merchant_decision": "merchant_decision",
        "merchant_connector_id": "merchant_connector_id",
        "incremental_authorization_allowed": true,
        "authorization_count": 0,
        "incremental_authorizations": [
          {
            "authorization_id": "authorization_id",
            "amount": 6540,
            "status": "success",
            "error_code": "error_code",
            "error_message": "error_message",
            "previously_authorized_amount": 0
          }
        ],
        "external_authentication_details": {
          "authentication_flow": "challenge",
          "electronic_commerce_indicator": "electronic_commerce_indicator",
          "status": "started",
          "ds_transaction_id": "ds_transaction_id",
          "version": "version",
          "error_code": "error_code",
          "error_message": "error_message"
        },
        "external_3ds_authentication_attempted": true,
        "expires_on": "2022-09-10T10:11:12Z",
        "fingerprint": "fingerprint",
        "browser_info": {
          "color_depth": 0,
          "java_enabled": true,
          "java_script_enabled": true,
          "language": "language",
          "screen_height": 0,
          "screen_width": 0,
          "time_zone": 0,
          "ip_address": "ip_address",
          "accept_header": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8",
          "user_agent": "user_agent",
          "os_type": "os_type",
          "os_version": "os_version",
          "device_model": "device_model",
          "accept_language": "accept_language",
          "referer": "referer"
        },
        "payment_channel": "ecommerce",
        "payment_method_id": "payment_method_id",
        "network_transaction_id": "network_transaction_id",
        "payment_method_status": "active",
        "updated": "2022-09-10T10:11:12Z",
        "split_payments": {
          "stripe_split_payment": {
            "charge_id": "charge_id",
            "charge_type": {
              "Stripe": "direct"
            },
            "application_fees": 6540,
            "transfer_account_id": "transfer_account_id"
          }
        },
        "frm_metadata": {},
        "extended_authorization_applied": true,
        "extended_authorization_last_applied_at": "2022-09-10T10:11:12Z",
        "request_extended_authorization": false,
        "capture_before": "2024-08-25T15:00:00Z",
        "merchant_order_reference_id": "Custom_Order_id_123",
        "order_tax_amount": 0,
        "connector_mandate_id": "connector_mandate_id",
        "card_discovery": "manual",
        "force_3ds_challenge": true,
        "force_3ds_challenge_trigger": true,
        "issuer_error_code": "issuer_error_code",
        "issuer_error_message": "issuer_error_message",
        "is_iframe_redirection_enabled": true,
        "whole_connector_response": "whole_connector_response",
        "enable_partial_authorization": false,
        "enable_overcapture": true,
        "is_overcapture_enabled": true,
        "network_details": {
          "network_advice_code": "network_advice_code"
        },
        "is_stored_credential": true,
        "mit_category": "installment",
        "billing_descriptor": {
          "name": "The Online Retailer",
          "city": "San Francisco",
          "phone": "9123456789",
          "statement_descriptor": "statement_descriptor",
          "statement_descriptor_suffix": "statement_descriptor_suffix",
          "reference": "reference"
        },
        "tokenization": "skip_psp",
        "partner_merchant_identifier_details": {
          "partner_details": {
            "name": "name",
            "version": "1.0.0",
            "integrator": "integrator"
          },
          "merchant_details": {
            "name": "name",
            "version": "version"
          }
        },
        "payment_method_tokenization_details": {
          "payment_method_id": "payment_method_id",
          "payment_method_status": "active",
          "psp_tokenization": true,
          "network_tokenization": true,
          "network_transaction_id": "network_transaction_id",
          "is_eligible_for_mit_payment": true
        },
        "installment_options": [
          {
            "payment_method": "card",
            "installments": [
              {
                "number_of_installments": "number_of_installments",
                "billing_frequency": "month",
                "interest_rate": 0
              }
            ]
          }
        ],
        "installment_data": {
          "number_of_installments": 0,
          "billing_frequency": "month",
          "installment_interest": 0
        },
        "customer_statistics": {
          "profile_id": "profile_id",
          "profile_name": "profile_name",
          "first_successful_payment_at": "first_successful_payment_at",
          "payments_count": 0,
          "payments_amount": 0,
          "refunds_count": 0,
          "refunds_amount": 0,
          "payouts_count": 0,
          "payouts_amount": 0,
          "currency": "AED"
        },
        "fee_summary": {
          "currency": "currency",
          "base_amount": 0,
          "merchant_commission_amount": 0,
          "provider_cost": 0,
          "margin": 0,
          "merchant_commission_rate": {},
          "provider_cost_rate": {},
          "merchant_commission_rule": "merchant_commission_rule",
          "provider_cost_rule": "provider_cost_rule"
        }
      }
    ]
  }
]

json

application/json

Payments - List using filters

POST

https://paysw-wiki.lab.next-on.pro/dev-router

/payments/list

api-key (header)

Lists payments with optional column operators

Payments - List using filters › Request Body

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

PaymentListFilterConstraints

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.

Payments - List using filters › Responses

Payments filtered

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

POST/payments/list

curl https://paysw-wiki.lab.next-on.pro/dev-router/payments/list \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'api-key: <api-key>' \
  --data '{
  "payment_id": "payment_id",
  "profile_id": "profile_id",
  "customer_id": "customer_id",
  "limit": 0,
  "offset": 0,
  "amount_filter": {
    "start_amount": 0,
    "end_amount": 0
  },
  "connector": [
    "flexifai"
  ],
  "currency": [
    "AED"
  ],
  "status": [
    "succeeded"
  ],
  "payment_method": [
    "card"
  ],
  "payment_method_type": [
    "ach"
  ],
  "authentication_type": [
    "three_ds"
  ],
  "merchant_connector_id": [
    "string"
  ],
  "order": {
    "on": "amount",
    "by": "asc"
  },
  "card_network": [
    "Visa"
  ],
  "merchant_order_reference_id": "merchant_order_reference_id",
  "card_discovery": [
    "manual"
  ],
  "filters": [
    {}
  ]
}'

Example Request Body

{
  "payment_id": "payment_id",
  "profile_id": "profile_id",
  "customer_id": "customer_id",
  "limit": 0,
  "offset": 0,
  "amount_filter": {
    "start_amount": 0,
    "end_amount": 0
  },
  "connector": [
    "flexifai"
  ],
  "currency": [
    "AED"
  ],
  "status": [
    "succeeded"
  ],
  "payment_method": [
    "card"
  ],
  "payment_method_type": [
    "ach"
  ],
  "authentication_type": [
    "three_ds"
  ],
  "merchant_connector_id": [
    "string"
  ],
  "order": {
    "on": "amount",
    "by": "asc"
  },
  "card_network": [
    "Visa"
  ],
  "merchant_order_reference_id": "merchant_order_reference_id",
  "card_discovery": [
    "manual"
  ],
  "filters": [
    {}
  ]
}

json

Example Responses

{
  "count": 0,
  "total_count": 0,
  "data": [
    {
      "payment_id": "pay_mbabizu24mvu3mela5njyhpit4",
      "merchant_id": "merchant_1668273825",
      "status": "requires_confirmation",
      "amount": 6540,
      "net_amount": 6540,
      "shipping_cost": 6540,
      "amount_capturable": 6540,
      "amount_received": 6540,
      "processor_merchant_id": "merchant_1689512302",
      "initiator": "platform",
      "sdk_authorization": "cHJvZmlsZV9pZD1wcm9mXzEyMyxwdWJsaXNoYWJsZV9rZXk9cGtfbGl2ZV8xMjM=",
      "connector": "stripe",
      "state_metadata": {
        "total_refunded_amount": 0,
        "total_disputed_amount": 0,
        "post_capture_void": {
          "status": "succeeded",
          "connector_reference_id": "connector_reference_id",
          "description": "description",
          "updated_at": "2024-08-25T15:00:00Z"
        }
      },
      "client_secret": "pay_U42c409qyHwOkWo3vK60_secret_el9ksDkiB8hi6j9N78yo",
      "created": "2022-09-10T10:11:12Z",
      "modified_at": "2022-09-10T10:11:12Z",
      "currency": "AED",
      "customer_id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
      "customer": {
        "id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
        "name": "John Doe",
        "email": "johntest@test.com",
        "phone": "9123456789",
        "phone_country_code": "+1",
        "customer_document_details": {
          "document_type": "cpf",
          "document_number": "12345678911"
        }
      },
      "description": "It's my first payment request",
      "refunds": [
        {
          "refund_id": "refund_id",
          "payment_id": "payment_id",
          "amount": 6540,
          "currency": "currency",
          "status": "succeeded",
          "reason": "reason",
          "metadata": {},
          "error_message": "error_message",
          "error_code": "error_code",
          "unified_code": "unified_code",
          "unified_message": "unified_message",
          "created_at": "2024-08-25T15:00:00Z",
          "updated_at": "2024-08-25T15:00:00Z",
          "connector": "stripe",
          "profile_id": "profile_id",
          "merchant_connector_id": "merchant_connector_id",
          "split_refunds": {
            "stripe_split_refund": {
              "revert_platform_fee": true,
              "revert_transfer": true
            }
          },
          "issuer_error_code": "issuer_error_code",
          "issuer_error_message": "issuer_error_message",
          "raw_connector_response": "raw_connector_response",
          "connector_refund_id": "connector_refund_id",
          "fee_summary": {
            "currency": "currency",
            "base_amount": 0,
            "merchant_commission_amount": 0,
            "provider_cost": 0,
            "margin": 0,
            "merchant_commission_rate": {},
            "provider_cost_rate": {},
            "merchant_commission_rule": "merchant_commission_rule",
            "provider_cost_rule": "provider_cost_rule"
          }
        }
      ],
      "disputes": [
        {
          "dispute_id": "dispute_id",
          "amount": "amount",
          "dispute_stage": "pre_dispute",
          "dispute_status": "dispute_opened",
          "connector_status": "connector_status",
          "connector_dispute_id": "connector_dispute_id",
          "connector_reason": "connector_reason",
          "connector_reason_code": "connector_reason_code",
          "challenge_required_by": "2024-08-25T15:00:00Z",
          "connector_created_at": "2024-08-25T15:00:00Z",
          "connector_updated_at": "2024-08-25T15:00:00Z",
          "created_at": "2024-08-25T15:00:00Z"
        }
      ],
      "attempts": [
        {
          "attempt_id": "attempt_id",
          "status": "started",
          "amount": 6540,
          "order_tax_amount": 6540,
          "currency": "AED",
          "connector": "connector",
          "merchant_connector_id": "merchant_connector_id",
          "error_message": "error_message",
          "payment_method": "card",
          "connector_transaction_id": "connector_transaction_id",
          "capture_method": "automatic",
          "authentication_type": "three_ds",
          "created_at": "2022-09-10T10:11:12Z",
          "modified_at": "2022-09-10T10:11:12Z",
          "cancellation_reason": "cancellation_reason",
          "mandate_id": "mandate_id",
          "error_code": "error_code",
          "payment_token": "payment_token",
          "connector_metadata": {},
          "payment_experience": "redirect_to_url",
          "payment_method_type": "ach",
          "reference_id": "993672945374576J",
          "unified_code": "unified_code",
          "unified_message": "unified_message",
          "client_source": "client_source",
          "client_version": "client_version",
          "error_details": {
            "unified_details": {
              "category": "UE_1000",
              "message": "message",
              "standardised_code": "account_closed_or_invalid",
              "description": "description",
              "user_guidance_message": "user_guidance_message",
              "recommended_action": "do_not_retry"
            },
            "issuer_details": {
              "code": "code",
              "message": "message",
              "network_details": {
                "name": "Visa",
                "advice_code": "advice_code",
                "advice_message": "advice_message"
              }
            },
            "connector_details": {
              "code": "code",
              "message": "message",
              "reason": "reason"
            }
          },
          "fee_details": [
            {
              "capture_id": "capture_id",
              "reference_id": "reference_id",
              "created_at": "2024-01-01T00:00:00Z",
              "currency": "currency",
              "base_amount": 0,
              "merchant_commission_amount": 0,
              "provider_cost": 0,
              "margin": 0,
              "merchant_commission_rate": {},
              "provider_cost_rate": {},
              "merchant_commission_rule": "merchant_commission_rule",
              "provider_cost_rule": "provider_cost_rule"
            }
          ]
        }
      ],
      "captures": [
        {
          "capture_id": "capture_id",
          "status": "started",
          "amount": 6540,
          "currency": "AED",
          "connector": "connector",
          "authorized_attempt_id": "authorized_attempt_id",
          "connector_capture_id": "connector_capture_id",
          "capture_sequence": 0,
          "error_message": "error_message",
          "error_code": "error_code",
          "error_reason": "error_reason",
          "reference_id": "reference_id"
        }
      ],
      "mandate_id": "mandate_iwer89rnjef349dni3",
      "mandate_data": {
        "update_mandate_id": "update_mandate_id",
        "customer_acceptance": {
          "acceptance_type": "online",
          "accepted_at": "2022-09-10T10:11:12Z",
          "online": {
            "ip_address": "123.32.25.123",
            "user_agent": "user_agent"
          }
        },
        "mandate_type": {
          "single_use": {
            "amount": 6540,
            "currency": "AED",
            "start_date": "2022-09-10T00:00:00Z",
            "end_date": "2023-09-10T23:59:59Z",
            "metadata": {}
          }
        }
      },
      "setup_future_usage": "off_session",
      "off_session": true,
      "capture_on": "2022-09-10T10:11:12Z",
      "capture_method": "automatic",
      "payment_method": "card",
      "payment_method_data": {
        "billing": {
          "address": {
            "city": "New York",
            "country": "AF",
            "line1": "123, King Street",
            "line2": "Powelson Avenue",
            "line3": "Bridgewater",
            "zip": "08807",
            "state": "New York",
            "first_name": "John",
            "last_name": "Doe",
            "origin_zip": "08807"
          },
          "phone": {
            "number": "9123456789",
            "country_code": "+1"
          },
          "email": "email"
        }
      },
      "payment_token": "187282ab-40ef-47a9-9206-5099ba31e432",
      "shipping": {
        "address": {
          "city": "New York",
          "country": "AF",
          "line1": "123, King Street",
          "line2": "Powelson Avenue",
          "line3": "Bridgewater",
          "zip": "08807",
          "state": "New York",
          "first_name": "John",
          "last_name": "Doe",
          "origin_zip": "08807"
        },
        "phone": {
          "number": "9123456789",
          "country_code": "+1"
        },
        "email": "email"
      },
      "billing": {
        "address": {
          "city": "New York",
          "country": "AF",
          "line1": "123, King Street",
          "line2": "Powelson Avenue",
          "line3": "Bridgewater",
          "zip": "08807",
          "state": "New York",
          "first_name": "John",
          "last_name": "Doe",
          "origin_zip": "08807"
        },
        "phone": {
          "number": "9123456789",
          "country_code": "+1"
        },
        "email": "email"
      },
      "order_details": "[{\n        \"product_name\": \"gillete creme\",\n        \"quantity\": 15,\n        \"amount\" : 900\n    }]",
      "email": "johntest@test.com",
      "name": "John Test",
      "phone": "9123456789",
      "return_url": "https://hyperswitch.io",
      "authentication_type": "three_ds",
      "statement_descriptor_name": "Hyperswitch Router",
      "statement_descriptor_suffix": "Payment for shoes purchase",
      "next_action": {
        "redirect_to_url": "redirect_to_url",
        "type": "redirect_to_url"
      },
      "cancellation_reason": "cancellation_reason",
      "error_code": "E0001",
      "error_message": "Failed while verifying the card",
      "unified_code": "unified_code",
      "unified_message": "unified_message",
      "error_details": {
        "unified_details": {
          "category": "UE_1000",
          "message": "message",
          "standardised_code": "account_closed_or_invalid",
          "description": "description",
          "user_guidance_message": "user_guidance_message",
          "recommended_action": "do_not_retry"
        },
        "issuer_details": {
          "code": "code",
          "message": "message",
          "network_details": {
            "name": "Visa",
            "advice_code": "advice_code",
            "advice_message": "advice_message"
          }
        },
        "connector_details": {
          "code": "code",
          "message": "message",
          "reason": "reason"
        }
      },
      "payment_experience": "redirect_to_url",
      "payment_method_type": "ach",
      "connector_label": "stripe_US_food",
      "business_country": "AF",
      "business_label": "business_label",
      "business_sub_label": "business_sub_label",
      "allowed_payment_method_types": [
        "ach"
      ],
      "manual_retry_allowed": true,
      "connector_transaction_id": "993672945374576J",
      "frm_message": {
        "frm_name": "frm_name",
        "frm_transaction_id": "frm_transaction_id",
        "frm_transaction_type": "frm_transaction_type",
        "frm_status": "frm_status",
        "frm_score": 0,
        "frm_reason": {},
        "frm_error": "frm_error"
      },
      "metadata": {},
      "connector_metadata": {
        "apple_pay": {
          "session_token_data": {
            "certificate": "certificate",
            "certificate_keys": "certificate_keys",
            "merchant_identifier": "merchant_identifier",
            "display_name": "display_name",
            "initiative": "web",
            "initiative_context": "initiative_context",
            "merchant_business_country": "AF"
          }
        },
        "airwallex": {
          "payload": "payload"
        },
        "noon": {
          "order_category": "order_category"
        },
        "braintree": {
          "merchant_account_id": "merchant_account_id",
          "merchant_config_currency": "merchant_config_currency"
        },
        "adyen": {
          "testing": {
            "holder_name": "holder_name"
          }
        },
        "peachpayments": {
          "rrn": "rrn"
        }
      },
      "connector_response_metadata": {
        "santander": {
          "end_to_end_id": "end_to_end_id"
        }
      },
      "feature_metadata": {
        "redirect_response": {
          "param": "param",
          "json_payload": {}
        },
        "search_tags": [
          "string"
        ],
        "apple_pay_recurring_details": {
          "payment_description": "payment_description",
          "regular_billing": {
            "label": "label",
            "recurring_payment_start_date": "2023-09-10T23:59:59Z",
            "recurring_payment_end_date": "2023-09-10T23:59:59Z",
            "recurring_payment_interval_unit": "year",
            "recurring_payment_interval_count": 0
          },
          "billing_agreement": "billing_agreement",
          "management_url": "https://hyperswitch.io"
        },
        "pix_additional_details": {
          "immediate": {
            "time": 0,
            "pix_key": {
              "type": "cpf",
              "value": "value"
            }
          }
        },
        "boleto_additional_details": {
          "due_date": "2026-12-31",
          "document_kind": "commercial_invoice",
          "payment_type": "fixed_amount",
          "covenant_code": "3568253",
          "pix_key": {
            "type": "cpf",
            "value": "value"
          }
        }
      },
      "reference_id": "993672945374576J",
      "payment_link": {
        "link": "link",
        "secure_link": "secure_link",
        "payment_link_id": "payment_link_id"
      },
      "profile_id": "profile_id",
      "surcharge_details": {
        "surcharge_amount": 6540,
        "tax_amount": 0
      },
      "attempt_count": 0,
      "merchant_decision": "merchant_decision",
      "merchant_connector_id": "merchant_connector_id",
      "incremental_authorization_allowed": true,
      "authorization_count": 0,
      "incremental_authorizations": [
        {
          "authorization_id": "authorization_id",
          "amount": 6540,
          "status": "success",
          "error_code": "error_code",
          "error_message": "error_message",
          "previously_authorized_amount": 0
        }
      ],
      "external_authentication_details": {
        "authentication_flow": "challenge",
        "electronic_commerce_indicator": "electronic_commerce_indicator",
        "status": "started",
        "ds_transaction_id": "ds_transaction_id",
        "version": "version",
        "error_code": "error_code",
        "error_message": "error_message"
      },
      "external_3ds_authentication_attempted": true,
      "expires_on": "2022-09-10T10:11:12Z",
      "fingerprint": "fingerprint",
      "browser_info": {
        "color_depth": 0,
        "java_enabled": true,
        "java_script_enabled": true,
        "language": "language",
        "screen_height": 0,
        "screen_width": 0,
        "time_zone": 0,
        "ip_address": "ip_address",
        "accept_header": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8",
        "user_agent": "user_agent",
        "os_type": "os_type",
        "os_version": "os_version",
        "device_model": "device_model",
        "accept_language": "accept_language",
        "referer": "referer"
      },
      "payment_channel": "ecommerce",
      "payment_method_id": "payment_method_id",
      "network_transaction_id": "network_transaction_id",
      "payment_method_status": "active",
      "updated": "2022-09-10T10:11:12Z",
      "split_payments": {
        "stripe_split_payment": {
          "charge_id": "charge_id",
          "charge_type": {
            "Stripe": "direct"
          },
          "application_fees": 6540,
          "transfer_account_id": "transfer_account_id"
        }
      },
      "frm_metadata": {},
      "extended_authorization_applied": true,
      "extended_authorization_last_applied_at": "2022-09-10T10:11:12Z",
      "request_extended_authorization": false,
      "capture_before": "2024-08-25T15:00:00Z",
      "merchant_order_reference_id": "Custom_Order_id_123",
      "order_tax_amount": 0,
      "connector_mandate_id": "connector_mandate_id",
      "card_discovery": "manual",
      "force_3ds_challenge": true,
      "force_3ds_challenge_trigger": true,
      "issuer_error_code": "issuer_error_code",
      "issuer_error_message": "issuer_error_message",
      "is_iframe_redirection_enabled": true,
      "whole_connector_response": "whole_connector_response",
      "enable_partial_authorization": false,
      "enable_overcapture": true,
      "is_overcapture_enabled": true,
      "network_details": {
        "network_advice_code": "network_advice_code"
      },
      "is_stored_credential": true,
      "mit_category": "installment",
      "billing_descriptor": {
        "name": "The Online Retailer",
        "city": "San Francisco",
        "phone": "9123456789",
        "statement_descriptor": "statement_descriptor",
        "statement_descriptor_suffix": "statement_descriptor_suffix",
        "reference": "reference"
      },
      "tokenization": "skip_psp",
      "partner_merchant_identifier_details": {
        "partner_details": {
          "name": "name",
          "version": "1.0.0",
          "integrator": "integrator"
        },
        "merchant_details": {
          "name": "name",
          "version": "version"
        }
      },
      "payment_method_tokenization_details": {
        "payment_method_id": "payment_method_id",
        "payment_method_status": "active",
        "psp_tokenization": true,
        "network_tokenization": true,
        "network_transaction_id": "network_transaction_id",
        "is_eligible_for_mit_payment": true
      },
      "installment_options": [
        {
          "payment_method": "card",
          "installments": [
            {
              "number_of_installments": "number_of_installments",
              "billing_frequency": "month",
              "interest_rate": 0
            }
          ]
        }
      ],
      "installment_data": {
        "number_of_installments": 0,
        "billing_frequency": "month",
        "installment_interest": 0
      },
      "customer_statistics": {
        "profile_id": "profile_id",
        "profile_name": "profile_name",
        "first_successful_payment_at": "first_successful_payment_at",
        "payments_count": 0,
        "payments_amount": 0,
        "refunds_count": 0,
        "refunds_amount": 0,
        "payouts_count": 0,
        "payouts_amount": 0,
        "currency": "AED"
      },
      "fee_summary": {
        "currency": "currency",
        "base_amount": 0,
        "merchant_commission_amount": 0,
        "provider_cost": 0,
        "margin": 0,
        "merchant_commission_rate": {},
        "provider_cost_rate": {},
        "merchant_commission_rule": "merchant_commission_rule",
        "provider_cost_rule": "provider_cost_rule"
      }
    }
  ]
}

json

application/json

Payments - Incremental Authorization

POST

https://paysw-wiki.lab.next-on.pro/dev-router

/payments/{payment_id}/incremental_authorization

api-key (header)

Authorized amount for a payment can be incremented if it is in status: requires_capture

Payments - Incremental Authorization › path Parameters

payment_id

string · required

The identifier for payment

Payments - Incremental Authorization › Request Body

PaymentsIncrementalAuthorizationRequest

amount

integer · int64 · required

The total amount including previously authorized amount and additional amount

Example: 6540

reason

string | null

Reason for incremental authorization

Payments - Incremental Authorization › Responses

Payment authorized amount incremented

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

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

Example: 6540

amount_capturable

integer · int64 · min: 100 · required

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

Example: 6540

initiator

string · enum

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

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

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

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.

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

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:

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

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

network_transaction_id

string | null

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

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

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

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

POST/payments/{payment_id}/incremental_authorization

curl https://paysw-wiki.lab.next-on.pro/dev-router/payments/:payment_id/incremental_authorization \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'api-key: <api-key>' \
  --data '{
  "amount": 6540,
  "reason": "reason"
}'

Example Request Body

{
  "amount": 6540,
  "reason": "reason"
}

json

Example Responses

{
  "payment_id": "pay_mbabizu24mvu3mela5njyhpit4",
  "merchant_id": "merchant_1668273825",
  "status": "requires_confirmation",
  "amount": 6540,
  "net_amount": 6540,
  "shipping_cost": 6540,
  "amount_capturable": 6540,
  "amount_received": 6540,
  "processor_merchant_id": "merchant_1689512302",
  "initiator": "platform",
  "sdk_authorization": "cHJvZmlsZV9pZD1wcm9mXzEyMyxwdWJsaXNoYWJsZV9rZXk9cGtfbGl2ZV8xMjM=",
  "connector": "stripe",
  "state_metadata": {
    "total_refunded_amount": 0,
    "total_disputed_amount": 0,
    "post_capture_void": {
      "status": "succeeded",
      "connector_reference_id": "connector_reference_id",
      "description": "description",
      "updated_at": "2024-08-25T15:00:00Z"
    }
  },
  "client_secret": "pay_U42c409qyHwOkWo3vK60_secret_el9ksDkiB8hi6j9N78yo",
  "created": "2022-09-10T10:11:12Z",
  "modified_at": "2022-09-10T10:11:12Z",
  "currency": "AED",
  "customer_id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
  "customer": {
    "id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
    "name": "John Doe",
    "email": "johntest@test.com",
    "phone": "9123456789",
    "phone_country_code": "+1",
    "customer_document_details": {
      "document_type": "cpf",
      "document_number": "12345678911"
    }
  },
  "description": "It's my first payment request",
  "refunds": [
    {
      "refund_id": "refund_id",
      "payment_id": "payment_id",
      "amount": 6540,
      "currency": "currency",
      "status": "succeeded",
      "reason": "reason",
      "metadata": {},
      "error_message": "error_message",
      "error_code": "error_code",
      "unified_code": "unified_code",
      "unified_message": "unified_message",
      "created_at": "2024-08-25T15:00:00Z",
      "updated_at": "2024-08-25T15:00:00Z",
      "connector": "stripe",
      "profile_id": "profile_id",
      "merchant_connector_id": "merchant_connector_id",
      "split_refunds": {
        "stripe_split_refund": {
          "revert_platform_fee": true,
          "revert_transfer": true
        }
      },
      "issuer_error_code": "issuer_error_code",
      "issuer_error_message": "issuer_error_message",
      "raw_connector_response": "raw_connector_response",
      "connector_refund_id": "connector_refund_id",
      "fee_summary": {
        "currency": "currency",
        "base_amount": 0,
        "merchant_commission_amount": 0,
        "provider_cost": 0,
        "margin": 0,
        "merchant_commission_rate": {},
        "provider_cost_rate": {},
        "merchant_commission_rule": "merchant_commission_rule",
        "provider_cost_rule": "provider_cost_rule"
      }
    }
  ],
  "disputes": [
    {
      "dispute_id": "dispute_id",
      "amount": "amount",
      "dispute_stage": "pre_dispute",
      "dispute_status": "dispute_opened",
      "connector_status": "connector_status",
      "connector_dispute_id": "connector_dispute_id",
      "connector_reason": "connector_reason",
      "connector_reason_code": "connector_reason_code",
      "challenge_required_by": "2024-08-25T15:00:00Z",
      "connector_created_at": "2024-08-25T15:00:00Z",
      "connector_updated_at": "2024-08-25T15:00:00Z",
      "created_at": "2024-08-25T15:00:00Z"
    }
  ],
  "attempts": [
    {
      "attempt_id": "attempt_id",
      "status": "started",
      "amount": 6540,
      "order_tax_amount": 6540,
      "currency": "AED",
      "connector": "connector",
      "merchant_connector_id": "merchant_connector_id",
      "error_message": "error_message",
      "payment_method": "card",
      "connector_transaction_id": "connector_transaction_id",
      "capture_method": "automatic",
      "authentication_type": "three_ds",
      "created_at": "2022-09-10T10:11:12Z",
      "modified_at": "2022-09-10T10:11:12Z",
      "cancellation_reason": "cancellation_reason",
      "mandate_id": "mandate_id",
      "error_code": "error_code",
      "payment_token": "payment_token",
      "connector_metadata": {},
      "payment_experience": "redirect_to_url",
      "payment_method_type": "ach",
      "reference_id": "993672945374576J",
      "unified_code": "unified_code",
      "unified_message": "unified_message",
      "client_source": "client_source",
      "client_version": "client_version",
      "error_details": {
        "unified_details": {
          "category": "UE_1000",
          "message": "message",
          "standardised_code": "account_closed_or_invalid",
          "description": "description",
          "user_guidance_message": "user_guidance_message",
          "recommended_action": "do_not_retry"
        },
        "issuer_details": {
          "code": "code",
          "message": "message",
          "network_details": {
            "name": "Visa",
            "advice_code": "advice_code",
            "advice_message": "advice_message"
          }
        },
        "connector_details": {
          "code": "code",
          "message": "message",
          "reason": "reason"
        }
      },
      "fee_details": [
        {
          "capture_id": "capture_id",
          "reference_id": "reference_id",
          "created_at": "2024-01-01T00:00:00Z",
          "currency": "currency",
          "base_amount": 0,
          "merchant_commission_amount": 0,
          "provider_cost": 0,
          "margin": 0,
          "merchant_commission_rate": {},
          "provider_cost_rate": {},
          "merchant_commission_rule": "merchant_commission_rule",
          "provider_cost_rule": "provider_cost_rule"
        }
      ]
    }
  ],
  "captures": [
    {
      "capture_id": "capture_id",
      "status": "started",
      "amount": 6540,
      "currency": "AED",
      "connector": "connector",
      "authorized_attempt_id": "authorized_attempt_id",
      "connector_capture_id": "connector_capture_id",
      "capture_sequence": 0,
      "error_message": "error_message",
      "error_code": "error_code",
      "error_reason": "error_reason",
      "reference_id": "reference_id"
    }
  ],
  "mandate_id": "mandate_iwer89rnjef349dni3",
  "mandate_data": {
    "update_mandate_id": "update_mandate_id",
    "customer_acceptance": {
      "acceptance_type": "online",
      "accepted_at": "2022-09-10T10:11:12Z",
      "online": {
        "ip_address": "123.32.25.123",
        "user_agent": "user_agent"
      }
    },
    "mandate_type": {
      "single_use": {
        "amount": 6540,
        "currency": "AED",
        "start_date": "2022-09-10T00:00:00Z",
        "end_date": "2023-09-10T23:59:59Z",
        "metadata": {}
      }
    }
  },
  "setup_future_usage": "off_session",
  "off_session": true,
  "capture_on": "2022-09-10T10:11:12Z",
  "capture_method": "automatic",
  "payment_method": "card",
  "payment_method_data": {
    "billing": {
      "address": {
        "city": "New York",
        "country": "AF",
        "line1": "123, King Street",
        "line2": "Powelson Avenue",
        "line3": "Bridgewater",
        "zip": "08807",
        "state": "New York",
        "first_name": "John",
        "last_name": "Doe",
        "origin_zip": "08807"
      },
      "phone": {
        "number": "9123456789",
        "country_code": "+1"
      },
      "email": "email"
    }
  },
  "payment_token": "187282ab-40ef-47a9-9206-5099ba31e432",
  "shipping": {
    "address": {
      "city": "New York",
      "country": "AF",
      "line1": "123, King Street",
      "line2": "Powelson Avenue",
      "line3": "Bridgewater",
      "zip": "08807",
      "state": "New York",
      "first_name": "John",
      "last_name": "Doe",
      "origin_zip": "08807"
    },
    "phone": {
      "number": "9123456789",
      "country_code": "+1"
    },
    "email": "email"
  },
  "billing": {
    "address": {
      "city": "New York",
      "country": "AF",
      "line1": "123, King Street",
      "line2": "Powelson Avenue",
      "line3": "Bridgewater",
      "zip": "08807",
      "state": "New York",
      "first_name": "John",
      "last_name": "Doe",
      "origin_zip": "08807"
    },
    "phone": {
      "number": "9123456789",
      "country_code": "+1"
    },
    "email": "email"
  },
  "order_details": "[{\n        \"product_name\": \"gillete creme\",\n        \"quantity\": 15,\n        \"amount\" : 900\n    }]",
  "email": "johntest@test.com",
  "name": "John Test",
  "phone": "9123456789",
  "return_url": "https://hyperswitch.io",
  "authentication_type": "three_ds",
  "statement_descriptor_name": "Hyperswitch Router",
  "statement_descriptor_suffix": "Payment for shoes purchase",
  "next_action": {
    "redirect_to_url": "redirect_to_url",
    "type": "redirect_to_url"
  },
  "cancellation_reason": "cancellation_reason",
  "error_code": "E0001",
  "error_message": "Failed while verifying the card",
  "unified_code": "unified_code",
  "unified_message": "unified_message",
  "error_details": {
    "unified_details": {
      "category": "UE_1000",
      "message": "message",
      "standardised_code": "account_closed_or_invalid",
      "description": "description",
      "user_guidance_message": "user_guidance_message",
      "recommended_action": "do_not_retry"
    },
    "issuer_details": {
      "code": "code",
      "message": "message",
      "network_details": {
        "name": "Visa",
        "advice_code": "advice_code",
        "advice_message": "advice_message"
      }
    },
    "connector_details": {
      "code": "code",
      "message": "message",
      "reason": "reason"
    }
  },
  "payment_experience": "redirect_to_url",
  "payment_method_type": "ach",
  "connector_label": "stripe_US_food",
  "business_country": "AF",
  "business_label": "business_label",
  "business_sub_label": "business_sub_label",
  "allowed_payment_method_types": [
    "ach"
  ],
  "manual_retry_allowed": true,
  "connector_transaction_id": "993672945374576J",
  "frm_message": {
    "frm_name": "frm_name",
    "frm_transaction_id": "frm_transaction_id",
    "frm_transaction_type": "frm_transaction_type",
    "frm_status": "frm_status",
    "frm_score": 0,
    "frm_reason": {},
    "frm_error": "frm_error"
  },
  "metadata": {},
  "connector_metadata": {
    "apple_pay": {
      "session_token_data": {
        "certificate": "certificate",
        "certificate_keys": "certificate_keys",
        "merchant_identifier": "merchant_identifier",
        "display_name": "display_name",
        "initiative": "web",
        "initiative_context": "initiative_context",
        "merchant_business_country": "AF"
      }
    },
    "airwallex": {
      "payload": "payload"
    },
    "noon": {
      "order_category": "order_category"
    },
    "braintree": {
      "merchant_account_id": "merchant_account_id",
      "merchant_config_currency": "merchant_config_currency"
    },
    "adyen": {
      "testing": {
        "holder_name": "holder_name"
      }
    },
    "peachpayments": {
      "rrn": "rrn"
    }
  },
  "connector_response_metadata": {
    "santander": {
      "end_to_end_id": "end_to_end_id"
    }
  },
  "feature_metadata": {
    "redirect_response": {
      "param": "param",
      "json_payload": {}
    },
    "search_tags": [
      "string"
    ],
    "apple_pay_recurring_details": {
      "payment_description": "payment_description",
      "regular_billing": {
        "label": "label",
        "recurring_payment_start_date": "2023-09-10T23:59:59Z",
        "recurring_payment_end_date": "2023-09-10T23:59:59Z",
        "recurring_payment_interval_unit": "year",
        "recurring_payment_interval_count": 0
      },
      "billing_agreement": "billing_agreement",
      "management_url": "https://hyperswitch.io"
    },
    "pix_additional_details": {
      "immediate": {
        "time": 0,
        "pix_key": {
          "type": "cpf",
          "value": "value"
        }
      }
    },
    "boleto_additional_details": {
      "due_date": "2026-12-31",
      "document_kind": "commercial_invoice",
      "payment_type": "fixed_amount",
      "covenant_code": "3568253",
      "pix_key": {
        "type": "cpf",
        "value": "value"
      }
    }
  },
  "reference_id": "993672945374576J",
  "payment_link": {
    "link": "link",
    "secure_link": "secure_link",
    "payment_link_id": "payment_link_id"
  },
  "profile_id": "profile_id",
  "surcharge_details": {
    "surcharge_amount": 6540,
    "tax_amount": 0
  },
  "attempt_count": 0,
  "merchant_decision": "merchant_decision",
  "merchant_connector_id": "merchant_connector_id",
  "incremental_authorization_allowed": true,
  "authorization_count": 0,
  "incremental_authorizations": [
    {
      "authorization_id": "authorization_id",
      "amount": 6540,
      "status": "success",
      "error_code": "error_code",
      "error_message": "error_message",
      "previously_authorized_amount": 0
    }
  ],
  "external_authentication_details": {
    "authentication_flow": "challenge",
    "electronic_commerce_indicator": "electronic_commerce_indicator",
    "status": "started",
    "ds_transaction_id": "ds_transaction_id",
    "version": "version",
    "error_code": "error_code",
    "error_message": "error_message"
  },
  "external_3ds_authentication_attempted": true,
  "expires_on": "2022-09-10T10:11:12Z",
  "fingerprint": "fingerprint",
  "browser_info": {
    "color_depth": 0,
    "java_enabled": true,
    "java_script_enabled": true,
    "language": "language",
    "screen_height": 0,
    "screen_width": 0,
    "time_zone": 0,
    "ip_address": "ip_address",
    "accept_header": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8",
    "user_agent": "user_agent",
    "os_type": "os_type",
    "os_version": "os_version",
    "device_model": "device_model",
    "accept_language": "accept_language",
    "referer": "referer"
  },
  "payment_channel": "ecommerce",
  "payment_method_id": "payment_method_id",
  "network_transaction_id": "network_transaction_id",
  "payment_method_status": "active",
  "updated": "2022-09-10T10:11:12Z",
  "split_payments": {
    "stripe_split_payment": {
      "charge_id": "charge_id",
      "charge_type": {
        "Stripe": "direct"
      },
      "application_fees": 6540,
      "transfer_account_id": "transfer_account_id"
    }
  },
  "frm_metadata": {},
  "extended_authorization_applied": true,
  "extended_authorization_last_applied_at": "2022-09-10T10:11:12Z",
  "request_extended_authorization": false,
  "capture_before": "2024-08-25T15:00:00Z",
  "merchant_order_reference_id": "Custom_Order_id_123",
  "order_tax_amount": 0,
  "connector_mandate_id": "connector_mandate_id",
  "card_discovery": "manual",
  "force_3ds_challenge": true,
  "force_3ds_challenge_trigger": true,
  "issuer_error_code": "issuer_error_code",
  "issuer_error_message": "issuer_error_message",
  "is_iframe_redirection_enabled": true,
  "whole_connector_response": "whole_connector_response",
  "enable_partial_authorization": false,
  "enable_overcapture": true,
  "is_overcapture_enabled": true,
  "network_details": {
    "network_advice_code": "network_advice_code"
  },
  "is_stored_credential": true,
  "mit_category": "installment",
  "billing_descriptor": {
    "name": "The Online Retailer",
    "city": "San Francisco",
    "phone": "9123456789",
    "statement_descriptor": "statement_descriptor",
    "statement_descriptor_suffix": "statement_descriptor_suffix",
    "reference": "reference"
  },
  "tokenization": "skip_psp",
  "partner_merchant_identifier_details": {
    "partner_details": {
      "name": "name",
      "version": "1.0.0",
      "integrator": "integrator"
    },
    "merchant_details": {
      "name": "name",
      "version": "version"
    }
  },
  "payment_method_tokenization_details": {
    "payment_method_id": "payment_method_id",
    "payment_method_status": "active",
    "psp_tokenization": true,
    "network_tokenization": true,
    "network_transaction_id": "network_transaction_id",
    "is_eligible_for_mit_payment": true
  },
  "installment_options": [
    {
      "payment_method": "card",
      "installments": [
        {
          "number_of_installments": "number_of_installments",
          "billing_frequency": "month",
          "interest_rate": 0
        }
      ]
    }
  ],
  "installment_data": {
    "number_of_installments": 0,
    "billing_frequency": "month",
    "installment_interest": 0
  },
  "customer_statistics": {
    "profile_id": "profile_id",
    "profile_name": "profile_name",
    "first_successful_payment_at": "first_successful_payment_at",
    "payments_count": 0,
    "payments_amount": 0,
    "refunds_count": 0,
    "refunds_amount": 0,
    "payouts_count": 0,
    "payouts_amount": 0,
    "currency": "AED"
  },
  "fee_summary": {
    "currency": "currency",
    "base_amount": 0,
    "merchant_commission_amount": 0,
    "provider_cost": 0,
    "margin": 0,
    "merchant_commission_rate": {},
    "provider_cost_rate": {},
    "merchant_commission_rule": "merchant_commission_rule",
    "provider_cost_rule": "provider_cost_rule"
  }
}

json

application/json

Payments Link - Retrieve

GET

https://paysw-wiki.lab.next-on.pro/dev-router

/payment_link/{payment_link_id}

api-key (header)

To retrieve the properties of a Payment Link. This may be used to get the status of a previously initiated payment or next action for an ongoing payment

Payments Link - Retrieve › path Parameters

payment_link_id

string · required

The identifier for payment link

Payments Link - Retrieve › query Parameters

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

Payments Link - Retrieve › Responses

Gets details regarding payment link

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)

Payments - External 3DS Authentication

POST

https://paysw-wiki.lab.next-on.pro/dev-router

/payments/{payment_id}/3ds/authentication

api-key (header)

External 3DS Authentication is performed and returns the AuthenticationResponse

Payments - External 3DS Authentication › path Parameters

payment_id

string · required

The identifier for payment

Payments - External 3DS Authentication › Request Body

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:

client_secret

string | null

Client Secret

object

SDK Information if request is from SDK

Payments - External 3DS Authentication › Responses

Authentication created

PaymentsExternalAuthenticationResponse

trans_status

TransactionStatus · enum · required

Indicates the transaction status

Enum values:

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

POST/payments/{payment_id}/3ds/authentication

curl https://paysw-wiki.lab.next-on.pro/dev-router/payments/:payment_id/3ds/authentication \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'api-key: <api-key>' \
  --data '{
  "client_secret": "client_secret",
  "sdk_information": {
    "sdk_app_id": "sdk_app_id",
    "sdk_enc_data": "sdk_enc_data",
    "sdk_ephem_pub_key": {
      "key": "string"
    },
    "sdk_trans_id": "sdk_trans_id",
    "sdk_reference_number": "sdk_reference_number",
    "sdk_max_timeout": 0,
    "sdk_type": "01",
    "device_details": {
      "device_type": "device_type",
      "device_brand": "device_brand",
      "device_os": "device_os",
      "device_display": "device_display"
    }
  },
  "device_channel": "APP",
  "threeds_method_comp_ind": "Y"
}'

Example Request Body

{
  "client_secret": "client_secret",
  "sdk_information": {
    "sdk_app_id": "sdk_app_id",
    "sdk_enc_data": "sdk_enc_data",
    "sdk_ephem_pub_key": {
      "key": "string"
    },
    "sdk_trans_id": "sdk_trans_id",
    "sdk_reference_number": "sdk_reference_number",
    "sdk_max_timeout": 0,
    "sdk_type": "01",
    "device_details": {
      "device_type": "device_type",
      "device_brand": "device_brand",
      "device_os": "device_os",
      "device_display": "device_display"
    }
  },
  "device_channel": "APP",
  "threeds_method_comp_ind": "Y"
}

json

Example Responses

{
  "trans_status": "Y",
  "acs_url": "acs_url",
  "challenge_request": "challenge_request",
  "challenge_request_key": "challenge_request_key",
  "acs_reference_number": "acs_reference_number",
  "acs_trans_id": "acs_trans_id",
  "three_dsserver_trans_id": "three_dsserver_trans_id",
  "acs_signed_content": "acs_signed_content",
  "three_ds_requestor_url": "three_ds_requestor_url",
  "three_ds_requestor_app_url": "three_ds_requestor_app_url",
  "error_message": "error_message"
}

json

application/json

Payments - Complete Authorize

POST

https://paysw-wiki.lab.next-on.pro/dev-router

/payments/{payment_id}/complete_authorize

api-key (header)

Payments - Complete Authorize › path Parameters

payment_id

string · required

The identifier for payment

Payments - Complete Authorize › Request 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:

Payments - Complete Authorize › Responses

Payments Complete Authorize Success

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

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

Example: 6540

amount_capturable

integer · int64 · min: 100 · required

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

Example: 6540

initiator

string · enum

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

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

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

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.

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

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:

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

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

network_transaction_id

string | null

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

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

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

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

POST/payments/{payment_id}/complete_authorize

curl https://paysw-wiki.lab.next-on.pro/dev-router/payments/:payment_id/complete_authorize \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'api-key: <api-key>' \
  --data '{
  "shipping": {
    "address": {
      "city": "New York",
      "country": "AF",
      "line1": "123, King Street",
      "line2": "Powelson Avenue",
      "line3": "Bridgewater",
      "zip": "08807",
      "state": "New York",
      "first_name": "John",
      "last_name": "Doe",
      "origin_zip": "08807"
    },
    "phone": {
      "number": "9123456789",
      "country_code": "+1"
    },
    "email": "email"
  },
  "client_secret": "client_secret",
  "threeds_method_comp_ind": "Y"
}'

Example Request Body

{
  "shipping": {
    "address": {
      "city": "New York",
      "country": "AF",
      "line1": "123, King Street",
      "line2": "Powelson Avenue",
      "line3": "Bridgewater",
      "zip": "08807",
      "state": "New York",
      "first_name": "John",
      "last_name": "Doe",
      "origin_zip": "08807"
    },
    "phone": {
      "number": "9123456789",
      "country_code": "+1"
    },
    "email": "email"
  },
  "client_secret": "client_secret",
  "threeds_method_comp_ind": "Y"
}

json

Example Responses

{
  "payment_id": "pay_mbabizu24mvu3mela5njyhpit4",
  "merchant_id": "merchant_1668273825",
  "status": "requires_confirmation",
  "amount": 6540,
  "net_amount": 6540,
  "shipping_cost": 6540,
  "amount_capturable": 6540,
  "amount_received": 6540,
  "processor_merchant_id": "merchant_1689512302",
  "initiator": "platform",
  "sdk_authorization": "cHJvZmlsZV9pZD1wcm9mXzEyMyxwdWJsaXNoYWJsZV9rZXk9cGtfbGl2ZV8xMjM=",
  "connector": "stripe",
  "state_metadata": {
    "total_refunded_amount": 0,
    "total_disputed_amount": 0,
    "post_capture_void": {
      "status": "succeeded",
      "connector_reference_id": "connector_reference_id",
      "description": "description",
      "updated_at": "2024-08-25T15:00:00Z"
    }
  },
  "client_secret": "pay_U42c409qyHwOkWo3vK60_secret_el9ksDkiB8hi6j9N78yo",
  "created": "2022-09-10T10:11:12Z",
  "modified_at": "2022-09-10T10:11:12Z",
  "currency": "AED",
  "customer_id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
  "customer": {
    "id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
    "name": "John Doe",
    "email": "johntest@test.com",
    "phone": "9123456789",
    "phone_country_code": "+1",
    "customer_document_details": {
      "document_type": "cpf",
      "document_number": "12345678911"
    }
  },
  "description": "It's my first payment request",
  "refunds": [
    {
      "refund_id": "refund_id",
      "payment_id": "payment_id",
      "amount": 6540,
      "currency": "currency",
      "status": "succeeded",
      "reason": "reason",
      "metadata": {},
      "error_message": "error_message",
      "error_code": "error_code",
      "unified_code": "unified_code",
      "unified_message": "unified_message",
      "created_at": "2024-08-25T15:00:00Z",
      "updated_at": "2024-08-25T15:00:00Z",
      "connector": "stripe",
      "profile_id": "profile_id",
      "merchant_connector_id": "merchant_connector_id",
      "split_refunds": {
        "stripe_split_refund": {
          "revert_platform_fee": true,
          "revert_transfer": true
        }
      },
      "issuer_error_code": "issuer_error_code",
      "issuer_error_message": "issuer_error_message",
      "raw_connector_response": "raw_connector_response",
      "connector_refund_id": "connector_refund_id",
      "fee_summary": {
        "currency": "currency",
        "base_amount": 0,
        "merchant_commission_amount": 0,
        "provider_cost": 0,
        "margin": 0,
        "merchant_commission_rate": {},
        "provider_cost_rate": {},
        "merchant_commission_rule": "merchant_commission_rule",
        "provider_cost_rule": "provider_cost_rule"
      }
    }
  ],
  "disputes": [
    {
      "dispute_id": "dispute_id",
      "amount": "amount",
      "dispute_stage": "pre_dispute",
      "dispute_status": "dispute_opened",
      "connector_status": "connector_status",
      "connector_dispute_id": "connector_dispute_id",
      "connector_reason": "connector_reason",
      "connector_reason_code": "connector_reason_code",
      "challenge_required_by": "2024-08-25T15:00:00Z",
      "connector_created_at": "2024-08-25T15:00:00Z",
      "connector_updated_at": "2024-08-25T15:00:00Z",
      "created_at": "2024-08-25T15:00:00Z"
    }
  ],
  "attempts": [
    {
      "attempt_id": "attempt_id",
      "status": "started",
      "amount": 6540,
      "order_tax_amount": 6540,
      "currency": "AED",
      "connector": "connector",
      "merchant_connector_id": "merchant_connector_id",
      "error_message": "error_message",
      "payment_method": "card",
      "connector_transaction_id": "connector_transaction_id",
      "capture_method": "automatic",
      "authentication_type": "three_ds",
      "created_at": "2022-09-10T10:11:12Z",
      "modified_at": "2022-09-10T10:11:12Z",
      "cancellation_reason": "cancellation_reason",
      "mandate_id": "mandate_id",
      "error_code": "error_code",
      "payment_token": "payment_token",
      "connector_metadata": {},
      "payment_experience": "redirect_to_url",
      "payment_method_type": "ach",
      "reference_id": "993672945374576J",
      "unified_code": "unified_code",
      "unified_message": "unified_message",
      "client_source": "client_source",
      "client_version": "client_version",
      "error_details": {
        "unified_details": {
          "category": "UE_1000",
          "message": "message",
          "standardised_code": "account_closed_or_invalid",
          "description": "description",
          "user_guidance_message": "user_guidance_message",
          "recommended_action": "do_not_retry"
        },
        "issuer_details": {
          "code": "code",
          "message": "message",
          "network_details": {
            "name": "Visa",
            "advice_code": "advice_code",
            "advice_message": "advice_message"
          }
        },
        "connector_details": {
          "code": "code",
          "message": "message",
          "reason": "reason"
        }
      },
      "fee_details": [
        {
          "capture_id": "capture_id",
          "reference_id": "reference_id",
          "created_at": "2024-01-01T00:00:00Z",
          "currency": "currency",
          "base_amount": 0,
          "merchant_commission_amount": 0,
          "provider_cost": 0,
          "margin": 0,
          "merchant_commission_rate": {},
          "provider_cost_rate": {},
          "merchant_commission_rule": "merchant_commission_rule",
          "provider_cost_rule": "provider_cost_rule"
        }
      ]
    }
  ],
  "captures": [
    {
      "capture_id": "capture_id",
      "status": "started",
      "amount": 6540,
      "currency": "AED",
      "connector": "connector",
      "authorized_attempt_id": "authorized_attempt_id",
      "connector_capture_id": "connector_capture_id",
      "capture_sequence": 0,
      "error_message": "error_message",
      "error_code": "error_code",
      "error_reason": "error_reason",
      "reference_id": "reference_id"
    }
  ],
  "mandate_id": "mandate_iwer89rnjef349dni3",
  "mandate_data": {
    "update_mandate_id": "update_mandate_id",
    "customer_acceptance": {
      "acceptance_type": "online",
      "accepted_at": "2022-09-10T10:11:12Z",
      "online": {
        "ip_address": "123.32.25.123",
        "user_agent": "user_agent"
      }
    },
    "mandate_type": {
      "single_use": {
        "amount": 6540,
        "currency": "AED",
        "start_date": "2022-09-10T00:00:00Z",
        "end_date": "2023-09-10T23:59:59Z",
        "metadata": {}
      }
    }
  },
  "setup_future_usage": "off_session",
  "off_session": true,
  "capture_on": "2022-09-10T10:11:12Z",
  "capture_method": "automatic",
  "payment_method": "card",
  "payment_method_data": {
    "billing": {
      "address": {
        "city": "New York",
        "country": "AF",
        "line1": "123, King Street",
        "line2": "Powelson Avenue",
        "line3": "Bridgewater",
        "zip": "08807",
        "state": "New York",
        "first_name": "John",
        "last_name": "Doe",
        "origin_zip": "08807"
      },
      "phone": {
        "number": "9123456789",
        "country_code": "+1"
      },
      "email": "email"
    }
  },
  "payment_token": "187282ab-40ef-47a9-9206-5099ba31e432",
  "shipping": {
    "address": {
      "city": "New York",
      "country": "AF",
      "line1": "123, King Street",
      "line2": "Powelson Avenue",
      "line3": "Bridgewater",
      "zip": "08807",
      "state": "New York",
      "first_name": "John",
      "last_name": "Doe",
      "origin_zip": "08807"
    },
    "phone": {
      "number": "9123456789",
      "country_code": "+1"
    },
    "email": "email"
  },
  "billing": {
    "address": {
      "city": "New York",
      "country": "AF",
      "line1": "123, King Street",
      "line2": "Powelson Avenue",
      "line3": "Bridgewater",
      "zip": "08807",
      "state": "New York",
      "first_name": "John",
      "last_name": "Doe",
      "origin_zip": "08807"
    },
    "phone": {
      "number": "9123456789",
      "country_code": "+1"
    },
    "email": "email"
  },
  "order_details": "[{\n        \"product_name\": \"gillete creme\",\n        \"quantity\": 15,\n        \"amount\" : 900\n    }]",
  "email": "johntest@test.com",
  "name": "John Test",
  "phone": "9123456789",
  "return_url": "https://hyperswitch.io",
  "authentication_type": "three_ds",
  "statement_descriptor_name": "Hyperswitch Router",
  "statement_descriptor_suffix": "Payment for shoes purchase",
  "next_action": {
    "redirect_to_url": "redirect_to_url",
    "type": "redirect_to_url"
  },
  "cancellation_reason": "cancellation_reason",
  "error_code": "E0001",
  "error_message": "Failed while verifying the card",
  "unified_code": "unified_code",
  "unified_message": "unified_message",
  "error_details": {
    "unified_details": {
      "category": "UE_1000",
      "message": "message",
      "standardised_code": "account_closed_or_invalid",
      "description": "description",
      "user_guidance_message": "user_guidance_message",
      "recommended_action": "do_not_retry"
    },
    "issuer_details": {
      "code": "code",
      "message": "message",
      "network_details": {
        "name": "Visa",
        "advice_code": "advice_code",
        "advice_message": "advice_message"
      }
    },
    "connector_details": {
      "code": "code",
      "message": "message",
      "reason": "reason"
    }
  },
  "payment_experience": "redirect_to_url",
  "payment_method_type": "ach",
  "connector_label": "stripe_US_food",
  "business_country": "AF",
  "business_label": "business_label",
  "business_sub_label": "business_sub_label",
  "allowed_payment_method_types": [
    "ach"
  ],
  "manual_retry_allowed": true,
  "connector_transaction_id": "993672945374576J",
  "frm_message": {
    "frm_name": "frm_name",
    "frm_transaction_id": "frm_transaction_id",
    "frm_transaction_type": "frm_transaction_type",
    "frm_status": "frm_status",
    "frm_score": 0,
    "frm_reason": {},
    "frm_error": "frm_error"
  },
  "metadata": {},
  "connector_metadata": {
    "apple_pay": {
      "session_token_data": {
        "certificate": "certificate",
        "certificate_keys": "certificate_keys",
        "merchant_identifier": "merchant_identifier",
        "display_name": "display_name",
        "initiative": "web",
        "initiative_context": "initiative_context",
        "merchant_business_country": "AF"
      }
    },
    "airwallex": {
      "payload": "payload"
    },
    "noon": {
      "order_category": "order_category"
    },
    "braintree": {
      "merchant_account_id": "merchant_account_id",
      "merchant_config_currency": "merchant_config_currency"
    },
    "adyen": {
      "testing": {
        "holder_name": "holder_name"
      }
    },
    "peachpayments": {
      "rrn": "rrn"
    }
  },
  "connector_response_metadata": {
    "santander": {
      "end_to_end_id": "end_to_end_id"
    }
  },
  "feature_metadata": {
    "redirect_response": {
      "param": "param",
      "json_payload": {}
    },
    "search_tags": [
      "string"
    ],
    "apple_pay_recurring_details": {
      "payment_description": "payment_description",
      "regular_billing": {
        "label": "label",
        "recurring_payment_start_date": "2023-09-10T23:59:59Z",
        "recurring_payment_end_date": "2023-09-10T23:59:59Z",
        "recurring_payment_interval_unit": "year",
        "recurring_payment_interval_count": 0
      },
      "billing_agreement": "billing_agreement",
      "management_url": "https://hyperswitch.io"
    },
    "pix_additional_details": {
      "immediate": {
        "time": 0,
        "pix_key": {
          "type": "cpf",
          "value": "value"
        }
      }
    },
    "boleto_additional_details": {
      "due_date": "2026-12-31",
      "document_kind": "commercial_invoice",
      "payment_type": "fixed_amount",
      "covenant_code": "3568253",
      "pix_key": {
        "type": "cpf",
        "value": "value"
      }
    }
  },
  "reference_id": "993672945374576J",
  "payment_link": {
    "link": "link",
    "secure_link": "secure_link",
    "payment_link_id": "payment_link_id"
  },
  "profile_id": "profile_id",
  "surcharge_details": {
    "surcharge_amount": 6540,
    "tax_amount": 0
  },
  "attempt_count": 0,
  "merchant_decision": "merchant_decision",
  "merchant_connector_id": "merchant_connector_id",
  "incremental_authorization_allowed": true,
  "authorization_count": 0,
  "incremental_authorizations": [
    {
      "authorization_id": "authorization_id",
      "amount": 6540,
      "status": "success",
      "error_code": "error_code",
      "error_message": "error_message",
      "previously_authorized_amount": 0
    }
  ],
  "external_authentication_details": {
    "authentication_flow": "challenge",
    "electronic_commerce_indicator": "electronic_commerce_indicator",
    "status": "started",
    "ds_transaction_id": "ds_transaction_id",
    "version": "version",
    "error_code": "error_code",
    "error_message": "error_message"
  },
  "external_3ds_authentication_attempted": true,
  "expires_on": "2022-09-10T10:11:12Z",
  "fingerprint": "fingerprint",
  "browser_info": {
    "color_depth": 0,
    "java_enabled": true,
    "java_script_enabled": true,
    "language": "language",
    "screen_height": 0,
    "screen_width": 0,
    "time_zone": 0,
    "ip_address": "ip_address",
    "accept_header": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8",
    "user_agent": "user_agent",
    "os_type": "os_type",
    "os_version": "os_version",
    "device_model": "device_model",
    "accept_language": "accept_language",
    "referer": "referer"
  },
  "payment_channel": "ecommerce",
  "payment_method_id": "payment_method_id",
  "network_transaction_id": "network_transaction_id",
  "payment_method_status": "active",
  "updated": "2022-09-10T10:11:12Z",
  "split_payments": {
    "stripe_split_payment": {
      "charge_id": "charge_id",
      "charge_type": {
        "Stripe": "direct"
      },
      "application_fees": 6540,
      "transfer_account_id": "transfer_account_id"
    }
  },
  "frm_metadata": {},
  "extended_authorization_applied": true,
  "extended_authorization_last_applied_at": "2022-09-10T10:11:12Z",
  "request_extended_authorization": false,
  "capture_before": "2024-08-25T15:00:00Z",
  "merchant_order_reference_id": "Custom_Order_id_123",
  "order_tax_amount": 0,
  "connector_mandate_id": "connector_mandate_id",
  "card_discovery": "manual",
  "force_3ds_challenge": true,
  "force_3ds_challenge_trigger": true,
  "issuer_error_code": "issuer_error_code",
  "issuer_error_message": "issuer_error_message",
  "is_iframe_redirection_enabled": true,
  "whole_connector_response": "whole_connector_response",
  "enable_partial_authorization": false,
  "enable_overcapture": true,
  "is_overcapture_enabled": true,
  "network_details": {
    "network_advice_code": "network_advice_code"
  },
  "is_stored_credential": true,
  "mit_category": "installment",
  "billing_descriptor": {
    "name": "The Online Retailer",
    "city": "San Francisco",
    "phone": "9123456789",
    "statement_descriptor": "statement_descriptor",
    "statement_descriptor_suffix": "statement_descriptor_suffix",
    "reference": "reference"
  },
  "tokenization": "skip_psp",
  "partner_merchant_identifier_details": {
    "partner_details": {
      "name": "name",
      "version": "1.0.0",
      "integrator": "integrator"
    },
    "merchant_details": {
      "name": "name",
      "version": "version"
    }
  },
  "payment_method_tokenization_details": {
    "payment_method_id": "payment_method_id",
    "payment_method_status": "active",
    "psp_tokenization": true,
    "network_tokenization": true,
    "network_transaction_id": "network_transaction_id",
    "is_eligible_for_mit_payment": true
  },
  "installment_options": [
    {
      "payment_method": "card",
      "installments": [
        {
          "number_of_installments": "number_of_installments",
          "billing_frequency": "month",
          "interest_rate": 0
        }
      ]
    }
  ],
  "installment_data": {
    "number_of_installments": 0,
    "billing_frequency": "month",
    "installment_interest": 0
  },
  "customer_statistics": {
    "profile_id": "profile_id",
    "profile_name": "profile_name",
    "first_successful_payment_at": "first_successful_payment_at",
    "payments_count": 0,
    "payments_amount": 0,
    "refunds_count": 0,
    "refunds_amount": 0,
    "payouts_count": 0,
    "payouts_amount": 0,
    "currency": "AED"
  },
  "fee_summary": {
    "currency": "currency",
    "base_amount": 0,
    "merchant_commission_amount": 0,
    "provider_cost": 0,
    "margin": 0,
    "merchant_commission_rate": {},
    "provider_cost_rate": {},
    "merchant_commission_rule": "merchant_commission_rule",
    "provider_cost_rule": "provider_cost_rule"
  }
}

json

application/json

Payments - Post Session Tokens

POST

https://paysw-wiki.lab.next-on.pro/dev-router

/payments/{payment_id}/post_session_tokens

api-key (header)

Payments - Post Session Tokens › path Parameters

payment_id

string · required

The identifier for payment

Payments - Post Session Tokens › Request Body

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.

Payments - Post Session Tokens › Responses

Post Session Token is done

PaymentsPostSessionTokensResponse

payment_id

string · required

The identifier for the payment

status

string · enum · required

Enum values:

succeeded

failed

cancelled

cancelled_post_capture

processing

requires_customer_action

requires_merchant_action

requires_payment_method

Default: requires_confirmation

Payments - Update Metadata

POST

https://paysw-wiki.lab.next-on.pro/dev-router

/payments/{payment_id}/update_metadata

api-key (header)

Payments - Update Metadata › path Parameters

payment_id

string · required

The identifier for payment

Payments - Update Metadata › Request Body

PaymentsUpdateMetadataRequest

metadata

object · required

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

object

additional data that might be required by hyperswitch

Payments - Update Metadata › Responses

Metadata updated successfully

PaymentsUpdateMetadataResponse

payment_id

string · required

The identifier for the payment

status

string · enum · required

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

POST/payments/{payment_id}/update_metadata

curl https://paysw-wiki.lab.next-on.pro/dev-router/payments/:payment_id/update_metadata \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'api-key: <api-key>' \
  --data '{
  "metadata": {},
  "feature_metadata": {
    "redirect_response": {
      "param": "param",
      "json_payload": {}
    },
    "search_tags": [
      "string"
    ],
    "apple_pay_recurring_details": {
      "payment_description": "payment_description",
      "regular_billing": {
        "label": "label",
        "recurring_payment_start_date": "2023-09-10T23:59:59Z",
        "recurring_payment_end_date": "2023-09-10T23:59:59Z",
        "recurring_payment_interval_unit": "year",
        "recurring_payment_interval_count": 0
      },
      "billing_agreement": "billing_agreement",
      "management_url": "https://hyperswitch.io"
    },
    "pix_additional_details": {
      "immediate": {
        "time": 0,
        "pix_key": {
          "type": "cpf",
          "value": "value"
        }
      }
    },
    "boleto_additional_details": {
      "due_date": "2026-12-31",
      "document_kind": "commercial_invoice",
      "payment_type": "fixed_amount",
      "covenant_code": "3568253",
      "pix_key": {
        "type": "cpf",
        "value": "value"
      }
    }
  }
}'

Example Request Body

{
  "metadata": {},
  "feature_metadata": {
    "redirect_response": {
      "param": "param",
      "json_payload": {}
    },
    "search_tags": [
      "string"
    ],
    "apple_pay_recurring_details": {
      "payment_description": "payment_description",
      "regular_billing": {
        "label": "label",
        "recurring_payment_start_date": "2023-09-10T23:59:59Z",
        "recurring_payment_end_date": "2023-09-10T23:59:59Z",
        "recurring_payment_interval_unit": "year",
        "recurring_payment_interval_count": 0
      },
      "billing_agreement": "billing_agreement",
      "management_url": "https://hyperswitch.io"
    },
    "pix_additional_details": {
      "immediate": {
        "time": 0,
        "pix_key": {
          "type": "cpf",
          "value": "value"
        }
      }
    },
    "boleto_additional_details": {
      "due_date": "2026-12-31",
      "document_kind": "commercial_invoice",
      "payment_type": "fixed_amount",
      "covenant_code": "3568253",
      "pix_key": {
        "type": "cpf",
        "value": "value"
      }
    }
  }
}

json

Example Responses

{
  "payment_id": "payment_id",
  "metadata": {},
  "status": "requires_confirmation",
  "feature_metadata": {
    "redirect_response": {
      "param": "param",
      "json_payload": {}
    },
    "search_tags": [
      "string"
    ],
    "apple_pay_recurring_details": {
      "payment_description": "payment_description",
      "regular_billing": {
        "label": "label",
        "recurring_payment_start_date": "2023-09-10T23:59:59Z",
        "recurring_payment_end_date": "2023-09-10T23:59:59Z",
        "recurring_payment_interval_unit": "year",
        "recurring_payment_interval_count": 0
      },
      "billing_agreement": "billing_agreement",
      "management_url": "https://hyperswitch.io"
    },
    "pix_additional_details": {
      "immediate": {
        "time": 0,
        "pix_key": {
          "type": "cpf",
          "value": "value"
        }
      }
    },
    "boleto_additional_details": {
      "due_date": "2026-12-31",
      "document_kind": "commercial_invoice",
      "payment_type": "fixed_amount",
      "covenant_code": "3568253",
      "pix_key": {
        "type": "cpf",
        "value": "value"
      }
    }
  }
}

json

application/json

Payments - Submit Eligibility Data

POST

https://paysw-wiki.lab.next-on.pro/dev-router

/payments/{payment_id}/eligibility

api-key (header)

Payments - Submit Eligibility Data › path Parameters

payment_id

string · required

The identifier for payment

Payments - Submit Eligibility Data › Request Body

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

Payments - Submit Eligibility Data › Responses

Eligibility submit is successful

PaymentsEligibilityResponse

payment_id

string · required

The identifier for the payment

SdkNextAction · required

POST/payments/{payment_id}/eligibility

curl https://paysw-wiki.lab.next-on.pro/dev-router/payments/:payment_id/eligibility \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'api-key: <api-key>' \
  --data '{
  "client_secret": "pay_U42c409qyHwOkWo3vK60_secret_el9ksDkiB8hi6j9N78yo",
  "payment_method_type": "card",
  "payment_method_subtype": "ach",
  "payment_method_data": {
    "billing": {
      "address": {
        "city": "New York",
        "country": "AF",
        "line1": "123, King Street",
        "line2": "Powelson Avenue",
        "line3": "Bridgewater",
        "zip": "08807",
        "state": "New York",
        "first_name": "John",
        "last_name": "Doe",
        "origin_zip": "08807"
      },
      "phone": {
        "number": "9123456789",
        "country_code": "+1"
      },
      "email": "email"
    }
  },
  "browser_info": {
    "color_depth": 0,
    "java_enabled": true,
    "java_script_enabled": true,
    "language": "language",
    "screen_height": 0,
    "screen_width": 0,
    "time_zone": 0,
    "ip_address": "ip_address",
    "accept_header": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8",
    "user_agent": "user_agent",
    "os_type": "os_type",
    "os_version": "os_version",
    "device_model": "device_model",
    "accept_language": "accept_language",
    "referer": "referer"
  }
}'

Example Request Body

{
  "client_secret": "pay_U42c409qyHwOkWo3vK60_secret_el9ksDkiB8hi6j9N78yo",
  "payment_method_type": "card",
  "payment_method_subtype": "ach",
  "payment_method_data": {
    "billing": {
      "address": {
        "city": "New York",
        "country": "AF",
        "line1": "123, King Street",
        "line2": "Powelson Avenue",
        "line3": "Bridgewater",
        "zip": "08807",
        "state": "New York",
        "first_name": "John",
        "last_name": "Doe",
        "origin_zip": "08807"
      },
      "phone": {
        "number": "9123456789",
        "country_code": "+1"
      },
      "email": "email"
    }
  },
  "browser_info": {
    "color_depth": 0,
    "java_enabled": true,
    "java_script_enabled": true,
    "language": "language",
    "screen_height": 0,
    "screen_width": 0,
    "time_zone": 0,
    "ip_address": "ip_address",
    "accept_header": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8",
    "user_agent": "user_agent",
    "os_type": "os_type",
    "os_version": "os_version",
    "device_model": "device_model",
    "accept_language": "accept_language",
    "referer": "referer"
  }
}

json

Example Responses

{
  "payment_id": "payment_id",
  "sdk_next_action": {
    "next_action": "post_session_tokens"
  }
}

json

application/json

Refunds