Hyperswitch API
Agent-ready OpenAPI document · curated by JenticPaymentsPayment ProcessingapiKey, bearer132 EndpointsREST
Know of an official OpenAPI document? Contribute it →
For Agents
Process payments, issue refunds, manage customers and payment methods, and handle disputes through the Hyperswitch open-source payments orchestrator.
Use for: Process a credit card payment of $50 via Hyperswitch, I want to refund the last successful payment for a customer, Capture an authorised payment by payment id, Generate a payment link for a $99 invoice
Not supported: Does not handle accounting, tax filing, or KYC document verification - use for payment processing, refunds, payment links, mandates, and disputes only.
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.
Install Jentic One Beta
Connect the Hyperswitch API to your agent
Jentic One is a self-hosted execution layer for AI agents. It lets your agent call the Hyperswitch API, or any other public or private API you need. You set the rules, the agent never sees your credentials, and every call is logged.
Two steps, two machines. Install the instance in a safe environment, then register your agent from wherever it runs.
1
Step 1: Jentic One Host machine
# On the machine that will host your Jentic One instance:
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fhyperswitch.io%2Fhyperswitch" | sh2
Step 2: Agent machine
# On the machine where your agent runs (keep this separate from the instance):
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fhyperswitch.io%2Fhyperswitch" | sh
jentic register # connects your agent to your Jentic One instanceJentic One is in public beta. The setup above keeps your agent separate from the instance, which is what you want before using real credentials: an agent running as the same OS user as Jentic One can read its stored keys directly. Just evaluating? A single local install is fine to start. See the secure deployment guide for the tiers.
Capabilities
What an agent can do with Hyperswitch API.
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
Patterns agents use Hyperswitch API for, with concrete tasks.
★ 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.
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.
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.
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.
Search Jentic for 'process a credit card payment', load the Hyperswitch POST /payments schema, and execute with amount=4999.
Key Endpoints
132 endpoints — jentic publishes the only available openapi specification for hyperswitch api, keeping it validated and agent-ready.
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
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
Why Jentic?
What agents get from Jentic-routed access to this vendor.
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 isolation
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.
Intent-based discovery
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
Alternatives and complements available in the Jentic catalogue.
Alternative
Stripe API
Stripe is a closed-source payments PSP with overlapping payment intent, refund, and customer APIs
Choose Stripe for a managed PSP with the broadest connector and feature set; choose Hyperswitch when the team wants open-source orchestration across multiple PSPs
FAQs
Specific to using Hyperswitch API through Jentic.
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.
GET STARTED