Hyperswitch (Juspay)

Hyperswitch API

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…

Payments#openapi

Fork copies the collection into your workspace, without the publisher's secrets, so you can add your own key and send requests. Star saves it to your starred APIs (Account › Marketplace) and helps others find it.

Overview

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:

EnvironmentBase URL
Sandbox
Production

Authentication

When you sign up on our dashboard 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.

KeyDescription
api-keyPrivate key. Used to authenticate all API requests from your merchant server
publishable keyUnique 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.

Endpoints 153

Merchant Account

  • POSTMerchant Account - Create/accountsCreate a new account for a *merchant* and the *merchant* could be a seller or retailer or client who likes to receive and send payments.
  • GETMerchant Account - Retrieve/accounts/:account_idRetrieve a *merchant* account details.
  • POSTMerchant Account - Update/accounts/:account_idUpdates details of an existing merchant account. Helpful in updating merchant details such as email, contact details, or other configuration details like…
  • DELETEMerchant Account - Delete/accounts/:account_idDelete a *merchant* account
  • POSTMerchant Account - KV Status/accounts/:account_id/kvToggle KV mode for the Merchant Account

Profile

  • GETProfile - List/account/:account_id/business_profileLists all the *profiles* under a merchant
  • POSTProfile - Create/account/:account_id/business_profileCreates a new *profile* for a merchant
  • GETProfile - Retrieve/account/:account_id/business_profile/:profile_idRetrieve existing *profile*
  • POSTProfile - Update/account/:account_id/business_profile/:profile_idUpdate the *profile*
  • DELETEProfile - Delete/account/:account_id/business_profile/:profile_idDelete the *profile*

Merchant Connector Account

  • GETMerchant Connector - List/account/:account_id/connectorsList Merchant Connector Details for the merchant
  • POSTMerchant Connector - Create/account/:account_id/connectorsCreates a new Merchant Connector for the merchant account. The connector could be a payment processor/facilitator/acquirer or a provider of specialized…
  • GETMerchant Connector - Retrieve/account/:account_id/connectors/:merchant_connector_idRetrieves details of a Connector account
  • POSTMerchant Connector - Update/account/:account_id/connectors/:merchant_connector_idTo update an existing Merchant Connector account. Helpful in enabling/disabling different payment methods and other settings for the connector
  • DELETEMerchant Connector - Delete/account/:account_id/connectors/:merchant_connector_idDelete or Detach a Merchant Connector from Merchant Account
  • POSTConfigure Connector Webhook - Register/account/:account_id/webhooks/:merchant_connector_idSetup webhook configuration for an existing Merchant at the connector.

Payments

  • POSTPayments - Create/paymentsCreates a payment resource, which represents a customer's intent to pay. This endpoint is the starting point for various payment flows:
  • GETPayments - Retrieve/payments/:payment_idRetrieves a Payment. This API can also be used to get the status of a previously initiated payment or next action for an ongoing payment
  • POSTPayments - Update/payments/:payment_idTo update the properties of a *PaymentIntent* object. This may include attaching a payment method, or attaching customer object or metadata fields after the…
  • POSTPayments - Confirm/payments/:payment_id/confirmConfirms a payment intent that was previously created with confirm: false. This action attempts to authorize the payment with the payment processor. Expected…
  • POSTPayments - Capture/payments/:payment_id/captureCaptures the funds for a previously authorized payment intent where capture_method was set to manual and the payment is in a requires_capture state. Upon…
  • POSTPayments - Session token/payments/session_tokensCreates a session object or a session token for wallets like Apple Pay, Google Pay, etc. These tokens are used by Hyperswitch's SDK to initiate these wallets'…
  • POSTPayments - Cancel/payments/:payment_id/cancelA Payment could can be cancelled when it is in one of these statuses: requires_payment_method, requires_capture, requires_confirmation,…
  • GETPayments - Cancel Post Capture Retrieve/payments/:payment_id/cancel_post_captureRetrieves a canceled Payment post capture
  • POSTPayments - Cancel Post Capture/payments/:payment_id/cancel_post_captureA Payment could can be cancelled when it is in one of these statuses: succeeded, partially_captured, partially_captured_and_capturable.
  • POSTPayments - Extended Authorization/payments/:payment_id/extend_authorizationExtended authorization is available for payments currently in the requires_capture status Call this endpoint to increase the authorization validity period
  • GETPayments - List/payments/listTo list the *payments*
  • POSTPayments - Incremental Authorization/payments/:payment_id/incremental_authorizationAuthorized amount for a payment can be incremented if it is in status: requires_capture
  • GETPayments Link - Retrieve/payment_link/:payment_link_idTo retrieve the properties of a Payment Link. This may be used to get the status of a previously initiated payment or next action for an ongoing payment
  • POSTPayments - External 3DS Authentication/payments/:payment_id/3ds/authenticationExternal 3DS Authentication is performed and returns the AuthenticationResponse
  • POSTPayments - Complete Authorize/payments/:payment_id/complete_authorize
  • POSTPayments - Post Session Tokens/payments/:payment_id/post_session_tokens
  • POSTPayments - Update Metadata/payments/:payment_id/update_metadata
  • POSTPayments - Submit Eligibility Check Data/payments/:payment_id/eligibility_check
  • POSTPayments - Submit Eligibility Data/payments/:payment_id/eligibilityRuns eligibility checks (blocklist, card testing guard) and calculates an external surcharge in a single call. Intended to be called by the SDK before the…

Refunds

  • POSTRefunds - Create/refundsCreates a refund against an already processed payment. In case of some processors, you can even opt to refund only a partial amount multiple times until the…
  • GETRefunds - Retrieve/refunds/:refund_idRetrieves a Refund. This may be used to get the status of a previously initiated refund
  • POSTRefunds - Update/refunds/:refund_idUpdates the properties of a Refund object. This API can be used to attach a reason for the refund or metadata fields
  • POSTRefunds - List/refunds/listLists all the refunds associated with the merchant, or for a specific payment if payment_id is provided

Mandates

  • GETMandates - Retrieve Mandate/mandates/:mandate_idRetrieves a mandate created using the Payments/Create API
  • POSTMandates - Revoke Mandate/mandates/revoke/:mandate_idRevokes a mandate created using the Payments/Create API
  • GETMandates - Customer Mandates List/customers/:customer_id/mandatesLists all the mandates for a particular customer id.

Customers

  • POSTCustomers - Create/customersCreates a customer object and stores the customer details to be reused for future payments. Incase the customer already exists in the system, this API will…
  • GETCustomers - Retrieve/customers/:customer_idRetrieves a customer's details.
  • POSTCustomers - Update/customers/:customer_idUpdates the customer's details in a customer object.
  • DELETECustomers - Delete/customers/:customer_idDelete a customer record.
  • GETCustomers - Retrieve using Merchant Reference ID/v1/customers/reference/:merchant_reference_idRetrieves a customer's details using the merchant supplied reference ID.
  • GETCustomers - List/customers/listLists all the customers for a particular merchant id.

Payment Methods

  • POSTPaymentMethods - Create/payment_methodsCreates and stores a payment method against a customer. In case of cards, this API should be used only by PCI compliant merchants.
  • GETList payment methods for a Merchant/account/payment_methodsLists the applicable payment methods for a particular Merchant ID. Use the client secret and publishable key authorization to list all relevant payment…
  • GETList payment methods for a Customer/customers/:customer_id/payment_methodsLists all the applicable payment methods for a particular Customer ID.
  • GETList customer saved payment methods for a Payment/customers/payment_methodsLists all the applicable payment methods for a particular payment tied to the client_secret.
  • GETList payment methods for a Payment/payments/:payment_id/clientClient SDK endpoint. Returns a unified response combining merchant-enabled payment methods and customer saved payment methods, filtered via Euclid constraint…
  • POSTPayment Method - Set Default Payment Method for Customer/:customer_id/payment_methods/:payment_method_id/defaultSet the Payment Method as Default for the Customer.
  • GETPayment Method - Retrieve/payment_methods/:method_idRetrieves a payment method of a customer.
  • DELETEPayment Method - Delete/payment_methods/:method_idDeletes a payment method of a customer.
  • POSTPayment Method - Update/payment_methods/:method_id/updateUpdate an existing payment method of a customer. This API is useful for use cases such as updating the card number for expired cards to prevent discontinuity…

Disputes

  • GETDisputes - Retrieve Dispute/disputes/:dispute_idRetrieves a dispute
  • GETDisputes - List Disputes/disputes/listLists all the Disputes for a merchant
  • GETDisputes - List Disputes for The Given Profiles/disputes/profile/listLists all the Disputes for a merchant
  • GETDisputes - Disputes Filters/disputes/filterLists all the filters associated with disputes
  • GETDisputes - Disputes Filters Profile/disputes/profile/filterLists all the filters associated with disputes for the given profiles
  • POSTDisputes - Accept Dispute/disputes/accept/:dispute_idAccepts a dispute
  • PUTDisputes - Attach Evidence to Dispute/disputes/evidenceAttaches an uploaded evidence file to a dispute
  • POSTDisputes - Uploads Dispute Evidence/disputes/evidenceUploads evidence for a dispute
  • DELETEDisputes - Delete Evidence attached to a Dispute/disputes/evidenceDeletes an evidence file attached to a dispute
  • GETDisputes - Retrieve Dispute Evidence/disputes/evidence/:dispute_idRetrieves evidence for a dispute
  • GETDisputes - Get Disputes Aggregate/disputes/aggregate?start_time=stringGets a count of disputes grouped by their status for a merchant within a time range
  • GETDisputes - Get Disputes Aggregate for Profiles/disputes/profile/aggregate?start_time=stringGets a count of disputes grouped by their status for the given profiles within a time range

API Key

  • POSTAPI Key - Create/api_keys/:merchant_idCreate a new API Key for accessing our APIs from your servers. The plaintext API Key will be displayed only once on creation, so ensure you store it securely.
  • GETAPI Key - Retrieve/api_keys/:merchant_id/:key_idRetrieve information about the specified API Key.
  • POSTAPI Key - Update/api_keys/:merchant_id/:key_idUpdate information for the specified API Key.
  • DELETEAPI Key - Revoke/api_keys/:merchant_id/:key_idRevoke the specified API Key. Once revoked, the API Key can no longer be used for authenticating with our APIs.
  • GETAPI Key - List/api_keys/:merchant_id/listList all the API Keys associated to a merchant account.

Payouts

  • POSTPayouts - Create/payouts/create
  • GETPayouts - Retrieve/payouts/:payout_id
  • POSTPayouts - Update/payouts/:payout_id
  • POSTPayouts - Cancel/payouts/:payout_id/cancel
  • POSTPayouts - Fulfill/payouts/:payout_id/fulfill
  • GETPayouts - List/payouts/list?customer_id=string&starting_after=string&ending_before=string&limit=string&created=string&time_range=string
  • POSTPayouts - List using filters/payouts/list
  • POSTPayouts - Confirm/payouts/:payout_id/confirm
  • POSTPayouts - List available filters/payouts/filter

Routing

  • GETRouting - List/routingList all routing configs
  • POSTRouting - Create/routingCreate a routing config
  • POSTRouting - Activate config/routing/:routing_algorithm_id/activateActivate a routing config
  • GETRouting - Retrieve/routing/:routing_algorithm_idRetrieve a routing algorithm
  • POSTRouting - Deactivate/routing/deactivateDeactivates a routing config
  • GETRouting - Retrieve Default Config/routing/defaultRetrieve default fallback config
  • POSTRouting - Update Default Config/routing/defaultUpdate default fallback config
  • GETRouting - Retrieve Config/routing/activeRetrieve active config
  • GETRouting - Retrieve Default For Profile/routing/default/profileRetrieve default config for profiles
  • POSTRouting - Update Default For Profile/routing/default/profile/:profile_idUpdate default config for profiles
  • POSTRouting - Toggle success based dynamic routing for profile/account/:account_id/business_profile/:profile_id/dynamic_routing/success_based/toggle?enable=metricsCreate a success based dynamic routing algorithm
  • POSTRouting - Toggle elimination routing for profile/account/:account_id/business_profile/:profile_id/dynamic_routing/elimination/toggle?enable=metricsCreate a elimination based dynamic routing algorithm
  • POSTRouting - Auth Rate Based/account/:account_id/business_profile/:profile_id/dynamic_routing/success_based/create?enable=metricsCreate a success based dynamic routing algorithm
  • POSTRouting - Elimination/account/:account_id/business_profile/:profile_id/dynamic_routing/elimination/create?enable=metricsCreate a elimination based dynamic routing algorithm
  • POSTRouting - Toggle Contract routing for profile/account/:account_id/business_profile/:profile_id/dynamic_routing/contracts/toggle?enable=metricsCreate a Contract based dynamic routing algorithm

Event

  • POSTEvents - List/events/:merchant_idList all Events associated with a Merchant Account or Profile.
  • POSTEvents - List/events/profile/listList all Events associated with a Profile.
  • GETEvents - Delivery Attempt List/events/:merchant_id/:event_id/attemptsList all delivery attempts for the specified Event.
  • POSTEvents - Manual Retry/events/:merchant_id/:event_id/retryManually retry the delivery of the specified Event.

Authentication

  • POSTAuthentication - Create/authenticationCreate a new authentication for accessing our APIs from your servers.
  • POSTAuthentication - Eligibility/authentication/:authentication_id/eligibilityCheck if an authentication is eligible for a specific merchant.
  • POSTAuthentication - Authenticate/authentication/:authentication_id/authenticateAuthenticate an authentication for accessing our APIs from your servers.
  • POSTAuthentication - Redirect/authentication/:authentication_id/redirectRedirect an authentication for accessing our APIs from your servers.
  • POSTAuthentication - Sync/authentication/:authentication_id/syncSync an authentication for accessing our APIs from your servers.
  • POSTAuthentication - Enable Authn Methods Token/authentication/:authentication_id/enabled_authn_methods_tokenEnable authn methods token for an authentication.
  • GETAuthentication - GET Eligibility Check/authentication/:authentication_id/eligibility-check
  • POSTAuthentication - POST Eligibility Check/authentication/:authentication_id/eligibility-check

Subscriptions

  • POSTSubscription - Create and Confirm/subscriptionsCreates and confirms a subscription in a single request.
  • POSTSubscription - Create/subscriptions/createCreates a subscription that requires separate confirmation.
  • POSTSubscription - Confirm/subscriptions/:subscription_id/confirmConfirms a previously created subscription.
  • GETSubscription - Retrieve/subscriptions/:subscription_idRetrieves subscription details by ID.
  • PUTSubscription - Update/subscriptions/:subscription_id/updateUpdates an existing subscription.
  • GETSubscription - Get Items/subscriptions/items?item_type=planRetrieves available subscription items.
  • GETSubscription - Get Estimate/subscriptions/estimate?plan_id=stringGets pricing estimate for a subscription.
  • POSTSubscription - Pause Subscription/subscriptions/:subscription_id/pausePause the subscription
  • POSTSubscription - Resume Subscription/subscriptions/:subscription_id/resumeResume the subscription
  • POSTSubscription - Cancel Subscription/subscriptions/:subscription_id/cancelCancel the subscription

Card Issuer

  • GETCard Issuer - List/card_issuersLists all card issuers
  • POSTCard Issuer - Create/card_issuersCreates a new card issuer entry
  • PUTCard Issuer - Update/card_issuers/:idUpdates an existing card issuer entry
  • DELETECard Issuer - Delete/card_issuers/:idDeletes an existing card issuer entry

Telephone Order

  • POSTTelephone Order - Charge/telephone_order/:merchant_id/:providerCharges a card that an IVR provider collected over the phone. Only twilio is supported as {provider}.

Payment Links

  • POSTPayment Link - List/payment_link/listTo list the payment links across all profiles for a merchant
  • POSTPayment Link - Profile List/payment_link/profile/listTo list payment links scoped to the authenticated business profile

Relay

  • POSTRelay - Create/relayCreates a relay request.
  • GETRelay - Retrieve/relay/:relay_idRetrieves a relay details.

Organization

  • POSTOrganization - Create/organizationCreate a new organization
  • GETOrganization - Retrieve/organization/:idRetrieve an existing organization
  • PUTOrganization - Update/organization/:idCreate a new organization for .

Gsm

  • POSTGsm - Create/gsmCreates a GSM (Global Status Mapping) Rule. A GSM rule is used to map a connector's error message/error code combination during a particular payments…
  • POSTGsm - Get/gsm/getRetrieves a Gsm Rule
  • POSTGsm - Update/gsm/updateUpdates a Gsm Rule
  • POSTGsm - Delete/gsm/deleteDeletes a Gsm Rule

Offers

  • POSTOffers - Browse/offer_engine/offers/listLists the offers currently available to the merchant. Offers that are not eligible are excluded, so the response contains only offers that can be used.

Blocklist

  • GETList Blocked fingerprints of a particular kind/blocklist?data_kind=payment_method
  • POSTBlock a Fingerprint/blocklist
  • DELETEUnblock a Fingerprint/blocklist
  • POSTToggle blocklist guard for a particular merchant/blocklist/toggle?status=true
  • GETCount blocked fingerprints of a particular kind/blocklist/count?data_kind=payment_method
  • GETLook up whether a value is blocked/blocklist/lookup?data=string
  • GETList batch blocklist jobs/blocklist/batch
  • POSTUpload a batch blocklist CSV/blocklist/batch
  • GETGet batch blocklist job status/blocklist/batch/:job_id
  • POSTStart a blocklist CSV export/blocklist/export
  • POSTBlocklist - Clone Entries/blocklist/cloneCopies a business profile's blocklist entries onto other profiles of the same merchant. The copy runs as one background job whose process tracker clones onto…

Poll

  • GETPoll - Retrieve Poll Status/poll/status/:poll_id

Profile Acquirer

  • POSTProfile Acquirer - Create/profile_acquirersCreate a new Profile Acquirer for accessing our APIs from your servers.
  • POSTProfile Acquirer - Update/profile_acquirers/:profile_id/:profile_acquirer_idUpdate a Profile Acquirer for accessing our APIs from your servers.

3DS Decision Rule

  • POST3DS Decision - Execute/three_ds_decision/execute

Platform

  • POSTPlatform - Create/user/create_platformCreate a new platform account

API details

Base URL
https://sandbox.hyperswitch.io
Authentication
An API key in the Authorization header
An API key in the api-key header
HTTP Basic authentication (username and password)
A bearer token in the Authorization header
An API key in the api-key header
Operations
153 operations on 124 pathsPOST 89GET 51DELETE 9PUT 4
Main resources
Payments 19Routing 15Disputes 12Blocklist 11Subscriptions 10Payment Methods 9Payouts 9Authentication 8Customers 6Merchant Connector Account 6
Response formats
application/json text/plain
Description format
OpenAPI 3.0.3, API version 0.1.0

How to test the Hyperswitch API in Swastik Codes

  1. Open the APISelect “Fork & run in Swastik Codes” on this page. Sign in or create a free account if asked.
  2. Fork it into your workspaceChoose a workspace. You get your own copy of the Hyperswitch API collection, without the publisher's secrets.
  3. Add your credentialsThis API uses an API key in the Authorization header. Add yours in the collection's variables or an environment; the requests already reference it.
  4. Send a requestPick an endpoint, for example “Merchant Account - Create” (POST /accounts), and press Send. Check the response, add tests and run the whole collection with the runner.

Frequently asked questions

What is the Hyperswitch API?

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… It is listed under Payments and has 153 endpoints.

Who publishes the Hyperswitch API?

It is listed from Hyperswitch (Juspay)'s public API description (an OpenAPI document), not published by Hyperswitch (Juspay) on Swastik Codes. Anyone who controls hyperswitch.io can claim the profile by adding a DNS TXT record.

What is the base URL of the Hyperswitch API?

Requests go to https://sandbox.hyperswitch.io. Endpoint paths are added to this base URL.

How do I authenticate with the Hyperswitch API?

It accepts 5 methods: an API key in the Authorization header; an API key in the api-key header; HTTP Basic authentication (username and password); A bearer token in the Authorization header; an API key in the api-key header.

How many endpoints does the Hyperswitch API have?

153 operations on 124 paths (89 POST, 51 GET, 9 DELETE, 4 PUT). The largest groups are Payments, Routing, Disputes, Blocklist.

Is forking the Hyperswitch API free?

Yes. Forking copies the collection into your workspace for free. It has been starred 0 times and forked 0 times.

Suggest an API

Tell us which public API is missing. We check it, then add it here with its endpoints when it has an OpenAPI (Swagger) description.