Payments - Get Intent

cURL

cURL
curl --request GET \
  --url https://sandbox.hyperswitch.io/v2/payments/{id}/get-intent \
  --header 'api-key: <api-key>'

Response (200 application/json)

Response example (truncated)
{
  "id": "<string>",
  "status": "succeeded",
  "amount_details": {
    "order_amount": 6540,
    "currency": "AED",
    "external_tax_calculation": "skip",
    "surcharge_calculation": "skip",
    "shipping_cost": 123,
    "order_tax_amount": 123,
    "surcharge_amount": 123,
    "tax_on_surcharge": 123,
    "amount_captured": 123
  },
  "client_secret": "cs_0195b34da95d75239c6a4bf514458896",
  "profile_id": "<string>",
  "capture_method": "automatic",
  "customer_id": "12345_cus_01926c58bc6e77c09e809964e72af8c8",
  "customer_present": "present",
  "setup_future_usage": "off_session",
  "apply_mit_exemption": "Apply",
  "payment_link_enabled": "Enable",
  "request_incremental_authorization": "true",
  "split_txns_enabled": "skip",
  "expires_on": "2023-11-07T05:31:56Z",
  "request_external_three_ds_authentication": "Enable",
  "payment_type": "normal",
  "merchant_reference_id": "pay_mbabizu24mvu3mela5njyhpit4",
  "routing_algorithm_id": "<string>",
  "authentication_type": "three_ds",
  "billing": { ... },
  "shipping": { ... },
  "description": "It's my first payment request",
  "return_url": "https://hyperswitch.io",
  "statement_descriptor": "Hyperswitch Router",
  "order_details": "[{ ... }]",
  "allowed_payment_method_types": ["ach"],
  "metadata": {},
  "connector_metadata": { ... },
  "feature_metadata": { ... },
  "payment_link_config": { ... },
  "frm_metadata": {},
  "enable_partial_authorization": false
}

Endpoint

GET /v2/payments/{id}/get-intent

Authorization

api-key (header, required) 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.

Path Parameters

  • id (string, required) The unique identifier for the Payment Intent

Response Schema (200 — Payment Intent)

Below are the main response fields and descriptions.

  • id (string, required) Global Payment Id for the payment

  • status (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.

    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, partially_captured_and_processing, conflicted, expired

  • amount_details (object, required) Contains monetary breakdowns (order_amount, currency, shipping_cost, order_tax_amount, surcharge_amount, amount_captured, etc.)

  • client_secret (string, required) Token used for client-side verification. Example: "cs_0195b34da95d75239c6a4bf514458896"

  • profile_id (string, required) Identifier for the profile. This is inferred from the x-profile-id header.

  • capture_method (enum, required) Specifies how the payment is captured:

    • automatic: Funds are captured immediately after successful authorization (default).

    • manual: Funds are authorized but not captured — use /payments/{payment_id}/capture to capture.

    • manual_multiple, scheduled, sequential_automatic are also available.

  • customer_id (string, required) Identifier for the customer. Required length: 32 - 64. Example: "12345_cus_01926c58bc6e77c09e809964e72af8c8"

  • customer_present (enum, required) Indicates whether customer is present during checkout. Options: present, absent

  • setup_future_usage (enum, required) How the payment method can be used for future payments:

    • off_session: can be used when customer is not present

    • on_session: intended for use only when customer is present (default if omitted)

  • apply_mit_exemption (enum, required) Options: Apply, Skip

  • payment_link_enabled (enum, required) Whether a payment link is enabled: Enable, Skip

  • request_incremental_authorization (enum, required) Options: true, false, default

  • split_txns_enabled (enum, required, default: skip) Options: enable, skip

  • expires_on (string, required) Expiration timestamp for client secret.

  • request_external_three_ds_authentication (enum, required) Whether 3DS authentication is requested: Enable, Skip

  • payment_type (enum, required) Type of payment: normal, new_mandate, setup_mandate, recurring_mandate

  • merchant_reference_id (string | null) Unique identifier for the payment to ensure idempotency. Required length: 30. Example: "pay_mbabizu24mvu3mela5njyhpit4"

  • routing_algorithm_id (string | null) Routing algorithm id to be used for the payment

  • authentication_type (enum) Type of cardholder authentication:

    • three_ds: request 3D Secure authentication

    • no_three_ds: do not perform 3DS Note: connectors or merchant config may override behavior.

  • billing (object) Billing address, phone, email (see example response for structure)

  • shipping (object) Shipping address, phone, email (see example response for structure)

  • description (string | null) A description for the payment. Example: "It's my first payment request"

  • return_url (string | null) URL to redirect the user after payment completion. Example: "https://hyperswitch.io"

  • statement_descriptor (string | null) Description on customer statements (non-card charges). Must contain at least one letter, max 22 chars. Example: "Hyperswitch Router"

  • order_details (object[] | null) Details about products included in the payment. Sum of amounts should equal overall payment amount. Example: "[{ \"product_name\": \"Apple iPhone 16\", \"quantity\": 1, \"amount\": 69000, \"product_img_link\": \"https://dummy-img-link.com\" }]"

  • allowed_payment_method_types (enum[] | null) Restrict Payment Method Types to show for this PaymentIntent. Examples include ach, card, apple_pay, google_pay, paypal, upi_intent, etc. (full list in original docs)

  • metadata (object) Unstructured key-value pairs for storing additional information

  • connector_metadata (object) Connector-specific additional information (e.g., Apple Pay session token data, Airwallex payload, Noon order category, Braintree merchant accounts, Adyen testing holder name, etc.)

  • feature_metadata (object) Additional data required by HyperSwitch (redirect_response, search_tags, apple_pay_recurring_details, revenue_recovery, etc.)

  • payment_link_config (object) Configuration for payment links (theme, logo, seller_name, sdk_layout, display options, transaction_details, background_image, payment button text/colours, UI rules, etc.)

  • frm_metadata (object) Additional data related to Fraud Risk Management connectors

  • enable_partial_authorization (boolean | null, default: false) Allow partial authorization for this payment

Was this page helpful?

  • Suggest edits: https://github.com/juspay/hyperswitch/edit/main/api-reference/v2/payments/payments--get-intent.mdx

  • Raise issue: https://github.com/juspay/hyperswitch/issues/new?title=Issue%20on%20docs&body=Path:%20/v2/payments/payments--get-intent

Related:

  • Payments - Create Intent: https://api-reference.hyperswitch.io/v2/payments/payments--create-intent

  • Payments - Update Intent: https://api-reference.hyperswitch.io/v2/payments/payments--update-intent

PreviousOrganization - RetrieveNextPayments - Create