Payments - List

GET /v2/payments/list

Description: Retrieve a list of payments.

Example — cURL

cURL
curl --request GET \
  --url https://sandbox.hyperswitch.io/v2/payments/list \
  --header 'api-key: <api-key>'

Example response (200)

application/json
{
  "count": 1,
  "total_count": 123,
  "data": [
    {
      "id": "12345_pay_01926c58bc6e77c09e809964e72af8c8",
      "merchant_id": "merchant_1668273825",
      "profile_id": "<string>",
      "status": "requires_confirmation",
      "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
      },
      "created": "2022-09-10T10:11:12Z",
      "attempt_count": 123,
      "return_url": "https://hyperswitch.io",
      "is_split_payment": true,
      "customer_id": "12345_cus_01926c58bc6e77c09e809964e72af8c8",
      "payment_method_id": "<string>",
      "payment_method_type": "card",
      "payment_method_subtype": "ach",
      "connector": "authipay",
      "merchant_connector_id": "<string>",
      "customer": {
        "name": "John Doe",
        "email": "[email protected]",
        "phone": "9123456789",
        "phone_country_code": "+1"
      },
      "merchant_reference_id": "<string>",
      "connector_payment_id": "993672945374576J",
      "connector_response_reference_id": "<string>",
      "metadata": {},
      "description": "It's my first payment request",
      "authentication_type": "three_ds",
      "capture_method": "automatic",
      "setup_future_usage": "off_session",
      "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>",
      "order_details": "[{\n        \"product_name\": \"gillete creme\",\n        \"quantity\": 15,\n        \"amount\" : 900\n    }]",
      "statement_descriptor": "Hyperswitch Router",
      "allowed_payment_method_types": [
        "ach"
      ],
      "authorization_count": 123,
      "modified_at": "2022-09-10T10:11:12Z"
    }
  ]
}

Authorization (header)

  • Name: api-key (string) — 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.

Query / Path Parameters

  • payment_id (string | null) — required The identifier for payment

  • profile_id (string | null) — required The identifier for business profile

  • customer_id (string | null) — required The identifier for customer Required string length: 1 - 64

  • starting_after (string | null) — required A cursor for pagination: fetch the next list after some object

  • ending_before (string | null) — required A cursor for pagination: fetch the previous list before some object

  • limit (integer) — required — default: 10 Limit on the number of objects to return Required range: 0 <= x <= 100

  • offset (integer | null) — required The starting point within a list of objects Required range: x >= 0

  • created (string | null) — required The time at which payment is created

  • created.lt (string | null) — required Time less than the payment created time

  • created.gt (string | null) — required Time greater than the payment created time

  • created.lte (string | null) — required Time less than or equals to the payment created time

  • created.gte (string | null) — required Time greater than or equals to the payment created time

  • start_amount (integer | null) — required Start amount to filter transactions >= this amount

  • end_amount (integer | null) — required End amount to filter transactions <= this amount

  • connector (enum[] | null) — required The connector to filter payments list See full list (expandable) below.

  • currency (enum[] | null) — required The currency to filter payments list. The three-letter ISO 4217 currency code (e.g., "USD", "EUR"). Required when creating a payment. See full list (expandable) below.

  • status (enum[] | null) — required The payment status to filter payments list. Represents overall payment status. 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

  • payment_method_type (enum[] | null) — required The payment method type to filter payments list. Available: 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

  • payment_method_subtype (enum[] | null) — required The payment method subtype to filter payments list. See full list (expandable) below.

  • authentication_type (enum[] | null) — required The authentication type to filter payments list.

    • three_ds — Requests 3D Secure (3DS) authentication. If the card is enrolled, 3DS will be activated.

    • no_three_ds — Indicates that 3DS should not be performed. Note: actual behavior may be influenced by merchant configuration and connector defaults. Available options: three_ds, no_three_ds

  • merchant_connector_id (string[] | null) — required Merchant connector id to filter payments list

  • order_on (enum) — required Field to sort on. Available options: amount, created

  • order_by (enum) — required Order direction. Available options: asc, desc

  • card_network (enum[] | null) — required Card networks to filter payments list. Available: Visa, Mastercard, AmericanExpress, JCB, DinersClub, Discover, CartesBancaires, UnionPay, Interac, RuPay, Maestro, Star, Pulse, Accel, Nyce

  • merchant_order_reference_id (string | null) — required Identifier for merchant order reference id

Expandable reference data

Connectors (click to expand)

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, datatrans, deutschebank, digitalvirgo, dlocal, dwolla, ebanx, elavon, facilitapay, finix, fiserv, fiservemea, fiuu, flexiti, forte, getnet, gigadat, globalpay, globepay, gocardless, gpayments, hipay, helcim, hyperswitch_vault, inespay, iatapay, 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, payu, peachpayments, payjustnow, payjustnowinstore, phonepe, placetopay, powertranz, prophetpay, rapyd, razorpay, recurly, redsys, santander, shift4, silverflow, square, stax, stripe, stripebilling, taxjar, threedsecureio, tesouro, tokenex, tokenio, trustpay, trustpayments, tsys, vgs, volt, wells fargo, wise, worldline, worldpay, worldpayvantiv, worldpayxml, worldpaymodular, signifyd, plaid, riskified, xendit, zen, zift, zsl

Currencies (click to expand)

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

Payment method subtypes (click to expand)

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, 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, pay_safe_card, przelewy24, prompt_pay, pse, 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

Response

  • 200 application/json — Successfully retrieved a payment list

Response fields:

  • count (integer) — number of payments included in current response (x >= 0)

  • total_count (integer) — total number of available payments for given constraints

  • data (object[]) — list of payment response objects

Related links

  • Documentation: 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

  • Edit docs: https://github.com/juspay/hyperswitch/edit/main/api-reference/v2/payments/payments--list.mdx

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

If you want, I can convert any of the long option lists into tabbed or column layouts, or extract the payment object schema into a separate reference block.

PreviousPayments - Submit Eligibility DataNextPayments - Cancel