Payments - Get
Retrieve a payment by its global payment id.
Example (cURL)
curl --request GET \
--url https://sandbox.hyperswitch.io/v2/payments/{id} \
--header 'api-key: <api-key>'Successful response (200)
{
"id": "12345_pay_01926c58bc6e77c09e809964e72af8c8",
"status": "succeeded",
"amount": {
"currency": "AED",
"external_tax_calculation": "skip",
"surcharge_calculation": "skip",
"net_amount": 123,
"amount_capturable": 123,
"order_amount": 6540,
"shipping_cost": 123,
"order_tax_amount": 123,
"surcharge_amount": 123,
"tax_on_surcharge": 123,
"amount_to_capture": 123,
"amount_captured": 123
},
"customer_id": "12345_cus_01926c58bc6e77c09e809964e72af8c8",
"processor_merchant_id": "merchant_1689512302",
"created": "2022-09-10T10:11:12Z",
"modified_at": "2022-09-10T10:11:12Z",
"initiator": "platform",
"connector": "stripe",
"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_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": "card_declined",
"message": "The card was declined.",
"reason": "The card was declined.",
"unified_code": "card_declined",
"unified_message": "The card was declined.",
"network_advice_code": "01",
"network_decline_code": "05",
"network_error_message": "Do not retry"
},
"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_capturable": 123,
"amount_to_capture": 123,
"surcharge_amount": 123,
"tax_on_surcharge": 123,
"shipping_cost": 123,
"order_tax_amount": 123,
"amount_captured": 123
},
"authentication_type": "three_ds",
"created_at": "2023-11-07T05:31:56Z",
"modified_at": "2023-11-07T05:31:56Z",
"connector_payment_id": "<string>",
"connector": "stripe",
"error": {
"code": "card_declined",
"message": "The card was declined.",
"reason": "The card was declined.",
"unified_code": "card_declined",
"unified_message": "The card was declined.",
"network_advice_code": "01",
"network_decline_code": "05",
"network_error_message": "Do not retry"
},
"cancellation_reason": "<string>",
"payment_token": "187282ab-40ef-47a9-9206-5099ba31e432",
"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>"
}
}
},
"payment_experience": "redirect_to_url",
"payment_method_type": "card",
"connector_reference_id": "993672945374576J",
"payment_method_subtype": "ach",
"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": {
"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>"
}
}
}
],
"connector_token_details": {
"token": "pm_9UhMqBMEOooRIvJFFdeW",
"connector_token_request_reference_id": "<string>"
},
"payment_method_id": "<string>",
"next_action": {
"redirect_to_url": "https://example.com/redirect",
"type": "redirect_to_url"
},
"return_url": "<string>",
"authentication_type": "no_three_ds",
"authentication_type_applied": "no_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
},
"management_url": "https://hyperswitch.io",
"billing_agreement": "<string>"
},
"revenue_recovery": {
"total_retry_count": "1",
"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"
}
},
"payment_connector_transmission": "ConnectorCallUnsuccessful",
"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": {}
}Endpoint
GET /v2/payments/{id}
Authorizations
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 global payment id
Query parameters
force_sync (enum, required) — A boolean to indicate whether to force sync the payment status. Value can be
trueorfalse.
Response
200 application/json — Gets the payment with final status.
Note: Few fields can be returned as expanded objects when explicitly requested. By default these may not be returned; to obtain them request explicit expansion. Examples of expandable fields: shipping, billing, customer, payment_method.
Important response fields
id (string, required) — Unique identifier for the payment. Required string length: 32 - 64. Example: "12345_pay_01926c58bc6e77c09e809964e72af8c8"
status (enum, required) — Overall status of a payment intent. Available options include:
succeeded,failed,cancelled,processing,requires_customer_action,requires_capture,partially_captured,expired, etc.amount (object, required) — Amount details (see response example).
customer_id (string, required) — Identifier for the customer. Required string length: 32 - 64.
processor_merchant_id (string, required) — Identifier for the processor merchant account. Example: "merchant_1689512302"
created (string, required) — Time when the payment was created.
modified_at (string, required) — Time when the payment was last modified.
initiator (enum) —
platformorconnected.connector (string | null) — The connector used for the payment (e.g., "stripe").
payment_method_data (object) — Payment method details (card, billing, etc.).
payment_method_type (enum) — e.g.,
card,wallet,bank_transfer,upi, etc.payment_method_subtype (enum) — e.g.,
ach,apple_pay,google_pay, etc.connector_transaction_id (string | null) — Connector-provided payment id.
connector_reference_id (string | null) — Reference identifier at connector side.
merchant_connector_id (string | null) — Identifier of the connector account used.
browser_info (object) — Browser information to be used for 3DS 2.0.
error (object) — Error details for the payment (if any).
attempts (object[] | null) — List of payment attempts associated with the payment intent.
connector_token_details (object) — Token info usable by the merchant.
payment_method_id (string | null) — Associated payment_method id.
next_action (object) — Contains the url for redirection flow (if applicable).
return_url (string | null) — URL to which user must be redirected after completion.
authentication_type (enum) —
three_dsorno_three_ds.authentication_type_applied (enum) — Actual applied authentication type.
is_iframe_redirection_enabled (boolean | null) — Indicates if redirection should open in an iframe.
merchant_reference_id (string | null) — Merchant-provided unique identifier for idempotency.
raw_connector_response (string | null) — Stringified raw connector response body. Only returned if
return_raw_connector_responseis true.feature_metadata (object) — Additional data (see response example).
metadata (object) — Up to 50 user-defined key/value pairs.
Expandable fields
Notes
Response for Payment Intent Confirm: few fields are expandable and are returned only when explicitly requested for expanded objects (for example: shipping, billing, customer, payment_method).
For full connector raw response include the
return_raw_connector_responseflag in your request (returnsraw_connector_responsefield).