Payments

GET

payments

list

curl --request GET \
  --url https://sandbox.hyperswitch.io/payments/list \
  --header 'api-key: <api-key>'

[
  {
    "size": 1,
    "data": [
      {
        "payment_id": "pay_mbabizu24mvu3mela5njyhpit4",
        "merchant_id": "merchant_1668273825",
        "status": "succeeded",
        "amount": 6540,
        "net_amount": 6540,
        "amount_capturable": 6540,
        "amount_received": 6540,
        "connector": "stripe",
        "client_secret": "pay_U42c409qyHwOkWo3vK60_secret_el9ksDkiB8hi6j9N78yo",
        "created": "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"
        },
        "description": "It's my first payment request",
        "refunds": [
          {
            "refund_id": "<string>",
            "payment_id": "<string>",
            "amount": 6540,
            "currency": "<string>",
            "status": "succeeded",
            "reason": "<string>",
            "metadata": {},
            "error_message": "<string>",
            "error_code": "<string>",
            "created_at": "2023-11-07T05:31:56Z",
            "updated_at": "2023-11-07T05:31:56Z",
            "connector": "stripe",
            "profile_id": "<string>",
            "merchant_connector_id": "<string>",
            "charges": {
              "charge_id": "<string>",
              "revert_platform_fee": true,
              "revert_transfer": true
            }
          }
        ],
        "disputes": [
          {
            "dispute_id": "<string>",
            "dispute_stage": "pre_dispute",
            "dispute_status": "dispute_opened",
            "connector_status": "<string>",
            "connector_dispute_id": "<string>",
            "connector_reason": "<string>",
            "connector_reason_code": "<string>",
            "challenge_required_by": "2023-11-07T05:31:56Z",
            "connector_created_at": "2023-11-07T05:31:56Z",
            "connector_updated_at": "2023-11-07T05:31:56Z",
            "created_at": "2023-11-07T05:31:56Z"
          }
        ],
        "attempts": [
          {
            "attempt_id": "<string>",
            "status": "started",
            "amount": 6540,
            "currency": "AED",
            "connector": "<string>",
            "error_message": "<string>",
            "payment_method": "card",
            "connector_transaction_id": "<string>",
            "capture_method": "automatic",
            "authentication_type": "three_ds",
            "cancellation_reason": "<string>",
            "mandate_id": "<string>",
            "error_code": "<string>",
            "payment_token": "<string>",
            "connector_metadata": "<any>",
            "payment_experience": "redirect_to_url",
            "payment_method_type": "ach",
            "reference_id": "993672945374576J",
            "unified_code": "<string>",
            "unified_message": "<string>",
            "client_source": "<string>",
            "client_version": "<string>"
          }
        ],
        "captures": [
          {
            "capture_id": "<string>",
            "status": "started",
            "amount": 6540,
            "currency": "AED",
            "connector": "<string>",
            "authorized_attempt_id": "<string>",
            "connector_capture_id": "<string>",
            "capture_sequence": 123,
            "error_message": "<string>",
            "error_code": "<string>",
            "error_reason": "<string>",
            "reference_id": "<string>"
          }
        ],
        "mandate_id": "mandate_iwer89rnjef349dni3",
        "mandate_data": {
          "update_mandate_id": "<string>",
          "customer_acceptance": {
            "acceptance_type": "online",
            "accepted_at": "2022-09-10T10:11:12Z",
            "online": {
              "ip_address": "123.32.25.123",
              "user_agent": "<string>"
            }
          },
          "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": {
          "card": {
            "last4": "<string>",
            "card_type": "<string>",
            "card_network": "Visa",
            "card_issuer": "<string>",
            "card_issuing_country": "<string>",
            "card_isin": "<string>",
            "card_extended_bin": "<string>",
            "card_exp_month": "<string>",
            "card_exp_year": "<string>",
            "card_holder_name": "<string>",
            "payment_checks": "<any>",
            "authentication_data": "<any>"
          },
          "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"
            },
            "phone": {
              "number": "9123456789",
              "country_code": "+1"
            },
            "email": "<string>"
          }
        },
        "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"
          },
          "phone": {
            "number": "9123456789",
            "country_code": "+1"
          },
          "email": "<string>"
        },
        "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"
          },
          "phone": {
            "number": "9123456789",
            "country_code": "+1"
          },
          "email": "<string>"
        },
        "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": "<string>",
          "type": "redirect_to_url"
        },
        "cancellation_reason": "<string>",
        "error_code": "E0001",
        "error_message": "Failed while verifying the card",
        "unified_code": "<string>",
        "unified_message": "<string>",
        "payment_experience": "redirect_to_url",
        "payment_method_type": "ach",
        "connector_label": "stripe_US_food",
        "business_country": "AF",
        "business_label": "<string>",
        "business_sub_label": "<string>",
        "allowed_payment_method_types": [
          "ach"
        ],
        "ephemeral_key": {
          "customer_id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
          "created_at": 123,
          "expires": 123,
          "secret": "<string>"
        },
        "manual_retry_allowed": true,
        "connector_transaction_id": "993672945374576J",
        "frm_message": {
          "frm_name": "<string>",
          "frm_transaction_id": "<string>",
          "frm_transaction_type": "<string>",
          "frm_status": "<string>",
          "frm_score": 123,
          "frm_reason": "<any>",
          "frm_error": "<string>"
        },
        "metadata": {},
        "connector_metadata": {
          "apple_pay": {
            "session_token_data": {
              "payment_processing_certificate": "<string>",
              "payment_processing_certificate_key": "<string>",
              "payment_processing_details_at": "Hyperswitch",
              "certificate": "<string>",
              "certificate_keys": "<string>",
              "merchant_identifier": "<string>",
              "display_name": "<string>",
              "initiative": "web",
              "initiative_context": "<string>",
              "merchant_business_country": "AF"
            }
          },
          "airwallex": {
            "payload": "<string>"
          },
          "noon": {
            "order_category": "<string>"
          }
        },
        "feature_metadata": {
          "redirect_response": {
            "param": "<string>",
            "json_payload": {}
          }
        },
        "reference_id": "993672945374576J",
        "payment_link": {
          "link": "<string>",
          "payment_link_id": "<string>"
        },
        "profile_id": "<string>",
        "surcharge_details": {
          "surcharge_amount": 6540,
          "tax_amount": 123
        },
        "attempt_count": 123,
        "merchant_decision": "<string>",
        "merchant_connector_id": "<string>",
        "incremental_authorization_allowed": true,
        "authorization_count": 123,
        "incremental_authorizations": [
          {
            "authorization_id": "<string>",
            "amount": 6540,
            "status": "success",
            "error_code": "<string>",
            "error_message": "<string>",
            "previously_authorized_amount": 123
          }
        ],
        "external_authentication_details": {
          "authentication_flow": "challenge",
          "electronic_commerce_indicator": "<string>",
          "status": "started",
          "ds_transaction_id": "<string>",
          "version": "<string>",
          "error_code": "<string>",
          "error_message": "<string>"
        },
        "external_3ds_authentication_attempted": true,
        "expires_on": "2022-09-10T10:11:12Z",
        "fingerprint": "<string>",
        "browser_info": {
          "color_depth": 1,
          "java_enabled": true,
          "java_script_enabled": true,
          "language": "<string>",
          "screen_height": 1,
          "screen_width": 1,
          "time_zone": 123,
          "ip_address": "<string>",
          "accept_header": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8",
          "user_agent": "<string>"
        },
        "payment_method_id": "<string>",
        "payment_method_status": "active",
        "updated": "2022-09-10T10:11:12Z",
        "charges": {
          "charge_id": "<string>",
          "charge_type": {
            "Stripe": "direct"
          },
          "application_fees": 6540,
          "transfer_account_id": "<string>"
        },
        "frm_metadata": {}
      }
    ]
  }
]

Authorizations

api-key

string

headerrequired

Use the API key created under your merchant account from the HyperSwitch dashboard. API key is used to authenticate API requests from your merchant server only. Don't expose this key on a website or embed it in a mobile application.

Query Parameters

customer_id

string

required

The identifier for the customer

starting_after

string

required

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

ending_before

string

required

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

limit

integer

required

Limit on the number of objects to return

created

string

required

The time at which payment is created

created_lt

string

required

Time less than the payment created time

created_gt

string

required

Time greater than the payment created time

created_lte

string

required

Time less than or equals to the payment created time

created_gte

string

required

Time greater than or equals to the payment created time

Response

200 - application/json

size

integer

required

The number of payments included in the list

data

object[]

required

data.payment_id

string | null

Unique identifier for the payment. This ensures idempotency for multiple payments that have been done by a single merchant.

data.merchant_id

string | null

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

data.status

enum<string>

required

The status of the current payment that was made

Available options:

succeeded,

failed,

cancelled,

processing,

requires_customer_action,

requires_merchant_action,

requires_payment_method,

requires_confirmation,

requires_capture,

partially_captured,

partially_captured_and_capturable

data.amount

integer

required

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

data.net_amount

integer

required

The payment net amount. net_amount = amount + surcharge_details.surcharge_amount + surcharge_details.tax_amount, If no surcharge_details, net_amount = amount

data.amount_capturable

integer

required

The maximum amount that could be captured from the payment

data.amount_received

integer

required

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

data.connector

string | null

The connector used for the payment

data.client_secret

string | null

It's a token used for client side verification.

data.created

string | null

Time when the payment was created

data.currency

enum<string>

required

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

Available options:

AED,

ALL,

AMD,

ANG,

AOA,

ARS,

AUD,

AWG,

AZN,

BAM,

BBD,

BDT,

BGN,

BHD,

BIF,

BMD,

BND,

BOB,

BRL,

BSD,

BWP,

BYN,

BZD,

CAD,

CHF,

CLP,

CNY,

COP,

CRC,

CUP,

CVE,

CZK,

DJF,

DKK,

DOP,

DZD,

EGP,

ETB,

EUR,

FJD,

FKP,

GBP,

GEL,

GHS,

GIP,

GMD,

GNF,

GTQ,

GYD,

HKD,

HNL,

HRK,

HTG,

HUF,

IDR,

ILS,

INR,

IQD,

JMD,

JOD,

JPY,

KES,

KGS,

KHR,

KMF,

KRW,

KWD,

KYD,

KZT,

LAK,

LBP,

LKR,

LRD,

LSL,

LYD,

MAD,

MDL,

MGA,

MKD,

MMK,

MNT,

MOP,

MRU,

MUR,

MVR,

MWK,

MXN,

MYR,

MZN,

NAD,

NGN,

NIO,

NOK,

NPR,

NZD,

OMR,

PAB,

PEN,

PGK,

PHP,

PKR,

PLN,

PYG,

QAR,

RON,

RSD,

RUB,

RWF,

SAR,

SBD,

SCR,

SEK,

SGD,

SHP,

SLE,

SLL,

SOS,

SRD,

SSP,

STN,

SVC,

SZL,

THB,

TND,

TOP,

TRY,

TTD,

TWD,

TZS,

UAH,

UGX,

USD,

UYU,

UZS,

VES,

VND,

VUV,

WST,

XAF,

XCD,

XOF,

XPF,

YER,

ZAR,

ZMW

data.customer_id

string | null

deprecated

The identifier for the customer object. If not provided the customer ID will be autogenerated. This field will be deprecated soon. Please refer to customer.id

data.customer

object

Details of customer attached to this payment

data.description

string | null

A description of the payment

data.refunds

object[] | null

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

data.refunds.refund_id

string

required

Unique Identifier for the refund

data.refunds.payment_id

string

required

The payment id against which refund is initiated

data.refunds.amount

integer

required

The refund amount, which should be less than or equal to the total payment amount. Amount for the payment in lowest denomination of the currency. (i.e) in cents for USD denomination, in paisa for INR denomination etc

data.refunds.currency

string

required

The three-letter ISO currency code

data.refunds.status

enum<string>

required

The status for refunds

Available options:

succeeded,

failed,

pending,

review

data.refunds.reason

string | null

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

data.refunds.metadata

object | null

You can specify up to 50 keys, with key names up to 40 characters long and values up to 500 characters long. Metadata is useful for storing additional, structured information on an object

data.refunds.error_message

string | null

The error message

data.refunds.error_code

string | null

The code for the error

data.refunds.created_at

string | null

The timestamp at which refund is created

data.refunds.updated_at

string | null

The timestamp at which refund is updated

data.refunds.connector

string

required

The connector used for the refund and the corresponding payment

data.refunds.profile_id

string | null

The id of business profile for this refund

data.refunds.merchant_connector_id

string | null

The merchant_connector_id of the processor through which this payment went through

data.refunds.charges

object

Charge object for refunds

data.disputes

object[] | null

List of dispute that happened on this intent

data.attempts

object[] | null

List of attempts that happened on this intent

data.attempts.attempt_id

string

required

Unique identifier for the attempt

data.attempts.status

enum<string>

required

The status of the attempt

Available options:

started,

authentication_failed,

router_declined,

authentication_pending,

authentication_successful,

authorized,

authorization_failed,

charged,

authorizing,

cod_initiated,

voided,

void_initiated,

capture_initiated,

capture_failed,

void_failed,

auto_refunded,

partial_charged,

partial_charged_and_chargeable,

unresolved,

pending,

failure,

payment_method_awaited,

confirmation_awaited,

device_data_collection_pending

data.attempts.amount

integer

required

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

data.attempts.currency

enum<string>

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

Available options:

AED,

ALL,

AMD,

ANG,

AOA,

ARS,

AUD,

AWG,

AZN,

BAM,

BBD,

BDT,

BGN,

BHD,

BIF,

BMD,

BND,

BOB,

BRL,

BSD,

BWP,

BYN,

BZD,

CAD,

CHF,

CLP,

CNY,

COP,

CRC,

CUP,

CVE,

CZK,

DJF,

DKK,

DOP,

DZD,

EGP,

ETB,

EUR,

FJD,

FKP,

GBP,

GEL,

GHS,

GIP,

GMD,

GNF,

GTQ,

GYD,

HKD,

HNL,

HRK,

HTG,

HUF,

IDR,

ILS,

INR,

IQD,

JMD,

JOD,

JPY,

KES,

KGS,

KHR,

KMF,

KRW,

KWD,

KYD,

KZT,

LAK,

LBP,

LKR,

LRD,

LSL,

LYD,

MAD,

MDL,

MGA,

MKD,

MMK,

MNT,

MOP,

MRU,

MUR,

MVR,

MWK,

MXN,

MYR,

MZN,

NAD,

NGN,

NIO,

NOK,

NPR,

NZD,

OMR,

PAB,

PEN,

PGK,

PHP,

PKR,

PLN,

PYG,

QAR,

RON,

RSD,

RUB,

RWF,

SAR,

SBD,

SCR,

SEK,

SGD,

SHP,

SLE,

SLL,

SOS,

SRD,

SSP,

STN,

SVC,

SZL,

THB,

TND,

TOP,

TRY,

TTD,

TWD,

TZS,

UAH,

UGX,

USD,

UYU,

UZS,

VES,

VND,

VUV,

WST,

XAF,

XCD,

XOF,

XPF,

YER,

ZAR,

ZMW

data.attempts.connector

string | null

The connector used for the payment

data.attempts.error_message

string | null

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

data.attempts.payment_method

enum<string>

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

Available options:

card,

card_redirect,

pay_later,

wallet,

bank_redirect,

bank_transfer,

crypto,

bank_debit,

reward,

real_time_payment,

upi,

voucher,

gift_card

data.attempts.connector_transaction_id

string | null

A unique identifier for a payment provided by the connector

data.attempts.capture_method

enum<string>

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

Available options:

automatic,

manual,

manual_multiple,

scheduled

data.attempts.authentication_type

enum<string>

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

Available options:

three_ds,

no_three_ds

data.attempts.cancellation_reason

string | null

If the payment was cancelled the reason provided here

data.attempts.mandate_id

string | null

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

data.attempts.error_code

string | null

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

data.attempts.payment_token

string | null

Provide a reference to a stored payment method

data.attempts.connector_metadata

any | null

additional data related to some connectors

data.attempts.payment_experience

enum<string>

To indicate the type of payment experience that the customer would go through

Available options:

redirect_to_url,

invoke_sdk_client,

display_qr_code,

one_click,

link_wallet,

invoke_payment_app,

display_wait_screen

data.attempts.payment_method_type

enum<string>

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

Available options:

ach,

affirm,

afterpay_clearpay,

alfamart,

ali_pay,

ali_pay_hk,

alma,

apple_pay,

atome,

bacs,

bancontact_card,

becs,

benefit,

bizum,

blik,

boleto,

bca_bank_transfer,

bni_va,

bri_va,

card_redirect,

cimb_va,

classic,

credit,

crypto_currency,

cashapp,

dana,

danamon_va,

debit,

duit_now,

efecty,

eps,

fps,

evoucher,

giropay,

givex,

google_pay,

go_pay,

gcash,

ideal,

interac,

indomaret,

klarna,

kakao_pay,

local_bank_redirect,

mandiri_va,

knet,

mb_way,

mobile_pay,

momo,

momo_atm,

multibanco,

online_banking_thailand,

online_banking_czech_republic,

online_banking_finland,

online_banking_fpx,

online_banking_poland,

online_banking_slovakia,

oxxo,

pago_efectivo,

permata_bank_transfer,

open_banking_uk,

pay_bright,

paypal,

pix,

pay_safe_card,

przelewy24,

prompt_pay,

pse,

red_compra,

red_pagos,

samsung_pay,

sepa,

sofort,

swish,

touch_n_go,

trustly,

twint,

upi_collect,

upi_intent,

vipps,

viet_qr,

venmo,

walley,

we_chat_pay,

seven_eleven,

lawson,

mini_stop,

family_mart,

seicomart,

pay_easy,

local_bank_transfer,

mifinity

data.attempts.reference_id

string | null

reference to the payment at connector side

data.attempts.unified_code

string | null

error code unified across the connectors is received here if there was an error while calling connector

data.attempts.unified_message

string | null

error message unified across the connectors is received here if there was an error while calling connector

data.attempts.client_source

string | null

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

data.attempts.client_version

string | null

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

data.captures

object[] | null

List of captures done on latest attempt

data.captures.capture_id

string

required

unique identifier for the capture

data.captures.status

enum<string>

required

Available options:

started,

charged,

pending,

failed

data.captures.amount

integer

required

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

data.captures.currency

enum<string>

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

Available options:

AED,

ALL,

AMD,

ANG,

AOA,

ARS,

AUD,

AWG,

AZN,

BAM,

BBD,

BDT,

BGN,

BHD,

BIF,

BMD,

BND,

BOB,

BRL,

BSD,

BWP,

BYN,

BZD,

CAD,

CHF,

CLP,

CNY,

COP,

CRC,

CUP,

CVE,

CZK,

DJF,

DKK,

DOP,

DZD,

EGP,

ETB,

EUR,

FJD,

FKP,

GBP,

GEL,

GHS,

GIP,

GMD,

GNF,

GTQ,

GYD,

HKD,

HNL,

HRK,

HTG,

HUF,

IDR,

ILS,

INR,

IQD,

JMD,

JOD,

JPY,

KES,

KGS,

KHR,

KMF,

KRW,

KWD,

KYD,

KZT,

LAK,

LBP,

LKR,

LRD,

LSL,

LYD,

MAD,

MDL,

MGA,

MKD,

MMK,

MNT,

MOP,

MRU,

MUR,

MVR,

MWK,

MXN,

MYR,

MZN,

NAD,

NGN,

NIO,

NOK,

NPR,

NZD,

OMR,

PAB,

PEN,

PGK,

PHP,

PKR,

PLN,

PYG,

QAR,

RON,

RSD,

RUB,

RWF,

SAR,

SBD,

SCR,

SEK,

SGD,

SHP,

SLE,

SLL,

SOS,

SRD,

SSP,

STN,

SVC,

SZL,

THB,

TND,

TOP,

TRY,

TTD,

TWD,

TZS,

UAH,

UGX,

USD,

UYU,

UZS,

VES,

VND,

VUV,

WST,

XAF,

XCD,

XOF,

XPF,

YER,

ZAR,

ZMW

data.captures.connector

string

required

The connector used for the payment

data.captures.authorized_attempt_id

string

required

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

data.captures.connector_capture_id

string | null

A unique identifier for a capture provided by the connector

data.captures.capture_sequence

integer

required

sequence number of this capture

data.captures.error_message

string | null

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

data.captures.error_code

string | null

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

data.captures.error_reason

string | null

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

data.captures.reference_id

string | null

reference to the capture at connector side

data.mandate_id

string | null

A unique identifier to link the payment to a mandate, can be used instead of payment_method_data, in case of setting up recurring payments

data.mandate_data

object

data.mandate_data.update_mandate_id

string | null

A way to update the mandate's payment method details

data.mandate_data.customer_acceptance

object

We will be Passing this "CustomerAcceptance" object during Payments-Confirm. The customer_acceptance sub object is usually passed by the SDK or client

data.mandate_data.mandate_type

object

data.setup_future_usage

enum<string>

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

Available options:

off_session,

on_session

data.off_session

boolean | null

Set to true to indicate that the customer is not in your checkout flow during this payment, and therefore is unable to authenticate. This parameter is intended for scenarios where you collect card details and charge them later. This parameter can only be used with confirm=true.

data.capture_on

string | null

A timestamp (ISO 8601 code) that determines when the payment should be captured. Providing this field will automatically set capture to true

data.capture_method

enum<string>

Available options:

automatic,

manual,

manual_multiple,

scheduled

data.payment_method

enum<string>

required

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

Available options:

card,

card_redirect,

pay_later,

wallet,

bank_redirect,

bank_transfer,

crypto,

bank_debit,

reward,

real_time_payment,

upi,

voucher,

gift_card

data.payment_method_data

object

data.payment_method_data.card

object

required

data.payment_method_data.billing

object

data.payment_method_data.billing.address

object

Address details

data.payment_method_data.billing.phone

object

data.payment_method_data.billing.email

string | null

data.payment_token

string | null

Provide a reference to a stored payment method

data.shipping

object

data.billing

object

data.order_details

object[] | null

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

data.email

string | null

deprecated

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

data.name

string | null

deprecated

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

data.phone

string | null

deprecated

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

data.return_url

string | null

The URL to redirect after the completion of the operation

data.authentication_type

enum<string>

Available options:

three_ds,

no_three_ds

data.statement_descriptor_name

string | null

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

data.statement_descriptor_suffix

string | null

Provides information about a card payment that customers see on their statements. Concatenated with the prefix (shortened descriptor) or statement descriptor that’s set on the account to form the complete statement descriptor. Maximum 255 characters for the concatenated descriptor.

data.next_action

object

Contains the url for redirection flow

data.cancellation_reason

string | null

If the payment was cancelled the reason provided here

data.error_code

string | null

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

data.error_message

string | null

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

data.unified_code

string | null

error code unified across the connectors is received here if there was an error while calling connector

data.unified_message

string | null

error message unified across the connectors is received here if there was an error while calling connector

data.payment_experience

enum<string>

To indicate the type of payment experience that the customer would go through

Available options:

redirect_to_url,

invoke_sdk_client,

display_qr_code,

one_click,

link_wallet,

invoke_payment_app,

display_wait_screen

data.payment_method_type

enum<string>

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

Available options:

ach,

affirm,

afterpay_clearpay,

alfamart,

ali_pay,

ali_pay_hk,

alma,

apple_pay,

atome,

bacs,

bancontact_card,

becs,

benefit,

bizum,

blik,

boleto,

bca_bank_transfer,

bni_va,

bri_va,

card_redirect,

cimb_va,

classic,

credit,

crypto_currency,

cashapp,

dana,

danamon_va,

debit,

duit_now,

efecty,

eps,

fps,

evoucher,

giropay,

givex,

google_pay,

go_pay,

gcash,

ideal,

interac,

indomaret,

klarna,

kakao_pay,

local_bank_redirect,

mandiri_va,

knet,

mb_way,

mobile_pay,

momo,

momo_atm,

multibanco,

online_banking_thailand,

online_banking_czech_republic,

online_banking_finland,

online_banking_fpx,

online_banking_poland,

online_banking_slovakia,

oxxo,

pago_efectivo,

permata_bank_transfer,

open_banking_uk,

pay_bright,

paypal,

pix,

pay_safe_card,

przelewy24,

prompt_pay,

pse,

red_compra,

red_pagos,

samsung_pay,

sepa,

sofort,

swish,

touch_n_go,

trustly,

twint,

upi_collect,

upi_intent,

vipps,

viet_qr,

venmo,

walley,

we_chat_pay,

seven_eleven,

lawson,

mini_stop,

family_mart,

seicomart,

pay_easy,

local_bank_transfer,

mifinity

data.connector_label

string | null

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

data.business_country

enum<string>

Available options:

AF,

AX,

AL,

DZ,

AS,

AD,

AO,

AI,

AQ,

AG,

AR,

AM,

AW,

AU,

AT,

AZ,

BS,

BH,

BD,

BB,

BY,

BE,

BZ,

BJ,

BM,

BT,

BO,

BQ,

BA,

BW,

BV,

BR,

IO,

BN,

BG,

BF,

BI,

KH,

CM,

CA,

CV,

KY,

CF,

TD,

CL,

CN,

CX,

CC,

CO,

KM,

CG,

CD,

CK,

CR,

CI,

HR,

CU,

CW,

CY,

CZ,

DK,

DJ,

DM,

DO,

EC,

EG,

SV,

GQ,

ER,

EE,

ET,

FK,

FO,

FJ,

FI,

FR,

GF,

PF,

TF,

GA,

GM,

GE,

DE,

GH,

GI,

GR,

GL,

GD,

GP,

GU,

GT,

GG,

GN,

GW,

GY,

HT,

HM,

VA,

HN,

HK,

HU,

IS,

IN,

ID,

IR,

IQ,

IE,

IM,

IL,

IT,

JM,

JP,

JE,

JO,

KZ,

KE,

KI,

KP,

KR,

KW,

KG,

LA,

LV,

LB,

LS,

LR,

LY,

LI,

LT,

LU,

MO,

MK,

MG,

MW,

MY,

MV,

ML,

MT,

MH,

MQ,

MR,

MU,

YT,

MX,

FM,

MD,

MC,

MN,

ME,

MS,

MA,

MZ,

MM,

NA,

NR,

NP,

NL,

NC,

NZ,

NI,

NE,

NG,

NU,

NF,

MP,

NO,

OM,

PK,

PW,

PS,

PA,

PG,

PY,

PE,

PH,

PN,

PL,

PT,

PR,

QA,

RE,

RO,

RU,

RW,

BL,

SH,

KN,

LC,

MF,

PM,

VC,

WS,

SM,

ST,

SA,

SN,

RS,

SC,

SL,

SG,

SX,

SK,

SI,

SB,

SO,

ZA,

GS,

SS,

ES,

LK,

SD,

SR,

SJ,

SZ,

SE,

CH,

SY,

TW,

TJ,

TZ,

TH,

TL,

TG,

TK,

TO,

TT,

TN,

TR,

TM,

TC,

TV,

UG,

UA,

AE,

GB,

UM,

UY,

UZ,

VU,

VE,

VN,

VG,

VI,

WF,

EH,

YE,

ZM,

ZW,

US

data.business_label

string | null

The business label of merchant for this payment

data.business_sub_label

string | null

The business_sub_label for this payment

data.allowed_payment_method_types

enum<string>[] | null

Allowed Payment Method Types for a given PaymentIntent

Available options:

ach,

affirm,

afterpay_clearpay,

alfamart,

ali_pay,

ali_pay_hk,

alma,

apple_pay,

atome,

bacs,

bancontact_card,

becs,

benefit,

bizum,

blik,

boleto,

bca_bank_transfer,

bni_va,

bri_va,

card_redirect,

cimb_va,

classic,

credit,

crypto_currency,

cashapp,

dana,

danamon_va,

debit,

duit_now,

efecty,

eps,

fps,

evoucher,

giropay,

givex,

google_pay,

go_pay,

gcash,

ideal,

interac,

indomaret,

klarna,

kakao_pay,

local_bank_redirect,

mandiri_va,

knet,

mb_way,

mobile_pay,

momo,

momo_atm,

multibanco,

online_banking_thailand,

online_banking_czech_republic,

online_banking_finland,

online_banking_fpx,

online_banking_poland,

online_banking_slovakia,

oxxo,

pago_efectivo,

permata_bank_transfer,

open_banking_uk,

pay_bright,

paypal,

pix,

pay_safe_card,

przelewy24,

prompt_pay,

pse,

red_compra,

red_pagos,

samsung_pay,

sepa,

sofort,

swish,

touch_n_go,

trustly,

twint,

upi_collect,

upi_intent,

vipps,

viet_qr,

venmo,

walley,

we_chat_pay,

seven_eleven,

lawson,

mini_stop,

family_mart,

seicomart,

pay_easy,

local_bank_transfer,

mifinity

data.ephemeral_key

object

ephemeral_key for the customer_id mentioned

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

data.connector_transaction_id

string | null

A unique identifier for a payment provided by the connector

data.frm_message

object

frm message is an object sent inside the payments response...when frm is invoked, its value is Some(...), else its None

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

data.connector_metadata

object

additional data related to some connectors

data.connector_metadata.apple_pay

object

data.connector_metadata.apple_pay.session_token_data

object

data.connector_metadata.airwallex

object

data.connector_metadata.noon

object

data.feature_metadata

object

additional data that might be required by hyperswitch

data.reference_id

string | null

reference(Identifier) to the payment at connector side

data.payment_link

object

data.profile_id

string | null

The business profile that is associated with this payment

data.surcharge_details

object

details of surcharge applied on this payment, if applicable

data.attempt_count

integer

required

total number of attempts associated with this payment

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

data.merchant_connector_id

string | null

Identifier of the connector ( merchant connector account ) which was chosen to make the payment

data.incremental_authorization_allowed

boolean | null

If true, incremental authorization can be performed on this payment, in case the funds authorized initially fall short.

data.authorization_count

integer | null

Total number of authorizations happened in an incremental_authorization payment

data.incremental_authorizations

object[] | null

List of incremental authorizations happened to the payment

data.external_authentication_details

object

Details of external authentication

data.external_3ds_authentication_attempted

boolean | null

Flag indicating if external 3ds authentication is made or not

data.expires_on

string | null

Date Time for expiry of the payment

data.fingerprint

string | null

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

data.browser_info

object

Browser information to be used for 3DS 2.0

data.payment_method_id

string | null

Identifier for Payment Method

data.payment_method_status

enum<string>

Payment Method Status

Available options:

active,

inactive,

processing,

awaiting_data

data.updated

string | null

Date time at which payment was updated

data.charges

object

Fee information to be charged on the payment being collected

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

Payments Link - Retrieve Payments - External 3DS Authentication

curl --request GET \
  --url https://sandbox.hyperswitch.io/payments/list \
  --header 'api-key: <api-key>'

[
  {
    "size": 1,
    "data": [
      {
        "payment_id": "pay_mbabizu24mvu3mela5njyhpit4",
        "merchant_id": "merchant_1668273825",
        "status": "succeeded",
        "amount": 6540,
        "net_amount": 6540,
        "amount_capturable": 6540,
        "amount_received": 6540,
        "connector": "stripe",
        "client_secret": "pay_U42c409qyHwOkWo3vK60_secret_el9ksDkiB8hi6j9N78yo",
        "created": "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"
        },
        "description": "It's my first payment request",
        "refunds": [
          {
            "refund_id": "<string>",
            "payment_id": "<string>",
            "amount": 6540,
            "currency": "<string>",
            "status": "succeeded",
            "reason": "<string>",
            "metadata": {},
            "error_message": "<string>",
            "error_code": "<string>",
            "created_at": "2023-11-07T05:31:56Z",
            "updated_at": "2023-11-07T05:31:56Z",
            "connector": "stripe",
            "profile_id": "<string>",
            "merchant_connector_id": "<string>",
            "charges": {
              "charge_id": "<string>",
              "revert_platform_fee": true,
              "revert_transfer": true
            }
          }
        ],
        "disputes": [
          {
            "dispute_id": "<string>",
            "dispute_stage": "pre_dispute",
            "dispute_status": "dispute_opened",
            "connector_status": "<string>",
            "connector_dispute_id": "<string>",
            "connector_reason": "<string>",
            "connector_reason_code": "<string>",
            "challenge_required_by": "2023-11-07T05:31:56Z",
            "connector_created_at": "2023-11-07T05:31:56Z",
            "connector_updated_at": "2023-11-07T05:31:56Z",
            "created_at": "2023-11-07T05:31:56Z"
          }
        ],
        "attempts": [
          {
            "attempt_id": "<string>",
            "status": "started",
            "amount": 6540,
            "currency": "AED",
            "connector": "<string>",
            "error_message": "<string>",
            "payment_method": "card",
            "connector_transaction_id": "<string>",
            "capture_method": "automatic",
            "authentication_type": "three_ds",
            "cancellation_reason": "<string>",
            "mandate_id": "<string>",
            "error_code": "<string>",
            "payment_token": "<string>",
            "connector_metadata": "<any>",
            "payment_experience": "redirect_to_url",
            "payment_method_type": "ach",
            "reference_id": "993672945374576J",
            "unified_code": "<string>",
            "unified_message": "<string>",
            "client_source": "<string>",
            "client_version": "<string>"
          }
        ],
        "captures": [
          {
            "capture_id": "<string>",
            "status": "started",
            "amount": 6540,
            "currency": "AED",
            "connector": "<string>",
            "authorized_attempt_id": "<string>",
            "connector_capture_id": "<string>",
            "capture_sequence": 123,
            "error_message": "<string>",
            "error_code": "<string>",
            "error_reason": "<string>",
            "reference_id": "<string>"
          }
        ],
        "mandate_id": "mandate_iwer89rnjef349dni3",
        "mandate_data": {
          "update_mandate_id": "<string>",
          "customer_acceptance": {
            "acceptance_type": "online",
            "accepted_at": "2022-09-10T10:11:12Z",
            "online": {
              "ip_address": "123.32.25.123",
              "user_agent": "<string>"
            }
          },
          "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": {
          "card": {
            "last4": "<string>",
            "card_type": "<string>",
            "card_network": "Visa",
            "card_issuer": "<string>",
            "card_issuing_country": "<string>",
            "card_isin": "<string>",
            "card_extended_bin": "<string>",
            "card_exp_month": "<string>",
            "card_exp_year": "<string>",
            "card_holder_name": "<string>",
            "payment_checks": "<any>",
            "authentication_data": "<any>"
          },
          "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"
            },
            "phone": {
              "number": "9123456789",
              "country_code": "+1"
            },
            "email": "<string>"
          }
        },
        "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"
          },
          "phone": {
            "number": "9123456789",
            "country_code": "+1"
          },
          "email": "<string>"
        },
        "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"
          },
          "phone": {
            "number": "9123456789",
            "country_code": "+1"
          },
          "email": "<string>"
        },
        "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": "<string>",
          "type": "redirect_to_url"
        },
        "cancellation_reason": "<string>",
        "error_code": "E0001",
        "error_message": "Failed while verifying the card",
        "unified_code": "<string>",
        "unified_message": "<string>",
        "payment_experience": "redirect_to_url",
        "payment_method_type": "ach",
        "connector_label": "stripe_US_food",
        "business_country": "AF",
        "business_label": "<string>",
        "business_sub_label": "<string>",
        "allowed_payment_method_types": [
          "ach"
        ],
        "ephemeral_key": {
          "customer_id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
          "created_at": 123,
          "expires": 123,
          "secret": "<string>"
        },
        "manual_retry_allowed": true,
        "connector_transaction_id": "993672945374576J",
        "frm_message": {
          "frm_name": "<string>",
          "frm_transaction_id": "<string>",
          "frm_transaction_type": "<string>",
          "frm_status": "<string>",
          "frm_score": 123,
          "frm_reason": "<any>",
          "frm_error": "<string>"
        },
        "metadata": {},
        "connector_metadata": {
          "apple_pay": {
            "session_token_data": {
              "payment_processing_certificate": "<string>",
              "payment_processing_certificate_key": "<string>",
              "payment_processing_details_at": "Hyperswitch",
              "certificate": "<string>",
              "certificate_keys": "<string>",
              "merchant_identifier": "<string>",
              "display_name": "<string>",
              "initiative": "web",
              "initiative_context": "<string>",
              "merchant_business_country": "AF"
            }
          },
          "airwallex": {
            "payload": "<string>"
          },
          "noon": {
            "order_category": "<string>"
          }
        },
        "feature_metadata": {
          "redirect_response": {
            "param": "<string>",
            "json_payload": {}
          }
        },
        "reference_id": "993672945374576J",
        "payment_link": {
          "link": "<string>",
          "payment_link_id": "<string>"
        },
        "profile_id": "<string>",
        "surcharge_details": {
          "surcharge_amount": 6540,
          "tax_amount": 123
        },
        "attempt_count": 123,
        "merchant_decision": "<string>",
        "merchant_connector_id": "<string>",
        "incremental_authorization_allowed": true,
        "authorization_count": 123,
        "incremental_authorizations": [
          {
            "authorization_id": "<string>",
            "amount": 6540,
            "status": "success",
            "error_code": "<string>",
            "error_message": "<string>",
            "previously_authorized_amount": 123
          }
        ],
        "external_authentication_details": {
          "authentication_flow": "challenge",
          "electronic_commerce_indicator": "<string>",
          "status": "started",
          "ds_transaction_id": "<string>",
          "version": "<string>",
          "error_code": "<string>",
          "error_message": "<string>"
        },
        "external_3ds_authentication_attempted": true,
        "expires_on": "2022-09-10T10:11:12Z",
        "fingerprint": "<string>",
        "browser_info": {
          "color_depth": 1,
          "java_enabled": true,
          "java_script_enabled": true,
          "language": "<string>",
          "screen_height": 1,
          "screen_width": 1,
          "time_zone": 123,
          "ip_address": "<string>",
          "accept_header": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8",
          "user_agent": "<string>"
        },
        "payment_method_id": "<string>",
        "payment_method_status": "active",
        "updated": "2022-09-10T10:11:12Z",
        "charges": {
          "charge_id": "<string>",
          "charge_type": {
            "Stripe": "direct"
          },
          "application_fees": 6540,
          "transfer_account_id": "<string>"
        },
        "frm_metadata": {}
      }
    ]
  }
]

Payment Methods

Customers

Mandates

Refunds

Disputes

Merchant Account

Business Profile

API Key

Merchant Connector Account

Payouts

Event

GSM (Global Status Mapping)

Poll

Blocklist

Routing

Schemas

Payments - List

Authorizations

Query Parameters

Response