canonical: https://jentic.com/apis/hyperswitch.io/hyperswitch

# Hyperswitch API

Jentic publishes the only available OpenAPI specification for Hyperswitch API, keeping it validated and agent-ready. Hyperswitch is an open-source payments orchestration platform from Juspay; the API exposes 132 endpoints covering payment intents, confirmations, captures, refunds, customers, payment methods, payment links, mandates, disputes, 3DS authentication, payouts, and merchant configuration. Sandbox traffic uses https://sandbox.hyperswitch.io while production runs at https://api.hyperswitch.io. Authentication is performed with api-key, publishable key, ephemeral key, or admin api-key headers, plus JWT bearer tokens for dashboard-style flows.

## For AI agents

Process payments, issue refunds, manage customers and payment methods, and handle disputes through the Hyperswitch open-source payments orchestrator.

## Scope

Does not handle accounting, tax filing, or KYC document verification - use for payment processing, refunds, payment links, mandates, and disputes only.

## Capabilities

- Create a payment intent and confirm it against a chosen connector or payment method
- Capture, cancel, or extend authorization on an existing payment by id
- Issue full or partial refunds against a captured payment
- Generate payment links and session tokens for hosted checkout flows
- Authorise and complete 3D Secure authentication on a payment intent
- Manage customers, saved payment methods, mandates, and payouts
- List and respond to disputes raised against a Hyperswitch payment

## Use cases

### Multi-Connector Payment Routing

Use Hyperswitch as a payments orchestrator that routes a single PaymentIntent to the best processor (Stripe, Adyen, Braintree, and so on) based on rules, success rates, or cost. The /payments and `/payments/{payment_id}/confirm` endpoints expose the full intent lifecycle with connector overrides, so a merchant can avoid hardcoding to one PSP and switch routing on the fly.

Example prompt: POST /payments with amount=4999, currency=USD, and confirm=true, then read the connector field on the response.

### Refund and Dispute Operations

Build refund and dispute tooling for support agents on top of `/payments/{payment_id}/cancel`, the refunds endpoint, and the disputes resource. Agents can issue partial refunds, attach evidence, and read dispute status without touching multiple PSP dashboards. This consolidates back-office work behind a single Hyperswitch surface.

Example prompt: POST a refund for payment_id pi_123 with amount=2500 and reason='customer_request'.

### Hosted Checkout Links

Generate hosted payment links for invoices, donations, or one-off sales via the `/payment_link/{payment_link_id}` resource and session-token endpoints. This avoids building a card form: the merchant emails the link and Hyperswitch handles 3DS and connector selection. Suited to teams that want a Stripe-Checkout-like flow without committing to a single PSP.

Example prompt: Create a payment with payment_link enabled for $99 USD and email the returned link to the customer.

### AI Agent Payment Tool

Give a sales or support AI agent a scoped 'process_payment' tool that calls Hyperswitch via Jentic. The agent searches for 'process a credit card payment', loads the input schema, and executes the POST /payments call - the api-key never enters the agent context. Useful for in-chat upsell or refund flows where prompt injection risk is real.

Example prompt: Search Jentic for 'process a credit card payment', load the Hyperswitch POST /payments schema, and execute with amount=4999.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/payments` | Create a payment intent |
| POST | `/payments/{payment_id}/confirm` | Confirm an existing payment intent |
| POST | `/payments/{payment_id}/capture` | Capture an authorised payment |
| POST | `/payments/{payment_id}/cancel` | Cancel an authorised payment |
| GET | `/payments/list` | List payments with filters |
| POST | `/payments/session_tokens` | Create a session token for hosted checkout |
| POST | `/payments/{payment_id}/3ds/authentication` | Initiate 3DS authentication for a payment |

## Key resources

- **Payments** — Create, confirm, capture, cancel, and list payment intents
- **Refunds** — Issue full or partial refunds against payments
- **Customers** — Create and manage customer records and saved payment methods
- **Payment Methods** — List, save, and detach payment methods for a customer
- **Payment Links** — Generate hosted payment links and session tokens
- **Mandates** — Set up and manage recurring payment mandates
- **Disputes** — List and respond to disputes raised against payments
- **Payouts** — Manage payouts to merchants or end users

## Why Jentic

- **Setup:** Wiring the Hyperswitch API by hand means juggling several key types in the api-key header plus a JWT bearer, targeting the sandbox host before your live host, and sequencing payment confirm and capture calls yourself. Through Jentic you install once, import the Hyperswitch API from the API Directory, store the keys once, and your agent calls it.
- **Permission scoping:** This API puts the payment id in the URL path (`/payments/{payment_id}/confirm`, `/payments/{payment_id}/capture`), so a rule can pin your agent to one payment: it can confirm and capture that payment and nothing else. You choose the operations it may call, so cancelling a payment is not included unless you add it.
- **Credential handling:** Your Hyperswitch keys and JWT bearer are stored once, encrypted, by your own Jentic One instance and injected at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'process a card payment' or 'capture an authorised payment', and Jentic returns the matching Hyperswitch operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Stripe API** — Stripe is a closed-source payments PSP with overlapping payment intent, refund, and customer APIs
- **Adyen Checkout API** — Adyen Checkout is an enterprise PSP with a single-acquirer payment API
- **Braintree API** — Braintree is a PayPal-owned PSP that Hyperswitch can route to as a connector

## FAQ

### Why is there no official OpenAPI spec for Hyperswitch API?

Hyperswitch publishes documentation but not a single canonical OpenAPI file in the Jentic API Directory today. Jentic generates and maintains this spec so AI agents and developers can call Hyperswitch via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the Hyperswitch API use?

Hyperswitch uses an api-key header for server-side calls, a publishable key for client-side calls, ephemeral keys for short-lived flows, an admin api-key for management calls, and JWT bearer tokens for dashboard-style flows. Through Jentic each key is stored in the credential vault and injected at execution time.

### Can I issue a refund through the Hyperswitch API?

Yes. Hyperswitch exposes a refunds resource and you can also cancel an authorised payment via `/payments/{payment_id}/cancel` before capture. Both flows return the updated payment state so a downstream support tool can confirm the outcome.

### What are the rate limits for the Hyperswitch API?

The OpenAPI spec does not declare numeric rate limits. Sandbox traffic on https://sandbox.hyperswitch.io is generally permissive while production limits are tied to the merchant configuration - check the Hyperswitch dashboard for your account's quota before scaling agent traffic.

### How do I create a payment intent through Jentic?

Search Jentic for 'process a credit card payment', load the schema for POST /payments, and execute with amount, currency, and customer fields. Install with pip install jentic and use the async search, load, and execute pattern.

### Does Hyperswitch support 3D Secure?

Yes. `/payments/{payment_id}/3ds/authentication` initiates a 3DS challenge and `/payments/{payment_id}/complete_authorize` completes the flow once the customer authenticates. The endpoints return updated payment state including the 3DS authentication result.

### Can I limit what my agent is allowed to do with the Hyperswitch API?

Yes. Because you run Jentic One yourself, your own rules decide which Hyperswitch operations and keys the agent may use. Since Hyperswitch puts the payment id in the URL path, such as `/payments/{payment_id}/confirm` and `/payments/{payment_id}/capture`, you can pin the agent to one payment so it confirms and captures that payment and nothing else. You pick the operations it may call, so cancelling a payment or issuing a refund is excluded unless you add it.