Payments - Retrieve

Retrieves a payment by its ID.

Example — cURL

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

Example response (200)

{
  "payment_id": "pay_mbabizu24mvu3mela5njyhpit4",
  "merchant_id": "merchant_1668273825",
  "status": "requires_confirmation",
  "amount": 6540,
  "net_amount": 6540,
  "amount_capturable": 6540,
  "processor_merchant_id": "merchant_1689512302",
  "currency": "AED",
  "payment_method": "card",
  "attempt_count": 123,
  "shipping_cost": 6540,
  "amount_received": 6540,
  "initiator": "platform",
  "connector": "stripe",
  "client_secret": "pay_U42c409qyHwOkWo3vK60_secret_el9ksDkiB8hi6j9N78yo",
  "created": "2022-09-10T10:11:12Z",
  "modified_at": "2022-09-10T10:11:12Z",
  "customer_id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
  "customer": {
    "id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
    "name": "John Doe",
    "email": "[email protected]",
    "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",
      "connector": "stripe",
      "reason": "<string>",
      "metadata": {},
      "error_message": "<string>",
      "error_code": "<string>",
      "unified_code": "<string>",
      "unified_message": "<string>",
      "created_at": "2023-11-07T05:31:56Z",
      "updated_at": "2023-11-07T05:31:56Z",
      "profile_id": "<string>",
      "merchant_connector_id": "<string>",
      "split_refunds": {
        "stripe_split_refund": {
          "revert_platform_fee": true,
          "revert_transfer": true
        }
      },
      "issuer_error_code": "<string>",
      "issuer_error_message": "<string>",
      "raw_connector_response": "<string>"
    }
  ],
  "disputes": [
    {
      "dispute_id": "<string>",
      "dispute_stage": "pre_dispute",
      "dispute_status": "dispute_opened",
      "connector_status": "<string>",
      "connector_dispute_id": "<string>",
      "created_at": "2023-11-07T05:31:56Z",
      "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"
    }
  ],
  "attempts": [
    {
      "attempt_id": "<string>",
      "status": "started",
      "amount": 6540,
      "created_at": "2022-09-10T10:11:12Z",
      "modified_at": "2022-09-10T10:11:12Z",
      "order_tax_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": "<unknown>",
      "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,
      "connector": "<string>",
      "authorized_attempt_id": "<string>",
      "capture_sequence": 123,
      "currency": "AED",
      "connector_capture_id": "<string>",
      "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_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": "<unknown>",
      "authentication_data": "<unknown>"
    },
    "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_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": "<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>"
  },
  "order_details": "[{\n        \"product_name\": \"gillete creme\",\n        \"quantity\": 15,\n        \"amount\" : 900\n    }]",
  "email": "[email protected]",
  "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"
  ],
  "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": "<unknown>",
    "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>"
    },
    "braintree": {
      "merchant_account_id": "<string>",
      "merchant_config_currency": "<string>"
    },
    "adyen": {
      "testing": {
        "holder_name": "<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
      },
      "management_url": "https://hyperswitch.io",
      "billing_agreement": "<string>"
    }
  },
  "reference_id": "993672945374576J",
  "payment_link": {
    "link": "<string>",
    "payment_link_id": "<string>",
    "secure_link": "<string>"
  },
  "profile_id": "<string>",
  "surcharge_details": {
    "surcharge_amount": 6540,
    "tax_amount": 123
  },
  "merchant_decision": "<string>",
  "merchant_connector_id": "<string>",
  "incremental_authorization_allowed": true,
  "authorization_count": 123,
  "incremental_authorizations": [
    {
      "authorization_id": "<string>",
      "amount": 6540,
      "status": "success",
      "previously_authorized_amount": 123,
      "error_code": "<string>",
      "error_message": "<string>"
    }
  ],
  "external_authentication_details": {
    "status": "started",
    "authentication_flow": "challenge",
    "electronic_commerce_indicator": "<string>",
    "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>",
    "os_type": "<string>",
    "os_version": "<string>",
    "device_model": "<string>",
    "accept_language": "<string>",
    "referer": "<string>"
  },
  "payment_channel": "ecommerce",
  "payment_method_id": "<string>",
  "network_transaction_id": "<string>",
  "payment_method_status": "active",
  "updated": "2022-09-10T10:11:12Z",
  "split_payments": {
    "stripe_split_payment": {
      "charge_type": {
        "Stripe": "direct"
      },
      "application_fees": 6540,
      "transfer_account_id": "<string>",
      "charge_id": "<string>"
    }
  },
  "frm_metadata": {},
  "extended_authorization_applied": true,
  "extended_authorization_last_applied_at": "2022-09-10T10:11:12Z",
  "request_extended_authorization": false,
  "capture_before": "2023-11-07T05:31:56Z",
  "merchant_order_reference_id": "Custom_Order_id_123",
  "order_tax_amount": 123,
  "connector_mandate_id": "<string>",
  "card_discovery": "manual",
  "force_3ds_challenge": true,
  "force_3ds_challenge_trigger": true,
  "issuer_error_code": "<string>",
  "issuer_error_message": "<string>",
  "is_iframe_redirection_enabled": true,
  "whole_connector_response": "<string>",
  "enable_partial_authorization": false,
  "enable_overcapture": true,
  "is_overcapture_enabled": true,
  "network_details": {
    "network_advice_code": "<string>"
  },
  "is_stored_credential": true,
  "mit_category": "installment",
  "billing_descriptor": {
    "name": "The Online Retailer",
    "city": "San Francisco",
    "phone": "9123456789",
    "statement_descriptor": "<string>",
    "statement_descriptor_suffix": "<string>",
    "reference": "<string>"
  },
  "tokenization": "skip_psp",
  "partner_merchant_identifier_details": {
    "partner_details": {
      "name": "<string>",
      "version": "1.0.0",
      "integrator": "<string>"
    },
    "merchant_details": {
      "name": "<string>",
      "version": "<string>"
    }
  },
  "payment_method_tokenization_details": {
    "payment_method_id": "<string>",
    "psp_tokenization": true,
    "network_tokenization": true,
    "is_eligible_for_mit_payment": true,
    "payment_method_status": "active",
    "network_transaction_id": "<string>"
  }
}

Endpoint

GET /payments/{payment_id}

Authorizations (Headers)

api-key (string, 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

payment_id (string, required) — The identifier for payment.

Query Parameters

force_sync (boolean | null) — Decider to enable or disable the connector call for retrieve request.
client_secret (string | null) — 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.

Response (200 — application/json)

Gets the payment with final status. Key response fields:

payment_id (string, required) — Unique identifier for the payment. Required string length: 30.
merchant_id (string, required) — Identifier for the merchant account inferred from API key.
status (enum, required) — Overall status of the payment intent. Default: requires_confirmation. 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 (integer, required) — Payment amount in minor units (e.g., cents).
net_amount (integer, required) — net_amount = amount + surcharge_details.surcharge_amount + surcharge_details.tax_amount + shipping_cost + order_tax_amount.
amount_capturable (integer, required) — Amount still capturable (relevant when capture_method is manual).
processor_merchant_id (string, required) — Identifier for the processor merchant account.
currency (enum, required) — Three-letter ISO 4217 currency code (e.g., USD, EUR). (Many currency codes supported.)
payment_method (enum, required) — Type of payment method (card, wallet, pay_later, etc.).
attempt_count (integer, required) — Total number of attempts associated with this payment.
shipping_cost (integer | null) — Shipping cost for the payment.
amount_received (integer | null) — Total amount captured for this payment.
initiator (enum) — platform or connected.
connector (string | null) — Name of the payment connector (e.g., "stripe").
client_secret (string | null) — Secret token for client-side flows (expires).
created, modified_at, updated, expires_on (string | null) — Timestamps in ISO 8601.
customer (object) — Details: id, name, email, phone, phone_country_code.
description (string | null) — Payment description.
refunds, disputes, attempts, captures (arrays) — Lists of associated objects (see example response).
mandate_id, mandate_data — Mandate-related fields for recurring payments.
setup_future_usage (enum) — off_session or on_session.
off_session (boolean | null)
capture_on (string | null)
capture_method (enum) — automatic, manual, manual_multiple, scheduled, sequential_automatic.
payment_method_data (object) — Details per payment method (card, billing, etc.).
payment_token (string | null) — Reference to stored payment method.
shipping, billing (objects) — Address/phone/email details.
order_details (array | null) — Product/quantity/amount info for connectors (e.g., Klarna).
return_url (string | null)
authentication_type (enum) — three_ds or no_three_ds. Default: three_ds.
statement_descriptor_name, statement_descriptor_suffix (string | null)
next_action (object) — Contains redirection info for next steps (e.g., redirect_to_url).
error_code, error_message (string | null) — Connector-specific and human-readable error.
unified_code, unified_message (string | null) — Unified error code/message across connectors.
payment_experience, payment_method_type, connector_label, business_country, business_label, business_sub_label
allowed_payment_method_types (array | null) — Allowed sub types for this PaymentIntent.
manual_retry_allowed (boolean | null)
connector_transaction_id (string | null)
frm_message, metadata, connector_metadata, feature_metadata (objects)
reference_id, payment_link, profile_id, surcharge_details
merchant_decision, merchant_connector_id
incremental_authorization_allowed, authorization_count, incremental_authorizations
external_authentication_details, external_3ds_authentication_attempted
fingerprint, browser_info (object) — Used for 3DS 2.0.
payment_channel (string) — e.g., ecommerce.
payment_method_id, network_transaction_id, payment_method_status
split_payments, frm_metadata
extended_authorization_applied, extended_authorization_last_applied_at, request_extended_authorization, capture_before
merchant_order_reference_id, order_tax_amount, connector_mandate_id
card_discovery, force_3ds_challenge, force_3ds_challenge_trigger
issuer_error_code, issuer_error_message
is_iframe_redirection_enabled, whole_connector_response
enable_partial_authorization, enable_overcapture, is_overcapture_enabled
network_details
is_stored_credential, mit_category
billing_descriptor
tokenization
partner_merchant_identifier_details
payment_method_tokenization_details

(Refer to the example response above for detailed structure and sample values.)

Was this page helpful?

Suggest edits: https://github.com/juspay/hyperswitch/edit/main/api-reference/v1/payments/payments--retrieve.mdx Raise issue: https://github.com/juspay/hyperswitch/issues/new?title=Issue%20on%20docs&body=Path:%20/v1/payments/payments--retrieve

Good afternoon