Skip to main content
POST
/
v2
/
payments
/
{id}
/
confirm-intent
Payments - Confirm Intent
curl --request POST \
  --url https://sandbox.hyperswitch.io/v2/payments/{id}/confirm-intent \
  --header 'Content-Type: application/json' \
  --header 'X-Profile-Id: <x-profile-id>' \
  --header 'api-key: <api-key>' \
  --data '{
  "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_subtype": "credit",
  "payment_method_type": "card"
}'
{
  "id": "12345_pay_01926c58bc6e77c09e809964e72af8c8",
  "status": "succeeded",
  "amount": {
    "order_amount": 6540,
    "currency": "AED",
    "shipping_cost": 123,
    "order_tax_amount": 123,
    "external_tax_calculation": "skip",
    "surcharge_calculation": "skip",
    "surcharge_amount": 123,
    "tax_on_surcharge": 123,
    "net_amount": 123,
    "amount_to_capture": 123,
    "amount_capturable": 123,
    "amount_captured": 123
  },
  "customer_id": "12345_cus_01926c58bc6e77c09e809964e72af8c8",
  "connector": "stripe",
  "created": "2022-09-10T10:11:12Z",
  "modified_at": "2022-09-10T10:11:12Z",
  "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",
        "origin_zip": "08807"
      },
      "phone": {
        "number": "9123456789",
        "country_code": "+1"
      },
      "email": "<string>"
    }
  },
  "payment_method_type": "card",
  "payment_method_subtype": "ach",
  "connector_transaction_id": "993672945374576J",
  "connector_reference_id": "993672945374576J",
  "merchant_connector_id": "<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>",
    "os_type": "<string>",
    "os_version": "<string>",
    "device_model": "<string>",
    "accept_language": "<string>",
    "referer": "<string>"
  },
  "error": {
    "code": "<string>",
    "message": "<string>",
    "reason": "<string>",
    "unified_code": "<string>",
    "unified_message": "<string>",
    "network_advice_code": "<string>",
    "network_decline_code": "<string>",
    "network_error_message": "<string>"
  },
  "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": "<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",
      "origin_zip": "08807"
    },
    "phone": {
      "number": "9123456789",
      "country_code": "+1"
    },
    "email": "<string>"
  },
  "attempts": [
    {
      "id": "<string>",
      "status": "started",
      "amount": {
        "net_amount": 123,
        "amount_to_capture": 123,
        "surcharge_amount": 123,
        "tax_on_surcharge": 123,
        "amount_capturable": 123,
        "shipping_cost": 123,
        "order_tax_amount": 123
      },
      "connector": "stripe",
      "error": {
        "code": "<string>",
        "message": "<string>",
        "reason": "<string>",
        "unified_code": "<string>",
        "unified_message": "<string>",
        "network_advice_code": "<string>",
        "network_decline_code": "<string>",
        "network_error_message": "<string>"
      },
      "authentication_type": "three_ds",
      "created_at": "2023-11-07T05:31:56Z",
      "modified_at": "2023-11-07T05:31:56Z",
      "cancellation_reason": "<string>",
      "payment_token": "187282ab-40ef-47a9-9206-5099ba31e432",
      "connector_metadata": {
        "apple_pay": {
          "session_token_data": {
            "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>"
        },
        "braintree": {
          "merchant_account_id": "<string>",
          "merchant_config_currency": "<string>"
        },
        "adyen": {
          "testing": {
            "holder_name": "<string>"
          }
        }
      },
      "payment_experience": "redirect_to_url",
      "payment_method_type": "card",
      "connector_reference_id": "993672945374576J",
      "payment_method_subtype": "ach",
      "connector_payment_id": "<string>",
      "payment_method_id": "12345_pm_01926c58bc6e77c09e809964e72af8c8",
      "client_source": "<string>",
      "client_version": "<string>",
      "feature_metadata": {
        "revenue_recovery": {
          "attempt_triggered_by": "internal",
          "charge_id": "ch_123abc456def789ghi012klmn"
        }
      },
      "payment_method_data": "<any>"
    }
  ],
  "connector_token_details": {
    "token": "pm_9UhMqBMEOooRIvJFFdeW",
    "connector_token_request_reference_id": "<string>"
  },
  "payment_method_id": "<string>",
  "next_action": {
    "redirect_to_url": "<string>",
    "type": "redirect_to_url"
  },
  "return_url": "<string>",
  "authentication_type": "three_ds",
  "authentication_type_applied": "three_ds",
  "is_iframe_redirection_enabled": true,
  "merchant_reference_id": "pay_mbabizu24mvu3mela5njyhpit4",
  "raw_connector_response": "<string>",
  "feature_metadata": {
    "redirect_response": {
      "param": "<string>",
      "json_payload": {}
    },
    "search_tags": [
      "<string>"
    ],
    "apple_pay_recurring_details": {
      "payment_description": "<string>",
      "regular_billing": {
        "label": "<string>",
        "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": 123
      },
      "billing_agreement": "<string>",
      "management_url": "https://hyperswitch.io"
    },
    "revenue_recovery": {
      "total_retry_count": "1",
      "payment_connector_transmission": "ConnectorCallUnsuccessful",
      "billing_connector_id": "mca_1234567890",
      "active_attempt_payment_connector_id": "mca_1234567890",
      "billing_connector_payment_details": {
        "payment_processor_token": "<string>",
        "connector_customer_id": "<string>"
      },
      "payment_method_type": "card",
      "payment_method_subtype": "ach",
      "connector": "authipay",
      "billing_connector_payment_method_details": {
        "type": "card",
        "value": {
          "card_network": "Visa",
          "card_issuer": "JP MORGAN CHASE"
        }
      },
      "invoice_next_billing_time": "2023-11-07T05:31:56Z",
      "invoice_billing_started_at_time": "2023-11-07T05:31:56Z",
      "first_payment_attempt_pg_error_code": "card_declined",
      "first_payment_attempt_network_decline_code": "05",
      "first_payment_attempt_network_advice_code": "02"
    }
  },
  "metadata": {}
}

Authorizations

​
api-key
string
header
required

Publishable keys are a type of keys that can be public and have limited scope of usage.

Headers

​
X-Profile-Id
string
required

Profile ID associated to the payment intent

Path Parameters

​
id
string
required

The unique identifier for the Payment Intent

Body

application/json

Request for Payment Intent Confirm

​
payment_method_data
object
required

The payment method information provided for making a payment

  • Card
  • CardRedirect
  • Wallet
  • PayLater
  • BankRedirect
  • BankDebit
  • BankTransfer
  • RealTimePayment
  • Crypto
  • Upi
  • Voucher
  • GiftCard
  • CardToken
  • OpenBanking
  • MobilePayment
​
payment_method_type
enum<string>
required

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

Available options:
card,
card_redirect,
pay_later,
wallet,
bank_redirect,
bank_transfer,
crypto,
bank_debit,
reward,
real_time_payment,
upi,
voucher,
gift_card,
open_banking,
mobile_payment
​
payment_method_subtype
enum<string>
required

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,
amazon_pay,
paysera,
apple_pay,
atome,
bacs,
bancontact_card,
becs,
benefit,
bizum,
blik,
bluecode,
boleto,
bca_bank_transfer,
bni_va,
breadpay,
bri_va,
bhn_card_network,
card_redirect,
cimb_va,
classic,
credit,
crypto_currency,
cashapp,
dana,
danamon_va,
debit,
duit_now,
efecty,
eft,
eps,
flexiti,
fps,
evoucher,
giropay,
givex,
google_pay,
go_pay,
gcash,
ideal,
interac,
indomaret,
klarna,
kakao_pay,
local_bank_redirect,
mandiri_va,
knet,
mb_way,
mobile_pay,
momo,
momo_atm,
multibanco,
online_banking_thailand,
online_banking_czech_republic,
online_banking_finland,
online_banking_fpx,
online_banking_poland,
online_banking_slovakia,
oxxo,
pago_efectivo,
permata_bank_transfer,
open_banking_uk,
pay_bright,
paypal,
paze,
pix,
pay_safe_card,
przelewy24,
prompt_pay,
pse,
red_compra,
red_pagos,
samsung_pay,
sepa,
sepa_bank_transfer,
sepa_guarenteed_debit,
skrill,
sofort,
swish,
touch_n_go,
trustly,
twint,
upi_collect,
upi_intent,
upi_qr,
vipps,
viet_qr,
venmo,
walley,
we_chat_pay,
seven_eleven,
lawson,
mini_stop,
family_mart,
seicomart,
pay_easy,
local_bank_transfer,
mifinity,
open_banking_pis,
direct_carrier_billing,
instant_bank_transfer,
instant_bank_transfer_finland,
instant_bank_transfer_poland,
revolut_pay,
indonesian_bank_transfer
​
return_url
string | null

The URL to which you want the user to be redirected after the completion of the payment operation If this url is not passed, the url configured in the business profile will be used

Example:

"https://hyperswitch.io"

​
split_payment_method_data
object[] | null

The payment instrument data to be used for the payment in case of split payments

​
shipping
object
​
customer_acceptance
object

This "CustomerAcceptance" object is passed during Payments-Confirm request, it enlists the type, time, and mode of acceptance properties related to an acceptance done by the customer. The customer_acceptance sub object is usually passed by the SDK or client.

​
browser_info
object

Browser information to be used for 3DS 2.0

​
payment_method_id
string | null

The payment_method_id to be associated with the payment

​
payment_token
string | null
Example:

"187282ab-40ef-47a9-9206-5099ba31e432"

​
merchant_connector_details
object

Merchant connector details

​
return_raw_connector_response
boolean | null

If true, returns stringified connector raw response body

​
webhook_url
string | null

The webhook endpoint URL to receive payment status notifications

Example:

"https://merchant.example.com/webhooks/payment"

Response

Payment created

Response for Payment Intent Confirm Few fields should be expandable, we need not return these in the normal response But when explicitly requested for expanded objects, these can be returned For example shipping, billing, customer, payment_method

​
id
string
required

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

Required string length: 32 - 64
Example:

"12345_pay_01926c58bc6e77c09e809964e72af8c8"

​
status
enum<string>
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).

Available options:
succeeded,
failed,
cancelled,
cancelled_post_capture,
processing,
requires_customer_action,
requires_merchant_action,
requires_payment_method,
requires_confirmation,
requires_capture,
partially_captured,
partially_captured_and_capturable,
partially_authorized_and_requires_capture,
conflicted,
expired
​
amount
object
required
​
customer_id
string
required

The identifier for the customer

Required string length: 32 - 64
Example:

"12345_cus_01926c58bc6e77c09e809964e72af8c8"

​
created
string<date-time>
required

Time when the payment was created

Example:

"2022-09-10T10:11:12Z"

​
modified_at
string<date-time>
required

Time when the payment was last modified

Example:

"2022-09-10T10:11:12Z"

​
connector
string | null

The connector used for the payment

Example:

"stripe"

​
payment_method_data
object
  • Option 1
  • Option 2
  • Option 3
  • Option 4
  • Option 5
  • Option 6
  • Option 7
  • Option 8
  • Option 9
  • Option 10
  • Option 11
  • Option 12
  • Option 13
  • Option 14
  • Option 15
  • Option 16
  • Option 17
​
payment_method_type
enum<string>

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

Available options:
card,
card_redirect,
pay_later,
wallet,
bank_redirect,
bank_transfer,
crypto,
bank_debit,
reward,
real_time_payment,
upi,
voucher,
gift_card,
open_banking,
mobile_payment
​
payment_method_subtype
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,
amazon_pay,
paysera,
apple_pay,
atome,
bacs,
bancontact_card,
becs,
benefit,
bizum,
blik,
bluecode,
boleto,
bca_bank_transfer,
bni_va,
breadpay,
bri_va,
bhn_card_network,
card_redirect,
cimb_va,
classic,
credit,
crypto_currency,
cashapp,
dana,
danamon_va,
debit,
duit_now,
efecty,
eft,
eps,
flexiti,
fps,
evoucher,
giropay,
givex,
google_pay,
go_pay,
gcash,
ideal,
interac,
indomaret,
klarna,
kakao_pay,
local_bank_redirect,
mandiri_va,
knet,
mb_way,
mobile_pay,
momo,
momo_atm,
multibanco,
online_banking_thailand,
online_banking_czech_republic,
online_banking_finland,
online_banking_fpx,
online_banking_poland,
online_banking_slovakia,
oxxo,
pago_efectivo,
permata_bank_transfer,
open_banking_uk,
pay_bright,
paypal,
paze,
pix,
pay_safe_card,
przelewy24,
prompt_pay,
pse,
red_compra,
red_pagos,
samsung_pay,
sepa,
sepa_bank_transfer,
sepa_guarenteed_debit,
skrill,
sofort,
swish,
touch_n_go,
trustly,
twint,
upi_collect,
upi_intent,
upi_qr,
vipps,
viet_qr,
venmo,
walley,
we_chat_pay,
seven_eleven,
lawson,
mini_stop,
family_mart,
seicomart,
pay_easy,
local_bank_transfer,
mifinity,
open_banking_pis,
direct_carrier_billing,
instant_bank_transfer,
instant_bank_transfer_finland,
instant_bank_transfer_poland,
revolut_pay,
indonesian_bank_transfer
​
connector_transaction_id
string | null

A unique identifier for a payment provided by the connector

Example:

"993672945374576J"

​
connector_reference_id
string | null

reference(Identifier) to the payment at connector side

Example:

"993672945374576J"

​
merchant_connector_id
string | null

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

​
browser_info
object

Browser information to be used for 3DS 2.0

​
error
object

Error details for the payment

​
shipping
object
​
billing
object
​
attempts
object[] | null

List of payment attempts associated with payment intent

​
connector_token_details
object

Token information that can be used to initiate transactions by the merchant.

​
payment_method_id
string | null

The payment_method_id associated with the payment

​
next_action
object

Contains the url for redirection flow

  • Option 1
  • Option 2
  • Option 3
  • Option 4
  • Option 5
  • Option 6
  • Option 7
  • Option 8
  • Option 9
  • Option 10
  • Option 11
  • Option 12
​
return_url
string | null

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

​
authentication_type
enum<string>
default:no_three_ds

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

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

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

Available options:
three_ds,
no_three_ds
​
authentication_type_applied
enum<string>
default:no_three_ds

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

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

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

Available options:
three_ds,
no_three_ds
​
is_iframe_redirection_enabled
boolean | null

Indicates if the redirection has to open in the iframe

​
merchant_reference_id
string | null

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

Required string length: 30
Example:

"pay_mbabizu24mvu3mela5njyhpit4"

​
raw_connector_response
string | null

Stringified connector raw response body. Only returned if return_raw_connector_response is true

​
feature_metadata
object

additional data that might be required by hyperswitch

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

⌘I