Hyperswitch

Introduction

👋 Welcome to Hyperswitch API Reference

Error Codes

Rate Limits

Go-live Checklist

Getting Started with Payments

**Creates a payment object when amount and currency are passed.**

This API is also used to create a mandate by passing the `mandate_object`.

Depending on the user journey you wish to achieve, you may opt to complete all the steps in a single request **by attaching a payment method, setting `confirm=true` and `capture_method = automatic`** in the *Payments/Create API* request.

Otherwise, To completely process a payment you will have to **create a payment, attach a payment method, confirm and capture funds**. For that you could use the following sequence of API requests -

1. Payments - Create

2. Payments - Update

3. Payments - Confirm

4. Payments - Capture.

You will require the 'API - Key' from the Hyperswitch dashboard to make the first call, and use the 'client secret' returned in this API along with your 'publishable key' to make subsequent API calls from your client.

This page lists the various combinations in which the Payments - Create API can be used and the details about the various fields in the requests and responses.

Payments - Create

To update the properties of a *PaymentIntent* object. This may include attaching a payment method, or attaching customer object or metadata fields after the Payment is created

Payments - Update

**Use this API to confirm the payment and forward the payment to the payment processor.**

Alternatively you can confirm the payment within the *Payments/Create* API by setting `confirm=true`. After confirmation, the payment could either:

1. fail with `failed` status or

2. transition to a `requires_customer_action` status with a `next_action` block or

3. succeed with either `succeeded` in case of automatic capture or `requires_capture` in case of manual capture

Payments - Confirm

Retrieves a Payment. This API can also be used to get the status of a previously initiated payment or next action for an ongoing payment

Payments - Retrieve

A Payment could can be cancelled when it is in one of these statuses: `requires_payment_method`, `requires_capture`, `requires_confirmation`, `requires_customer_action`.

Payments - Cancel

To capture the funds for an uncaptured payment

Payments - Capture

Authorized amount for a payment can be incremented if it is in status: requires_capture

Payments - Incremental Authorization

Creates 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' SDK.

Payments - Session token

To 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

Payments Link - Retrieve

Payments - List

External 3DS Authentication is performed and returns the AuthenticationResponse

Payments - External 3DS Authentication

Payments - Complete Authorize

Payments - Update Metadata

Creates and stores a payment method against a customer.
In case of cards, this API should be used only by PCI compliant merchants.

PaymentMethods - Create

Retrieves a payment method of a customer.

Payment Method - Retrieve

Update 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 in recurring payments.

Payment Method - Update

Payment Method - Delete

Set the Payment Method as Default for the Customer.

Payment Method - Set Default Payment Method for Customer

Lists the applicable payment methods for a particular Merchant ID.
Use the client secret and publishable key authorization to list all relevant payment methods of the merchant for the payment corresponding to the client secret.

List payment methods for a Merchant

Lists all the applicable payment methods for a particular payment tied to the `client_secret`.

List customer saved payment methods for a Payment

Lists all the applicable payment methods for a particular Customer ID.

List payment methods for a Customer

Creates 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 respond with the customer details.

Customers - Create

Customers - Retrieve

Updates the customer's details in a customer object.

Customers - Update

Customers - Delete

Lists all the customers for a particular merchant id.

Customers - List

Revokes a mandate created using the Payments/Create API

Mandates - Revoke Mandate

Retrieves a mandate created using the Payments/Create API

Mandates - Retrieve Mandate

Lists all the mandates for a particular customer id.

Mandates - Customer Mandates List

Creates 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 original charge amount has been refunded

Refunds - Create

Updates the properties of a Refund object. This API can be used to attach a reason for the refund or metadata fields

Refunds - Update

Retrieves a Refund. This may be used to get the status of a previously initiated refund

Refunds - Retrieve

Lists all the refunds associated with the merchant, or for a specific payment if payment_id is provided

Refunds - List

Disputes - Retrieve Dispute

Disputes - List Disputes

Payouts - Create

Payouts - Update

Payouts - Cancel

Payouts - Fulfill

Payouts - Confirm

Payouts - Retrieve

Payouts - List

Payouts - List available filters

Payouts - List using filters

List all Events associated with a Merchant Account or Profile.

Events - List

List all delivery attempts for the specified Event.

Events - Delivery Attempt List

Manually retry the delivery of the specified Event.

Events - Manual Retry

Poll - Retrieve Poll Status

Routing - List

Routing - Create

Routing - Retrieve Config

Routing - Deactivate

Routing - Retrieve Default Config

Routing - Update Default Config

Routing - Retrieve Default For Profile

Routing - Update Default For Profile

Routing - Retrieve

Routing - Activate config

Relay - Create

Relay - Retrieve

3DS Decision - Execute

Organization - Create

Organization - Retrieve

Organization - Update

Create a new account for a *merchant* and the *merchant* could be a seller or retailer or client who likes to receive and send payments.

Merchant Account - Create

Merchant Account - Retrieve

Updates details of an existing merchant account. Helpful in updating merchant details such as email, contact details, or other configuration details like webhook, routing algorithm etc

Merchant Account - Update

Merchant Account - Delete

Merchant Account - KV Status

Profile - Create

Profile - Update

Profile - Retrieve

Profile - Delete

Lists all the *profiles* under a merchant

Profile - List

Create 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.

API Key - Create

Retrieve information about the specified API Key.

API Key - Retrieve

Update information for the specified API Key.

API Key - Update

Revoke the specified API Key. Once revoked, the API Key can no longer be used for
authenticating with our APIs.

API Key - Revoke

List all the API Keys associated to a merchant account.

API Key - List

Creates a new Merchant Connector for the merchant account. The connector could be a payment processor/facilitator/acquirer or a provider of specialized services like Fraud/Accounting etc.

Merchant Connector - Create

Merchant Connector - Retrieve

To update an existing Merchant Connector account. Helpful in enabling/disabling different payment methods and other settings for the connector

Merchant Connector - Update

Delete or Detach a Merchant Connector from Merchant Account

Merchant Connector - Delete

List Merchant Connector Details for the merchant

Merchant Connector - List

Creates 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 flow/sub-flow to Hyperswitch's unified status/error code/error message combination. It is also used to decide the next action in the flow - retry/requeue/do_default

Gsm - Create

Gsm - Get

Gsm - Update

Gsm - Delete

Get Health

Provide the first key to unlock the locker

Provide Key 1

Provide the second key to unlock the locker

Provide Key 2

Unlock the locker with the key1 and key2 provided

Unlock the locker

Add Data in Locker

Delete Data from Locker

Retrieve Data from Locker

Get or insert the card fingerprint

Calculates success rate for an entity based on provided parameters and labels

Fetch success rate for an entity

Updates the success rate calculation window with new data points

Update success rate window

Invalidates the success rate calculation windows for a specific ID

Invalidate windows

Calculates success rates for both entity-specific and global metrics

Fetch entity and global success rates

Determines which processors should be eliminated from routing consideration based on historical performance data.

Fetch eliminated processor list

Updates the failure records for specific processors, affecting future elimination decisions.

Update elimination bucket

Invalidates all elimination bucket data for a specific entity, effectively resetting its processor elimination history.

Invalidate elimination bucket

Calculates contract scores for an entity based on provided parameters and labels

Get Started [BETA]

Essentials [BETA]

Payments Core APIs [BETA]

Account management APIs [BETA]

Other APIs [BETA]

Payment method session update a saved payment method