Hyperswitch

API Reference

Locker API Reference

api key

Error Codes

Rate Limits

Go-live Checklist

Payments - Create

**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

Payments - Update

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

Payments - Confirm

**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

Payments - Retrieve

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

Payments - Cancel

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

Payments - Capture

To capture the funds for an uncaptured payment

Payments - Capture

Payments - Incremental Authorization

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

Payments - Incremental Authorization

Payments - Session token

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

Payments Link - Retrieve

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

Payments - External 3DS Authentication

External 3DS Authentication is performed and returns the AuthenticationResponse

Payments - External 3DS Authentication

Payments - Complete Authorize

PaymentMethods - Create

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

Payment Method - Retrieve

Retrieves a payment method of a customer.

Payment Method - Retrieve

Payment Method - Update

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

Deletes a payment method of a customer.

Payment Method - Delete

Payment Method - Set Default Payment Method for Customer

Set the Payment Method as Default for the Customer.

Payment Method - Set Default Payment Method for Customer

List payment methods for a Merchant

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

List customer saved payment methods for a Payment

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

List customer saved payment methods for a Payment

List payment methods for a Customer

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

List payment methods for a Customer

Customers - Create

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

Retrieves a customer's details.

Customers - Retrieve

Customers - Update

Updates the customer's details in a customer object.

Customers - Update

Customers - Delete

Delete a customer record.

Customers - Delete

Customers - List

Lists all the customers for a particular merchant id.

Customers - List

Mandates - Revoke Mandate

Revokes a mandate created using the Payments/Create API

Mandates - Revoke Mandate

Mandates - Retrieve Mandate

Retrieves a mandate created using the Payments/Create API

Mandates - Retrieve Mandate

Mandates - Customer Mandates List

Lists all the mandates for a particular customer id.

Mandates - Customer Mandates List

Refunds - Create

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

Refunds - Update

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

Refunds - Update

Refunds - Retrieve

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

Refunds - Retrieve

Refunds - List

Lists all the refunds associated with the merchant or a payment_id if payment_id is not provided

Refunds - List

Disputes - Retrieve Dispute
Retrieves a dispute

Disputes - Retrieve Dispute

Disputes - List Disputes
Lists all the Disputes for a merchant

Disputes - List Disputes

Merchant Account - Create

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

Retrieve a *merchant* account details.

Merchant Account - Retrieve

Merchant Account - Update

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

Delete a *merchant* account

Merchant Account - Delete

Merchant Account - KV Status

Toggle KV mode for the Merchant Account

Merchant Account - KV Status

Business Profile - Create

Creates a new *business profile* for a merchant

Business Profile - Create

Business Profile - Update

Update the *business profile*

Business Profile - Update

Business Profile - Retrieve

Retrieve existing *business profile*

Business Profile - Retrieve

Business Profile - Delete

Delete the *business profile*

Business Profile - Delete

Business Profile - List

Lists all the *business profiles* under a merchant

Business Profile - List

API Key - Create

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

API Key - Retrieve

Retrieve information about the specified API Key.

API Key - Retrieve

API Key - Update

Update information for the specified API Key.

API Key - Update

API Key - Revoke

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

API Key - Revoke

Merchant Connector - Create

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

Retrieves details of a Connector account

Merchant Connector - Retrieve

Merchant Connector - Update

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

Merchant Connector - Update

Merchant Connector - Delete

Delete or Detach a Merchant Connector from Merchant Account

Merchant Connector - Delete

Merchant Connector - List

List Merchant Connector Details for the merchant

Merchant Connector - List

Payouts - Create

Payouts - Retrieve

Payouts - Update

Payouts - Cancel

Payouts - Fulfill

Payouts - List

Payouts - Filter

Events - List

List all Events associated with a Merchant Account or Business Profile.

Events - List

Events - Delivery Attempt List

List all delivery attempts for the specified Event.

Events - Delivery Attempt List

Events - Manual Retry

Manually retry the delivery of the specified Event.

Events - Manual Retry

Gsm - Create

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

Payments

Payment Methods

Customers

Mandates

Refunds

Disputes

Merchant Account

Business Profile

API Key

Merchant Connector Account

Payouts

Event

GSM (Global Status Mapping)

Poll

Blocklist

Routing

Schemas

Post blocklisttoggle

Authorizations

Query Parameters

Response