Hyperswitch

API Reference

Locker API Reference

Error Codes

Rate Limits

Go-live Checklist

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

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 a payment_id if payment_id is not provided

Refunds - List

Disputes - Retrieve Dispute

Disputes - List Disputes

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

Creates a new *business profile* for a merchant

Business Profile - Create

Business Profile - Update

Business Profile - Retrieve

Business Profile - Delete

Lists all the *business profiles* under a merchant

Business Profile - List

Retrieve information about the specified API Key.

API Key - Retrieve

Update information for the specified API Key.

API Key - Update

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

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

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

Organization

Merchant Account

Business Profile

API Key

Merchant Connector Account

Payouts

Event

GSM (Global Status Mapping)

Poll

Blocklist

Routing

Schemas

Routing retrieve