> ## Documentation Index > Fetch the complete documentation index at: https://api-reference.hyperswitch.io/llms.txt > Use this file to discover all available pages before exploring further. # Payments - List > To list the *payments* ## OpenAPI ````yaml get /v2/payments/list openapi: 3.0.3 info: title: Hyperswitch - API Documentation description: > ## Get started Hyperswitch provides a collection of APIs that enable you to process and manage payments. Our APIs accept and return JSON in the HTTP body, and return standard HTTP response codes. You can consume the APIs directly using your favorite HTTP/REST library. We have a testing environment referred to "sandbox", which you can setup to test API calls without affecting production data. Currently, our sandbox environment is live while our production environment is under development and will be available soon. You can sign up on our Dashboard to get API keys to access Hyperswitch API. ### Environment Use the following base URLs when making requests to the APIs: | Environment | Base URL | |---------------|------------------------------------| | Sandbox | | | Production | | ## Authentication When you sign up on our [dashboard](https://app.hyperswitch.io) and create a merchant account, you are given a secret key (also referred as api-key) and a publishable key. You may authenticate all API requests with Hyperswitch server by providing the appropriate key in the request Authorization header. | Key | Description | |-----------------|-----------------------------------------------------------------------------------------------| | api-key | Private key. Used to authenticate all API requests from your merchant server | | publishable key | Unique identifier for your account. Used to authenticate API requests from your app's client | Never share your secret api keys. Keep them guarded and secure. contact: name: Hyperswitch Support url: https://hyperswitch.io email: support.global@juspay.io license: name: Apache-2.0 version: 0.1.0 servers: - url: https://sandbox.hyperswitch.io description: Sandbox Environment security: [] tags: - name: Merchant Account description: Create and manage merchant accounts - name: Profile description: Create and manage profiles - name: Merchant Connector Account description: Create and manage merchant connector accounts - name: Payments description: Create and manage one-time payments, recurring payments and mandates - name: Refunds description: Create and manage refunds for successful payments - name: Mandates description: Manage mandates - name: Customers description: Create and manage customers - name: Payment Methods description: Create and manage payment methods of customers - name: Disputes description: Manage disputes - name: API Key description: Create and manage API Keys - name: Payouts description: Create and manage payouts - name: payment link description: Create payment link - name: Routing description: Create and manage routing configurations - name: Event description: Manage events paths: /v2/payments/list: get: tags: - Payments summary: Payments - List description: To list the *payments* operationId: List all Payments parameters: - name: payment_id in: path description: The identifier for payment required: true schema: type: string nullable: true example: pay_fafa124123 - name: profile_id in: path description: The identifier for business profile required: true schema: type: string nullable: true example: pay_fafa124123 - name: customer_id in: path description: The identifier for customer required: true schema: type: string nullable: true maxLength: 64 minLength: 1 example: cus_y3oqhf46pyzuxjbcn2giaqnb44 - name: starting_after in: path description: >- A cursor for use in pagination, fetch the next list after some object required: true schema: type: string nullable: true example: pay_fafa124123 - name: ending_before in: path description: >- A cursor for use in pagination, fetch the previous list before some object required: true schema: type: string nullable: true example: pay_fafa124123 - name: limit in: path description: limit on the number of objects to return required: true schema: type: integer format: int32 default: 10 maximum: 100 minimum: 0 - name: offset in: path description: The starting point within a list of objects required: true schema: type: integer format: int32 nullable: true minimum: 0 - name: created in: path description: The time at which payment is created required: true schema: type: string format: date-time nullable: true example: '2022-09-10T10:11:12Z' - name: created.lt in: path description: Time less than the payment created time required: true schema: type: string format: date-time nullable: true example: '2022-09-10T10:11:12Z' - name: created.gt in: path description: Time greater than the payment created time required: true schema: type: string format: date-time nullable: true example: '2022-09-10T10:11:12Z' - name: created.lte in: path description: Time less than or equals to the payment created time required: true schema: type: string format: date-time nullable: true example: '2022-09-10T10:11:12Z' - name: created.gte in: path description: Time greater than or equals to the payment created time required: true schema: type: string format: date-time nullable: true example: '2022-09-10T10:11:12Z' - name: start_amount in: path description: >- The start amount to filter list of transactions which are greater than or equal to the start amount required: true schema: type: integer format: int64 nullable: true - name: end_amount in: path description: >- The end amount to filter list of transactions which are less than or equal to the end amount required: true schema: type: integer format: int64 nullable: true - name: connector in: path description: The connector to filter payments list required: true schema: type: array items: $ref: '#/components/schemas/Connector' nullable: true - name: currency in: path description: The currency to filter payments list required: true schema: type: array items: $ref: '#/components/schemas/Currency' nullable: true - name: status in: path description: The payment status to filter payments list required: true schema: type: array items: $ref: '#/components/schemas/IntentStatus' nullable: true - name: payment_method_type in: path description: The payment method type to filter payments list required: true schema: type: array items: $ref: '#/components/schemas/PaymentMethod' nullable: true - name: payment_method_subtype in: path description: The payment method subtype to filter payments list required: true schema: type: array items: $ref: '#/components/schemas/PaymentMethodType' nullable: true - name: authentication_type in: path description: The authentication type to filter payments list required: true schema: type: array items: $ref: '#/components/schemas/AuthenticationType' nullable: true - name: merchant_connector_id in: path description: The merchant connector id to filter payments list required: true schema: type: array items: type: string nullable: true - name: order_on in: path description: The field on which the payments list should be sorted required: true schema: $ref: '#/components/schemas/SortOn' - name: order_by in: path description: The order in which payments list should be sorted required: true schema: $ref: '#/components/schemas/SortBy' - name: card_network in: path description: The card networks to filter payments list required: true schema: type: array items: $ref: '#/components/schemas/CardNetwork' nullable: true - name: merchant_order_reference_id in: path description: The identifier for merchant order reference id required: true schema: type: string nullable: true responses: '200': description: Successfully retrieved a payment list content: application/json: schema: $ref: '#/components/schemas/PaymentListResponse' '404': description: No payments found security: - api_key: [] - jwt_key: [] components: schemas: Connector: type: string enum: - absa_sanlam - authipay - adyenplatform - stripe_billing_test - phonypay - fauxpay - pretendpay - stripe_test - adyen_test - checkout_test - paypal_test - aci - adyen - affirm - airwallex - amazonpay - archipel - authorizedotnet - bambora - bamboraapac - bankofamerica - barclaycard - billwerk - bitpay - bluesnap - blackhawknetwork - calida - boku - braintree - breadpay - cardinal - cashtocode - celero - chargebee - checkbook - checkout - coinbase - coingate - custombilling - cryptopay - ctp_mastercard - ctp_visa - cybersource - cybersourcedecisionmanager - datatrans - deutschebank - digitalvirgo - dlocal - dwolla - ebanx - envoy - elavon - facilitapay - finix - fiserv - fiservemea - fiservcommercehub - fiuu - flexiti - forte - getnet - gigadat - globalpay - globepay - gocardless - gpayments - hipay - helcim - hyperpg - hyperswitch_vault - interpayments - inespay - iatapay - imerchantsolutions - itaubank - jpmorgan - juspaythreedsserver - klarna - loonio - mifinity - mollie - moneris - multisafepay - netcetera - nexinets - nexixpay - nmi - nomupay - noon - nordea - novalnet - nuvei - opennode - paybox - payload - payme - payone - paypal - paysafe - paystack - paytm - payconex - payu - peachpayments - payjustnow - payjustnowinstore - phonepe - placetopay - powertranz - prophetpay - rapyd - razorpay - recurly - redsys - revolv3 - santander - shift4 - silverflow - square - stax - stripe - stripebilling - taxjar - threedsecureio - tesouro - tokenex - tokenio - trustly - truelayer - trustpay - trustpayments - tsys - tsys_transit - vgs - volt - wellsfargo - wise - worldline - worldpay - worldpayvantiv - worldpayxml - worldpaymodular - signifyd - plaid - riskified - xendit - zen - zift - zsl Currency: type: string description: >- The three-letter ISO 4217 currency code (e.g., "USD", "EUR") for the payment amount. This field is mandatory for creating a payment. enum: - AED - AFN - ALL - AMD - ANG - AOA - ARS - AUD - AWG - AZN - BAM - BBD - BDT - BGN - BHD - BIF - BMD - BND - BOB - BRL - BSD - BTN - BWP - BYN - BZD - CAD - CDF - CHF - CLF - CLP - CNY - COP - CRC - CUC - CUP - CVE - CZK - DJF - DKK - DOP - DZD - EGP - ERN - ETB - EUR - FJD - FKP - GBP - GEL - GHS - GIP - GMD - GNF - GTQ - GYD - HKD - HNL - HRK - HTG - HUF - IDR - ILS - INR - IQD - IRR - ISK - JMD - JOD - JPY - KES - KGS - KHR - KMF - KPW - KRW - KWD - KYD - KZT - LAK - LBP - LKR - LRD - LSL - LYD - MAD - MDL - MGA - MKD - MMK - MNT - MOP - MRU - MUR - MVR - MWK - MXN - MYR - MZN - NAD - NGN - NIO - NOK - NPR - NZD - OMR - PAB - PEN - PGK - PHP - PKR - PLN - PYG - QAR - RON - RSD - RUB - RWF - SAR - SBD - SCR - SDG - SEK - SGD - SHP - SLE - SLL - SOS - SRD - SSP - STD - STN - SVC - SYP - SZL - THB - TJS - TMT - TND - TOP - TRY - TTD - TWD - TZS - UAH - UGX - USD - UYU - UZS - VES - VND - VUV - WST - XAF - XCD - XOF - XPF - YER - ZAR - ZMW - ZWL IntentStatus: type: string description: >- 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). enum: - 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 - review PaymentMethod: type: string description: 'Indicates the type of payment method. Eg: ''card'', ''wallet'', etc.' enum: - 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 - network_token PaymentMethodType: type: string description: >- Indicates the sub type of payment method. Eg: 'google_pay' & 'apple_pay' for wallets. enum: - 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 - eft_debit_order - 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 - payjustnow - paypal - paze - pix - pix_key - pix_emv - pix_qr - pix_automatico_qr - pix_automatico_push - pay_safe_card - przelewy24 - prompt_pay - pse - qris - 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 - open_banking - network_token AuthenticationType: type: string description: >- 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. enum: - three_ds - no_three_ds SortOn: type: string enum: - amount - attempt_count - created - modified SortBy: type: string enum: - asc - desc CardNetwork: type: string description: Indicates the card network. enum: - Visa - Mastercard - AmericanExpress - JCB - DinersClub - Discover - CartesBancaires - UnionPay - Interac - RuPay - Maestro - Star - Pulse - Accel - Nyce PaymentListResponse: type: object required: - count - total_count - data properties: count: type: integer description: The number of payments included in the current response minimum: 0 total_count: type: integer format: int64 description: The total number of available payments for given constraints data: type: array items: $ref: '#/components/schemas/PaymentsListResponseItem' description: The list of payments response objects PaymentsListResponseItem: type: object required: - id - merchant_id - profile_id - status - amount - created - attempt_count - return_url - is_split_payment properties: id: type: string description: Unique identifier for the payment example: 0a_pay_01926c58bc6e77c09e809964e72af8c8 maxLength: 64 minLength: 32 merchant_id: type: string description: >- This is an identifier for the merchant account. This is inferred from the API key provided during the request example: merchant_1668273825 maxLength: 255 profile_id: type: string description: The business profile that is associated with this payment customer_id: type: string description: The identifier for the customer example: 0a_cus_01926c58bc6e77c09e809964e72af8c8 nullable: true maxLength: 64 minLength: 32 payment_method_id: type: string description: Identifier for Payment Method used for the payment nullable: true status: allOf: - $ref: '#/components/schemas/IntentStatus' default: requires_confirmation amount: $ref: '#/components/schemas/PaymentAmountDetailsResponse' created: type: string format: date-time description: Time when the payment was created example: '2022-09-10T10:11:12Z' payment_method_type: allOf: - $ref: '#/components/schemas/PaymentMethod' nullable: true payment_method_subtype: allOf: - $ref: '#/components/schemas/PaymentMethodType' nullable: true connector: allOf: - $ref: '#/components/schemas/Connector' nullable: true merchant_connector_id: type: string description: >- Identifier of the connector ( merchant connector account ) which was chosen to make the payment nullable: true customer: allOf: - $ref: '#/components/schemas/CustomerDetailsResponse' nullable: true merchant_reference_id: type: string description: >- The reference id for the order in the merchant's system. This value can be passed by the merchant. nullable: true connector_payment_id: type: string description: A unique identifier for a payment provided by the connector example: 993672945374576J nullable: true connector_response_reference_id: type: string description: Reference to the capture at connector side nullable: true metadata: type: object description: >- Metadata is useful for storing additional, unstructured information on an object. nullable: true description: type: string description: A description of the payment example: It's my first payment request nullable: true authentication_type: allOf: - $ref: '#/components/schemas/AuthenticationType' default: three_ds nullable: true capture_method: allOf: - $ref: '#/components/schemas/CaptureMethod' nullable: true setup_future_usage: allOf: - $ref: '#/components/schemas/FutureUsage' nullable: true attempt_count: type: integer format: int32 description: Total number of attempts associated with this payment error: allOf: - $ref: '#/components/schemas/ErrorDetails' nullable: true cancellation_reason: type: string description: If the payment was cancelled the reason will be provided here nullable: true order_details: type: array items: $ref: '#/components/schemas/OrderDetailsWithAmount' description: >- Information about the product , quantity and amount for connectors. (e.g. Klarna) example: |- [{ "product_name": "gillete creme", "quantity": 15, "amount" : 900 }] nullable: true return_url: type: string description: The URL to redirect after the completion of the operation example: https://hyperswitch.io statement_descriptor: type: string description: >- For non-card charges, you can use this value as the complete description that appears on your customers’ statements. Must contain at least one letter, maximum 22 characters. example: Hyperswitch Router nullable: true maxLength: 255 allowed_payment_method_types: type: array items: $ref: '#/components/schemas/PaymentMethodType' description: Allowed Payment Method Types for a given PaymentIntent nullable: true authorization_count: type: integer format: int32 description: >- Total number of authorizations happened in an incremental_authorization payment nullable: true modified_at: type: string format: date-time description: Date time at which payment was updated example: '2022-09-10T10:11:12Z' nullable: true is_split_payment: type: boolean description: >- Indicates if the payment amount is split across multiple payment methods PaymentAmountDetailsResponse: type: object required: - currency - external_tax_calculation - surcharge_calculation - net_amount - amount_capturable properties: order_amount: type: integer format: int64 description: >- The payment amount. Amount for the payment in the lowest denomination of the currency, (i.e) in cents for USD denomination, in yen for JPY denomination etc. E.g., Pass 100 to charge $1.00 and 1 for 1¥ since ¥ is a zero-decimal currency. Read more about [the Decimal and Non-Decimal Currencies](https://github.com/juspay/hyperswitch/wiki/Decimal-and-Non%E2%80%90Decimal-Currencies) example: 6540 minimum: 0 currency: $ref: '#/components/schemas/Currency' shipping_cost: allOf: - $ref: '#/components/schemas/MinorUnit' nullable: true order_tax_amount: allOf: - $ref: '#/components/schemas/MinorUnit' nullable: true external_tax_calculation: $ref: '#/components/schemas/TaxCalculationOverride' surcharge_calculation: $ref: '#/components/schemas/SurchargeCalculationOverride' surcharge_amount: allOf: - $ref: '#/components/schemas/MinorUnit' nullable: true tax_on_surcharge: allOf: - $ref: '#/components/schemas/MinorUnit' nullable: true net_amount: $ref: '#/components/schemas/MinorUnit' amount_to_capture: allOf: - $ref: '#/components/schemas/MinorUnit' nullable: true amount_capturable: $ref: '#/components/schemas/MinorUnit' amount_captured: allOf: - $ref: '#/components/schemas/MinorUnit' nullable: true CustomerDetailsResponse: type: object description: Details of customer attached to this payment properties: name: type: string description: The customer's name example: John Doe nullable: true maxLength: 255 email: type: string description: The customer's email address example: johntest@test.com nullable: true maxLength: 255 phone: type: string description: The customer's phone number example: '9123456789' nullable: true maxLength: 10 phone_country_code: type: string description: The country code for the customer's phone number example: '+1' nullable: true maxLength: 2 CaptureMethod: type: string description: >- Specifies how the payment is captured. - `automatic`: Funds are captured immediately after successful authorization. This is the default behavior if the field is omitted. - `manual`: Funds are authorized but not captured. A separate request to the `/payments/{payment_id}/capture` endpoint is required to capture the funds. enum: - automatic - manual - manual_multiple - scheduled - sequential_automatic FutureUsage: type: string description: >- Specifies how the payment method can be used for future payments. - `off_session`: The payment method can be used for future payments when the customer is not present. - `on_session`: The payment method is intended for use only when the customer is present during checkout. If omitted, defaults to `on_session`. enum: - off_session - on_session ErrorDetails: type: object description: Error details for the payment required: - code - message properties: code: type: string description: The error code example: card_declined message: type: string description: The error message example: The card was declined. reason: type: string description: The detailed error reason that was returned by the connector. example: The card was declined. nullable: true unified_code: type: string description: |- The unified error code across all connectors. This can be relied upon for taking decisions based on the error. example: card_declined nullable: true unified_message: type: string description: >- The unified error message across all connectors. If there is a translation available, this will have the translated message example: The card was declined. nullable: true network_advice_code: type: string description: >- This field can be returned for both approved and refused Mastercard payments. This code provides additional information about the type of transaction or the reason why the payment failed. If the payment failed, the network advice code gives guidance on if and when you can retry the payment. example: '01' nullable: true network_decline_code: type: string description: >- For card errors resulting from a card issuer decline, a brand specific 2, 3, or 4 digit code which indicates the reason the authorization failed. example: '05' nullable: true network_error_message: type: string description: >- A string indicating how to proceed with an network error if payment gateway provide one. This is used to understand the network error code better. example: Do not retry nullable: true OrderDetailsWithAmount: type: object required: - product_name - quantity - amount properties: product_name: type: string description: Name of the product that is being purchased example: shirt maxLength: 255 quantity: type: integer format: int32 description: The quantity of the product to be purchased example: 1 minimum: 0 amount: type: integer format: int64 description: the amount per quantity of product tax_rate: type: number format: double description: tax rate applicable to the product nullable: true total_tax_amount: type: integer format: int64 description: total tax amount applicable to the product nullable: true requires_shipping: type: boolean nullable: true product_img_link: type: string description: The image URL of the product nullable: true product_id: type: string description: ID of the product that is being purchased nullable: true category: type: string description: Category of the product that is being purchased nullable: true sub_category: type: string description: Sub category of the product that is being purchased nullable: true brand: type: string description: Brand of the product that is being purchased nullable: true product_type: allOf: - $ref: '#/components/schemas/ProductType' nullable: true product_tax_code: type: string description: The tax code for the product nullable: true description: type: string description: Description for the item nullable: true sku: type: string description: Stock Keeping Unit (SKU) or the item identifier for this item. nullable: true upc: type: string description: Universal Product Code for the item. nullable: true commodity_code: type: string description: >- Code describing a commodity or a group of commodities pertaining to goods classification. nullable: true unit_of_measure: type: string description: Unit of measure used for the item quantity. nullable: true total_amount: type: integer format: int64 description: Total amount for the item. nullable: true unit_discount_amount: type: integer format: int64 description: Discount amount applied to this item. nullable: true MinorUnit: type: integer format: int64 description: This Unit struct represents MinorUnit in which core amount works TaxCalculationOverride: type: string enum: - skip - calculate SurchargeCalculationOverride: type: string enum: - skip - calculate ProductType: type: string enum: - physical - digital - travel - ride - event - accommodation securitySchemes: api_key: type: apiKey in: header name: Authorization description: >- Format: `api-key=` 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. jwt_key: type: http scheme: bearer bearerFormat: JWT ````