Payments - List
GET /payments/list
Description: Retrieve a list of payments.
cURL
curl --request GET \
--url https://sandbox.hyperswitch.io/payments/list \
--header 'api-key: <api-key>'Example Response (200)
[
{
"size": 1,
"data": [
{
"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>"
}
}
]
}
]Authorization
Header: 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. Do not expose this key on a website or embed it in a mobile application.
Query Parameters
customer_id — string | null The identifier for the customer
starting_after — string | null A cursor for use in pagination, fetch the next list after some object
ending_before — string | null A cursor for use in pagination, fetch the previous list before some object
limit — integer | null Limit on the number of objects to return
created — string | null The time at which payment is created
created_lt — string | null Time less than the payment created time
created_gt — string | null Time greater than the payment created time
created_lte — string | null Time less than or equals to the payment created time
created_gte — string | null Time greater than or equals to the payment created time
Response
200 application/json — Successfully retrieved a payment list
Response fields:
size (integer, required) — The number of payments included in the list (Required range: x >= 0)
data (object[], required) — Array of payment objects (see example response for detailed attributes)
Links
API reference: https://api-reference.hyperswitch.io/introduction
Locker API Reference: https://api-reference.hyperswitch.io/locker-api-reference/overview
Intelligent Router API Reference: https://api-reference.hyperswitch.io/intelligent-router-api-reference/overview
Suggest edits: https://github.com/juspay/hyperswitch/edit/main/api-reference/v1/payments/payments--list.mdx Raise issue: https://github.com/juspay/hyperswitch/issues/new?title=Issue%20on%20docs&body=Path:%20/v1/payments/payments--list
Related:
Payments Link - Retrieve: https://api-reference.hyperswitch.io/v1/payments/payments-link--retrieve
Payments - External 3DS Authentication: https://api-reference.hyperswitch.io/v1/payments/payments--external-3ds-authentication