1.5 Practical: Running Your First Payment via Hyperswitch (API)
Initiate a payment via API
To initiate a payment via API, you’ll first need a tool to send HTTP requests.
Download and install Postman, a popular API client used for testing and exploring APIs. Once installed, import the Hyperswitch Academy Postman Collection (linked below), which contains pre-configured requests for common payment flows, including payment creation with auto-confirm which we will be using in this exercise.
This collection helps you get started quickly without having to manually construct requests or remember endpoint details, allowing you to focus on understanding how payments move through Hyperswitch. Make sure to cross check the parameters and values before sending in a payment request. Also, refer to the API reference documentation for any addtional assistance.
Below mentioned are the step-by-step instructions organized in tab groups. Navigate through them in order to successfully initiate a payment via API.
Import the postman collection:
Once the collection is imported successfully, you should see a structured set of folders and requests for Hyperswitch APIs in Postman similar to what is shown in the screenshot indicating that the import is successful and ready to use.
Navigate to API Keys in the Control Center:
From the Control Center sidebar, go to: Developers → API Keys
This section allows you to create and manage API keys used to authenticate server-to-server requests made to Hyperswitch APIs.
Create a New API Key:
Click Create New API Key. In the modal:
Enter a Name (for example: Academy)
Add a Description (optional)
Set Expiration to Never for local testing
Click Create to generate the key.
Copy and Store the API Key:
Once the key is created, you’ll see a Download the API Key.
Copy the API key shown and store it securely.
This value will not be visible again and is required for authenticating API requests.
Verify API Key Creation:
After closing the modal, you’ll see the newly created API key listed under API Keys, along with:
Key prefix
Name and description
Creation timestamp
Expiration status
This confirms that the API key is active and ready to use.
Open the HS Academy Collection in Postman:
Switch to Postman and select the HS Academy collection from the left sidebar.
Navigate to the Variables tab of the collection.
This is where common values used across all API requests are configured.
Set Base URL and Profile ID:
Ensure the following variables are set correctly:
baseUrl → http://localhost:8080
profile_id → Copy the Profile ID from the Control Center (shown when hovering over the profile selector)
These values tell Postman which Hyperswitch instance and merchant profile to target.
Set API and Publishable Keys:
Update the following variables in Postman:
api_key → Paste the API key you generated earlier
publishable_key → Copy this from the API Keys page in Control Center
These keys authenticate and authorize the API requests.
Open “Payments – Create” Request on Postman:
In the Postman collection, navigate to: Instant Payment (auto capture) → Payments – Create
This request creates and auto-confirms a payment in a single step
Step 10: Review the Payment Create Request Payload:
Before sending the request, take a moment to review the JSON payload used to create and auto-confirm the payment. This payload defines what is being charged, who is being charged, and how the payment should be processed.
Core payment details
amount and currency specify the transaction value. The amount is expressed in the smallest currency unit (for USD, cents).
confirm: true instructs Hyperswitch to immediately attempt confirmation after creating the payment.
capture_method: "automatic" ensures the payment is captured automatically upon successful authorization.
profile_id links the payment to the selected merchant profile in Hyperswitch.
Customer and context information
customer_id, email, name, and phone identify the customer associated with the payment.
description provides a human-readable note for internal tracking and dashboards.
authentication_type: "no_three_ds" explicitly disables 3DS for this flow.
Billing and shipping information
The billing and shipping objects capture address details used for compliance, risk evaluation, and downstream processor requirements.These fields become especially important for fraud checks and region-specific regulations.
Statement descriptors
statement_descriptor_name and statement_descriptor_suffix control how the transaction appears on the customer’s bank statement.
Metadata
The metadata object allows you to attach custom key-value pairs to the payment, useful for internal analytics, segmentation, or reconciliation.
Payment method details
payment_method specifies the method being used (in this case, card).
payment_method_data contains the actual card details required to process the payment.
In production, these values are typically tokenized or collected via a client-side SDK rather than sent directly.
Browser information
browser_info provides contextual information about the customer’s device and environment.
This data is commonly used for fraud detection and risk assessment, especially in browser-based payment flows.
Before proceeding, review these fields and ensure they align with your test scenario. Once validated, you can send the request to create and process the payment via the Hyperswitch API.
Step 11: Send the Request and Review the Payment Response
Once the request payload is reviewed, click Send in Postman to create and auto-confirm the payment.
If the request is successful, you will receive a 200 OK response along with a JSON body describing the newly created payment. This response represents the system’s view of the payment after it has been processed by Hyperswitch and the configured connector.
Below is a simplified explanation of the key parts of the response.
Core identifiers and status
payment_id is the unique identifier generated by Hyperswitch for this transaction and is used to reference the payment across APIs and the Control Center.
merchant_id identifies the merchant account under which the payment was created.
status indicates the current state of the payment. In this case, succeeded confirms that the payment was authorized and captured successfully.
Amount and settlement information
amount represents the original payment amount requested.
net_amount reflects the amount after any adjustments (such as fees, if applicable).
amount_received indicates the final amount captured for this payment.
amount_capturable being 0 confirms that no further capture is pending, since this was an automatic and full capture flow.
Connector and processing details
connector shows which payment processor handled the transaction. Here, the payment was routed to fauxpay.
capture_method confirms how the payment was captured (automatic in this case).
created records the timestamp when the payment was created.
Client and customer context
client_secret is a short-lived secret used by client-side SDKs to securely retrieve or act on the payment.
customer_id links the payment to the customer object.
The nested customer object provides the customer’s name, email, and phone details associated with the payment.
Payment method information
payment_method indicates the type of payment used (for example, card).
payment_method_data contains masked and derived card details such as the last four digits, expiry, and issuer-related information. Sensitive card data is never returned in full.
Optional and lifecycle fields
Fields such as refunds, disputes, and mandate_id are included for completeness but are null at this stage, as no post-payment actions have occurred yet.
This is only a subset of the full response structure. Hyperswitch returns a rich, extensible payment object designed to support advanced use cases such as refunds, disputes, mandates, and asynchronous workflows. For now, we focus on the essentials to keep the initial learning experience simple.
With this, we have successfully created and confirmed a payment using the Hyperswitch SDK, Hyperswitch API and inspected its response at a high level. While we focused only on the most essential fields to keep the flow approachable, the API exposes a much richer set of attributes and capabilities. If you’d like to explore the full request and response schema immediately, you can refer to the official API reference documentation at https://docs.hyperswitch.io/api-reference
In the next section, we’ll shift focus from what the API returns to how the payment actually moves through Hyperswitch tracing its journey across SDK, core backend services, connectors, and supporting components to understand the system’s internal flow end to end.
Last updated