| Reliability |
|
| Scalability |
|
| Performance |
|
| Modularity |
|
| Security & Compliance |
|
| Observability |
|
| Quality & Maintenance |
|
| Legend | Description |
| 🟩 | Feature completed |
| 🟧 | Feature in progress |
| 🟥 | Work not started |
| 💪 | Stretch target |
| 🚛 | Backlog feature from Q1 2024 |
| Legend | Description |
| 🟩 | Feature completed |
| 🟧 | Feature in progress |
| 🟥 | Work not started |
| 💪 | Stretch target |
| 🚛 | Backlog feature from Q4 2023 |
| Legend | Description |
|---|---|
| 🟩 | Work completed |
| 🟧 | Work in progress |
| 🟥 | Work not started |
| 💪 | Stretch target |
| 🚛 | Backlogged for next quarter |
Typical Deployment
HyperSwitch Monitoring Architecture
In-Memory Configuration Caching
* Hyperswitch eliminates the delays associated with fetching configuration data for each transaction by caching all merchant and processor-related configurations in memory * This ensures that transaction processing remains lightning quick, regardless of the specifics of each transactionRedis for Transaction Data
* To further accelerate transaction processing, Hyperswitch stores all transaction-related data reads in Redis, an in-memory key-value store * This choice of data storage allows for rapid access to transaction details, ensuring that every step of the process is nearly instantaneous.Asynchronous Data Persistence
* Hyperswitch optimizes the transaction workflow by making all data writes to Redis and then asynchronously draining this data to the database * This approach minimizes any potential delays in the critical transaction path, maintaining the rapid pace that customers expectParallelization
* Hyperswitch embraces parallelization wherever possible, ensuring that multiple operations can be executed simultaneously * This approach further enhances its speed and responsiveness, making it a true powerhouse in payment processing(Say Card and Enters their Card Details) SDK->>HS: payments/confirm (client_secret, payment_method_data) HS->>PS: payments/confirm to processor (with merchant credentials) PS-->>HS: payments/confirm response (status) HS-->>SDK: payments/confirm response (status) SDK-->>MC: return to return_url with status ``` ### **How does Payment flow vary across Payment methods?**
| Customer Action | Direct/Redirect flows | Payment- finalized immediately | Payment- finalized later |
|---|---|---|---|
| Customer action required before payments/ confirm | Within Hyperswitch SDK |
|
|
| Customer action required before payments/ confirm | 3rd party Redirect/SDK |
| |
| Customer action required after payments/ confirm | 3rd party Redirect |
|
|
| Accept online payments | Get started with accepting one time payments globally on your online store | /files/bCAWLoNxDHOg3QcQxcCX | /pages/FgH8DjTXnf5Th2C7B2hA | |
| Setup mandates & recurring payments | Setup payments for a future date or charge your customers on a recurring basis | /files/4TGjQBQxLyKgH9W8txTC | /pages/vjpY8TSr0sGJmjWYiifd | |
| Manage payouts | Facilitate payouts for global network of partners and service providers | /files/VBT7SYLnisWYmCYagzp9 | /pages/Aj7TIQDmiomFn5GwFemr | |
| Save a card during payment | Learn how you can save your customers' cards in a secure PCI compliant manner | /files/8LU0asFl64BOjSwrJ8Tl | /pages/xUD3tdwLRlVNcXIxLLia | |
| Manage payments on your platform / marketplace | Accept payments from your customers and process payouts to the sellers on your marketplace | /files/ck7qSNRmkozreP60oZYl | /pages/7IbHrxgL3awnEZxY4x4S | |
| Accept payments on your e-commerce platform | Give your Wordpress store a lightweight and embedded payment experience with the Hyperswitch WooCommerce plugin | /files/m2JKIcMQZUOSicY63lqJ | /pages/ywDpx6aO2SB9SWfj7tCk | |
| Create payment links | Accept payments for your products through reusable links without writing any code | /files/KrF8WgJPBrDY035pM64y | /pages/9AYUf5mZWCiTXihcSYbf |
{confirm: true, capture_method: "manual"} Hyperswitch->>Processor: Authorize Only Processor-->>Hyperswitch: Authorization Hold Hyperswitch-->>Client: Status: requires_capture Note over Client: Ship goods, then capture Client->>Hyperswitch: POST /payments/{id}/capture Hyperswitch->>Processor: Capture Funds Processor-->>Hyperswitch: Capture Complete Hyperswitch-->>Client: Status: succeeded ``` **Flow:** 1. **Authorize:** `POST /payments` with `capture_method: "manual"` 2. **Status:** `requires_capture` 3. **Capture:** `POST /payments/{payment_id}/capture` 4. **Final Status:** `succeeded` Read more: [here](https://docs.hyperswitch.io/~/revisions/2M8ySHqN3pH3rctBK2zj/about-hyperswitch/payment-suite-1/payments-cards/manual-capture) #### 3. Fully Decoupled Flow **Use Case:** Complex checkout journeys with multiple modification steps. Useful in headless checkout or B2B portals where data is filled progressively. ```mermaid %%{init: { "theme": "base", "themeVariables": { "primaryColor": "#ffffff", "primaryBorderColor": "#2563EB", "lineColor": "#2563EB", "secondaryColor": "#EFF6FF", "tertiaryColor": "#DBEAFE", "fontFamily": "Inter, system-ui, sans-serif", "fontSize": "14px", "textColor": "#000000", "actorBkg": "#346DDB", "actorBorder": "#999999", "actorTextColor": "#ffffff", "signalColor": "#000000", "signalTextColor": "#696969", "labelBoxBkgColor": "#346DDB", "labelBoxBorderColor": "#2563EB" } }}%% sequenceDiagram participant Client participant Hyperswitch Client->>Hyperswitch: POST /payments\n(Create Intent) Hyperswitch-->>Client: payment_id + client_secret Client->>Hyperswitch: POST /payments/{id}\n(Update: customer, amount, etc.) Hyperswitch-->>Client: Updated Intent Client->>Hyperswitch: POST /payments/{id}/confirm\n(Final Confirmation) Hyperswitch-->>Client: Status: succeeded / requires_capture opt Manual Capture Client->>Hyperswitch: POST /payments/{id}/capture Hyperswitch-->>Client: Status: succeeded end ``` **Endpoints:** * **Create:** `POST /payments` * **Update:** `POST /payments/{payment_id}` * **Confirm:** `POST /payments/{payment_id}/confirm` * **Capture:** `POST /payments/{payment_id}/capture` (if manual) #### 4. 3D Secure Authentication Flow **Use Case:** Enhanced security with customer authentication ```mermaid %%{init: { "theme": "base", "themeVariables": { "primaryColor": "#ffffff", "primaryBorderColor": "#2563EB", "lineColor": "#2563EB", "secondaryColor": "#EFF6FF", "tertiaryColor": "#DBEAFE", "fontFamily": "Inter, system-ui, sans-serif", "fontSize": "14px", "textColor": "#000000", "actorBkg": "#346DDB", "actorBorder": "#999999", "actorTextColor": "#ffffff", "signalColor": "#000000", "signalTextColor": "#696969", "labelBoxBkgColor": "#346DDB", "labelBoxBorderColor": "#2563EB" } }}%% sequenceDiagram participant Client participant Hyperswitch participant Customer participant Bank Client->>Hyperswitch: POST /payments
{authentication_type: "three_ds"} Hyperswitch-->>Client: Status: requires_customer_action
+ redirect_url Client->>Customer: Redirect to 3DS page Customer->>Bank: Complete 3DS Challenge Bank-->>Hyperswitch: Authentication Result Hyperswitch-->>Hyperswitch: Resume Payment Processing Hyperswitch-->>Client: Status: succeeded ``` **Additional Fields:** * `authentication_type: "three_ds"` **Status Progression:** `processing` → `requires_customer_action` → `succeeded` Read more: [here](https://docs.hyperswitch.io/~/revisions/9QlGypixZFcbkq8oGjaF/explore-hyperswitch/workflows/3ds-decision-manager) ### Recurring Payments and Payment Storage #### 1. Saving Payment Methods **During Payment Creation:** * Add `setup_future_usage: "off_session"` or `"on_session"` * Include `customer_id` * **Result:** `payment_method_id` returned on success **Understanding `setup_future_usage`:** * **`on_session`**: Use when the customer is actively present during the transaction. This is typical for scenarios like saving card details for faster checkouts in subsequent sessions where the customer will still be present to initiate the payment (e.g., card vaulting for e-commerce sites). * **`off_session`**: Use when you intend to charge the customer later without their active involvement at the time of charge. This is suitable for subscriptions, recurring billing, or merchant-initiated transactions (MITs) where the customer has pre-authorized future charges. #### 2. Using Saved Payment Methods ```mermaid %%{init: { "theme": "base", "themeVariables": { "primaryColor": "#ffffff", "primaryBorderColor": "#2563EB", "lineColor": "#2563EB", "secondaryColor": "#EFF6FF", "tertiaryColor": "#DBEAFE", "fontFamily": "Inter, system-ui, sans-serif", "fontSize": "14px", "textColor": "#000000", "actorBkg": "#346DDB", "actorBorder": "#999999", "actorTextColor": "#ffffff", "signalColor": "#000000", "signalTextColor": "#696969", "labelBoxBkgColor": "#346DDB", "labelBoxBorderColor": "#2563EB" } }}%% sequenceDiagram participant Client as Client participant HS as Hyperswitch Client->>HS: POST /payments/create
{customer_id} HS-->>Client: client_secret Client->>HS: GET /customers/payment_methods
{client_secret, publishable_key} HS-->>Client: List of payment_tokens Client->>HS: POST /payments/{id}/confirm
{payment_token} HS-->>Client: Payment Result ``` **Steps:** 1. **Initiate:** Create payment with `customer_id` 2. **List:** Get saved cards via `GET /customers/payment_methods` 3. **Confirm:** Use selected `payment_token` in confirm call #### PCI Compliance and `payment_method_id` Storing `payment_method_id` (which is a token representing the actual payment instrument, which could be a payment token, network token, or payment processor token) significantly reduces your PCI DSS scope. Hyperswitch securely stores the sensitive card details and provides you with this token. While you still need to ensure your systems handle `payment_method_id` and related customer data securely, you avoid the complexities of storing raw card numbers. Always consult with a PCI QSA to understand your specific compliance obligations. ### Recurring Payment Flows #### 3. Customer-Initiated Transaction (CIT) Setup ```mermaid flowchart TD A[CIT Setup] --> B{Setup Type} B -->|With Charge| C[Amount > 0
setup_future_usage:
off_session] B -->|Zero Dollar Auth| D[Amount: 0
payment_type:
setup_mandate] C --> E[payment_method_id] D --> E classDef default fill:#3F8CFF,stroke:#3F8CFF,color:#ffffff,rx:6 classDef accent fill:#3F8CFF,stroke:#3F8CFF,color:#ffffff,rx:6 classDef decision fill:#FFF8E1,stroke:#CCCCCC,color:#1A1A1A class A accent class E accent class B decision ``` Read more: [here](https://docs.hyperswitch.io/~/revisions/j00Urtz9MpwPggJzRCsi/about-hyperswitch/payment-suite-1/payments-cards/recurring-payments) #### 4. Merchant-Initiated Transaction (MIT) Execution ```mermaid %%{init: { "theme": "base", "themeVariables": { "primaryColor": "#ffffff", "primaryBorderColor": "#2563EB", "lineColor": "#2563EB", "secondaryColor": "#EFF6FF", "tertiaryColor": "#DBEAFE", "fontFamily": "Inter, system-ui, sans-serif", "fontSize": "14px", "textColor": "#000000", "actorBkg": "#346DDB", "actorBorder": "#999999", "actorTextColor": "#ffffff", "signalColor": "#000000", "signalTextColor": "#696969", "labelBoxBkgColor": "#346DDB", "labelBoxBorderColor": "#2563EB" } }}%% sequenceDiagram participant Merchant as Merchant participant HS as Hyperswitch participant Processor as Processor Note over Merchant: Subscription billing trigger Merchant->>HS: POST /payments
{off_session: true, recurring_details} HS->>Processor: Process with saved payment_method_id Processor-->>HS: Payment Result HS-->>Merchant: Status: succeeded ``` Read more: [here](https://docs.hyperswitch.io/~/revisions/j00Urtz9MpwPggJzRCsi/about-hyperswitch/payment-suite-1/payments-cards/recurring-payments) ### Status Flow Summary ```mermaid stateDiagram-v2 [*] --> RequiresConfirmation RequiresConfirmation --> Processing : confirm=true Processing --> RequiresCustomerAction : 3DS
needed RequiresCustomerAction --> Processing : 3DS complete Processing --> RequiresCapture : manual capture Processing --> Succeeded : automatic capture Processing --> Failed : payment failed RequiresCapture --> Succeeded : capture API call RequiresCapture --> PartiallyCaptured : partial capture PartiallyCaptured --> [*] Succeeded --> [*] Failed --> [*] ``` ### Notes * **Terminal States:** `succeeded`, `failed`, `cancelled`, `partially_captured` are terminal states requiring no further action * **Capture Methods:** System supports `automatic` (funds captured immediately), `manual` (funds captured in a separate step), `manual_multiple` (funds captured in multiple partial amounts via separate steps), and `scheduled` (funds captured automatically at a future predefined time) capture methods. * **Authentication:** 3DS authentication automatically resumes payment processing after customer completion * **MIT Compliance:** Off-session recurring payments follow industry standards for merchant-initiated transactions # Instant Payment (Auto Capture) Authorize and capture a card payment in a single step — the simplest and most common one-time payment pattern. ### Overview An instant payment charges the customer's card immediately upon confirmation. There is no separate capture step — authorization and capture happen together, and funds are settled without any additional action from your backend. This is the right pattern for most standard checkout flows. ### How It Works ```mermaid sequenceDiagram participant Client participant Hyperswitch participant Processor Client->>Hyperswitch: POST /payments\n{confirm: true, capture_method: "automatic"} Hyperswitch->>Processor: Authorize + Capture Processor-->>Hyperswitch: Payment Complete Hyperswitch-->>Client: Status: succeeded ``` 1. Your backend calls `POST /payments` with `capture_method: "automatic"` 2. Hyperswitch returns a `client_secret` 3. You pass the `client_secret` to the frontend SDK and render Hyperswitch SDK. 4. The Hyperswitch SDK renders the payment form, collects card details, and calls `confirmPayment()` once the use clicks on the make payment button. 5. Hyperswitch sends request to payment process to authorizes and captures the payment in one step. 6. Processor sends the payment response to Juspay Hyperswitch, which is relayed back to merchant. ### SDK Integration
SDK Integration Steps
**Step 1 — Create the Payment (Backend)** ```bash curl --location 'https://sandbox.hyperswitch.io/payments' \ --header 'Content-Type: application/json' \ --header 'Accept: application/json' \ --header 'api-key:API Integration Steps
**Step 1 — Create the Payment (Backend)** ```bash curl --location 'https://sandbox.hyperswitch.io/payments' \ --header 'Content-Type: application/json' \ --header 'Accept: application/json' \ --header 'api-key:Possible states: | Connector Capability | Resulting Status | | -------------------------- | ----------------------------------- | | Single capture only | `partially_captured` | | Multiple capture supported | `partially_captured_and_capturable` | #### Over Capture Over Capture occurs when a merchant captures (settles) an amount greater than the originally authorized amount. You can find detailed docs [here](https://docs.hyperswitch.io/~/revisions/KHifKaZGv4c5XEloMvlu/about-hyperswitch/payment-suite-1/payments-cards/manual-capture/overcapture) # Overcapture Capture amounts greater than the originally authorized amount in manual capture payments ### Overview In card payments, Over Capture occurs when a merchant captures (settles) an amount greater than the originally authorized amount. This is particularly useful in scenarios such as: * Additional charges (e.g., shipping, handling, gratuities). * Price adjustments made after initial authorization. * Reducing the risk of under-capturing when final order values differ. ### Enabling Over Capture #### 1. Profile-level Configuration (via Dashboard) * Navigate to:\ Developer → Payment Settings → Always Enable Over Capture * Toggle Enable/Disable as required. #### 2. Per-request Configuration (via API) Use the boolean field `enable_overcapture` in your payment request. This can be passed in: [POST /payments](https://api-reference.hyperswitch.io/v1/payments/payments--create) [POST /payments/:id/update](https://api-reference.hyperswitch.io/v1/payments/payments--update) {% hint style="warning" %} **Note:** * The request-level `enable_overcapture` will override the profile-level setting. * Over Capture is only applicable for manual capture payments i.e. `capture_method = manual`. {% endhint %} *** ### Example: API Request ```json curl --location 'https://sandbox.hyperswitch.io/payments' \ --header 'Content-Type: application/json' \ --header 'Accept: application/json' \ --header 'api-key:
Follow Steps for SDK integration
Pass the following field in the `/payments` create request to indicate your intention to save the payment method ```bash curl --location 'https://sandbox.hyperswitch.io/payments' \ --header 'Content-Type: application/json' \ --header 'Accept: application/json' \ --header 'api-key:The customer's consent to save their card is expressed through this checkbox
Follow Steps For API Integration
**Step 1 --** Pass the following field in the `/payments` create request to indicate your intention to save the payment method ```bash curl --location 'https://sandbox.hyperswitch.io/payments' \ --header 'Content-Type: application/json' \ --header 'Accept: application/json' \ --header 'api-key:Follow Steps for SDK integration
Pass the following field in the `/payments` create request to indicate your intention to save the payment method ```bash curl --location 'https://sandbox.hyperswitch.io/payments' \ --header 'Content-Type: application/json' \ --header 'Accept: application/json' \ --header 'api-key:Follow Steps for API integration
Pass the following field in the `/payments` create request to indicate your intention to save the payment method ```bash curl --location 'https://sandbox.hyperswitch.io/payments' \ --header 'Content-Type: application/json' \ --header 'Accept: application/json' \ --header 'api-key:"off_session": true,
"recurring_details": {
"type": "payment_method_id",
"data": "pm_lmTnIO5EdCiiMgRPrV9x" //pass the payment method id here
}
"off_session": true,
"recurring_details": {
"type": "network_transaction_id_and_card_details",
"data": {
"card_number": "4242424242424242",
"card_exp_month": "10",
"card_exp_year": "25",
"card_holder_name": "joseph Doe",
"network_transaction_id": "MCC5ZRGMI0925" //scheme transaction id
}
}
| Token Led Payment | Execute a payment using a payment_method_id via S2S API | /pages/ecneth5mwKKB9scVONye |
| Proxy Payment | Send PSP payment requests through the Vault Proxy — raw card data never leaves the Vault | /pages/TMSjT7A6dQjxfw2VxDJI |
| Payment Methods Management | Embed the Vault SDK widget to let customers view, add and delete saved cards | /pages/yyUy7tIb5oaFrDk2XycP |
to PSP (PM_ID replaced with actual card data) PSP -->> HBE: Payment response HBE -->> MBE: Payment response ``` #### 1. Create Payment Method Session (Server-Side) The merchant server initiates the flow by calling the Hyperswitch [`Create-payment-method-session`](https://api-reference.hyperswitch.io/v2/payment-method-session/payment-method-session--create-v1) API with the `customer_id`. Hyperswitch responds with a `sdk_authorization`, which are required to authenticate the client-side session. ```bash curl --request POST \ --url https://sandbox.hyperswitch.io/v1/payment-method-sessions \ --header 'Authorization:
curl --location 'https://sandbox.hyperswitch.io/proxy' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'X-Profile-Id: pro_p3ifmp0HzuC0Bp1KhMnK' \
--header 'Authorization: api-key=dev_bBPAkg0KX9Wn4Zewavrd0W76LsgDpGSey8iMARauXDWqzX4zwk4D03d0851Tx0EV' \
--header 'api-key: dev_30hnPzj6Kk6UAETk9hjWdaIxdVVuTk3mjmz2kxh6CIhq1K1DJ4nTZdpGt986L53G' \
--data '{
"request_body": {
"source": {
"type": "card",
"number": "{{$card_number}}",
"expiry_month": "{{$card_exp_month}}",
"expiry_year": "{{$card_exp_year}}",
"billing_address": {
"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "GB",
"zip": "SW1A 1AA",
"country": "GB"
}
},
"processing_channel_id": "pc_jx5lvimg..",
"amount": 6540,
"currency": "USD",
"payment_type": "Regular",
"reference": "ORD-5023-4E89",
"description": "Set of 3 masks",
"capture": true,
"capture_on": "2019-09-10T10:11:12Z",
},
"destination_url": "https://api.sandbox.checkout.com/payments",
"headers": {
"Content-Type": "application/json",
"Authorization": "Bearer sk_sbox_3uu..."
},
"token": "12345_pm_0196f252baa1736190bf0fc81b9651ea",
"token_type": "payment_method_id",
"method": "POST"
}'
Inclusive
A variety of global payment methods including cards, buy now pay later and digital wallets are supported by the Unified Checkout, with adaptation to local preferences and ability to local language customization.
Consistent
With a diverse set of payment methods supported, the Unified Checkout provides a singular consistent payment experience across platforms (web, android and ios) powered by smart payment forms, minimal redirections and intelligent retries.
Blended
The Unified Checkout includes 40+ styling APIs, which could be tweaked to make the payment experience blend with your product. Your users will get a fully native and embedded payment experience within your app or website
| Prioritizing payment methods You can make an impact on the payment mix or conversion rates by prioritizing/ promoting specific payment methods for your customers. | /pages/zMfShvn3zjsGJugBGUST | /files/nYF8awSzYOaV8W2pSN4H | ||
Switching themes and layouts of checkout page The Unified Checkout comes with a wide range of pre-designed themes and layouts which you can choose from. | /pages/zMfShvn3zjsGJugBGUST | /files/eR1MrGtAScFTn1M8K6uD |
Demo App
You can use this demo app as a reference with your Hyperswitch credentials to test the setup.
{clientSecret && (
)}
```
#### 2.6 Setup the state (optional)
Initialize a state to keep track of payment, display errors and control the user interface.
```js
const [message, setMessage] = useState(null);
const [isLoading, setIsLoading] = useState(false);
```
#### 2.7 Store a reference to `Hyper`
Access the `hyper-js` library in your CheckoutForm component by using the `useHyper()` and `useWidgets()` hooks. If you need to access Widgets via a class component, use the `WidgetsConsumer` instead. You can find the API for these methods here.
```js
const hyper = useHyper();
const widgets = useWidgets();
```
### 3. Complete the checkout on the client
{% tabs %}
{% tab title="ExpressCheckout" %}
**Key Features of Hyperswitch's Express Checkout**
* Fast Performance: One-click payment at checkout enables a smooth and frictionless payment experience to customers.
* Multiple Payment Options: Supports ApplePay, PayPal, Klarna, and GooglePay, giving customers a variety of payment choices on top of the speed in checkout.
* Easy Integration: Our SDK can be easily integrated with web applications.
**Benefits of Hyperswitch's Express Checkout Feature**
* Better User Experience: One-click payment makes shopping easier, leading to more sales and fewer abandoned carts.
* Time Savings: Speeds up the checkout process, saving time for both customers and merchants.
* Great for Mobile: Optimized for mobile shopping with ApplePay, PayPal and GooglePay integration for quick purchases on smartphones.
* Collect billing and shipping details directly from ApplePay, Klarna, GooglePay, PayPal
**3.1 Add the ExpressCheckout**
Alternate Implementation: SDK handles the Confirm Button
For SDK to render the confirm button and handle the confirm payment, in paymentElementOptions, you can send: ```javascript var unifiedCheckoutOptions = { ..., sdkHandleConfirmPayment: { handleConfirm: true, buttonText: "SDK Pay Now", confirmParams: { return_url: "https://example.com/complete", }, }, }; ``` 1. **`handleConfirm (required)`** - A boolean value indicating whether the SDK should handle the confirmation of the payment. 2. **`confirmParams (required)`** - It's an object which takes return\_url. return\_url parameter specifies the URL where the user should be redirected after payment confirmation. 3. **`buttonText (optional)`** - The text to display on the payment button.\ Default value: **Pay Now** For customization, please follow the [`Customization docs`](https://docs.hyperswitch.io/hyperswitch-cloud/integration-guide/web/customization#id-5.-confirm-button).Alternate Implementation: SDK handles the Confirm Button
For SDK to render the confirm button and handle the confirm payment, in paymentElementOptions, you can send: ```html const unifiedCheckoutOptions = { ..., sdkHandleConfirmPayment: { handleConfirm: true, buttonText: "SDK Pay Now", confirmParams: { return_url: "https://example.com/complete", }, }, }; ``` 1. **`handleConfirm (required)`** - A boolean value indicating whether the SDK should handle the confirmation of the payment. 2. **`confirmParams (required)`** - It's an object which takes return\_url. return\_url parameter specifies the URL where the user should be redirected after payment confirmation. 3. **`buttonText (optional)`** - The text to display on the payment button.\ Default value: **Pay Now** For customization, please follow the [`Customization docs`](https://docs.hyperswitch.io/hyperswitch-cloud/integration-guide/web/customization#id-5.-confirm-button).// Source Hyperloader on your HTML file using the <script /> tag
hyper = Hyper.init("YOUR_PUBLISHABLE_KEY",{
customBackendUrl: "YOUR_BACKEND_URL",
//You can configure this as an endpoint for all the api calls such as session, payments, confirm call.
});
| options (Required) | Description |
|---|---|
confirmParams (object) | Parameters that will be passed on to the Hyper API. |
redirect (string) | Can be either 'always' or 'if_required' By default, |
id (string)(optional) | The id used when creating the CardCVCElement. |
| confirmParams | Description |
|---|---|
return_url(string) | The url your customer will be directed to after they complete payment. |
| options (Required) | Description |
|---|---|
confirmParams (object) | Parameters that will be passed on to the Hyper API. |
redirect (string) | Can be either 'always' or 'if_required' By default, |
id (string)(optional) | The id used when creating the CardCVCElement. |
| confirmParams | Description |
|---|---|
return_url(string) | The url your customer will be directed to after they complete payment. |
{/* Render your saved card UI here */}
{/* CVC Element */}
);
}
```
# Customization
Customize your Web unified checkout for Juspay Hyperswitch
### 1. Layouts
Choose a layout that fits well with your UI pattern. There are two types of layout options as listed below. The layout defaults to accordion if not explicitly specified.
#### 1.1 Accordion layout
The accordion layout displays payment methods vertically using an accordion. To use this layout, set the value for layout to accordion. You also have the option to specify other properties, such as those shown in the following example.
```js
var paymentElementOptions = {
layout: {
type: 'accordion',
defaultCollapsed: false,
radios: true,
spacedAccordionItems: false
},
}
--- or ---
var paymentElementOptions = {
layout: 'accordion'
}
{message}
}
var paymentElementOptions = {
wallets: {
walletReturnUrl: `${window.location.origin}`,
applePay: "auto",
googlePay: "auto",
payPal: "auto",
klarna: "never",
style: {
theme: "dark",
type: "default",
height: 55,
buttonRadius: 4,
},
},
}
<PaymentElement id="payment-element" options={paymentElementOptions} />
applePay: showType
googlePay: showType
payPal: showType
klarna: showType
showType can take two values:
"auto": Display when supported."never": Always hidden
style: {
theme: theme,
type: styleType,
height: int,
buttonRadius: int,
}
Configures the wallet's appearance with the following options:
theme: Sets the theme.type: Defines the style type (e.g. buy).height: Specifies the height of the wallet.buttonRadius: Adjusts the button corner radius.
theme: It can take values as dark, light, or outline.type: Specifies the wallet button style with options including checkout, pay, buy, installment, default, book, donate, order, addmoney, topup, rent, subscribe, reload, support, tip, and contribute.
var paymentElementOptions = {
...,
branding: "never", // choose between "never" and "always"
}
<PaymentElement id="payment-element" options={paymentElementOptions} />
var paymentElementOptions = {
...,
paymentMethodsHeaderText: "Select Payment Method",
}
<PaymentElement id="payment-element" options={paymentElementOptions} />
var paymentElementOptions = {
...,
savedPaymentMethodsHeaderText: "Saved Payment Methods",
}
<PaymentElement id="payment-element" options={paymentElementOptions} />
var paymentElementOptions = {
...,
customMessageForCardTerms: "Custom message for Card terms",
}
<PaymentElement id="payment-element" options={paymentElementOptions} />
Inclusive
Global payments, diverse methods - cards, buy now pay later, and digital wallets. Unified Checkout adapts to local preferences, integrates languages for an inclusive solution.
| | ------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | |Consistent
Consistent payment experience on Web, Android, and iOS with smart forms, minimal redirects, and intelligent retries. Unified Checkout ensures reliability and uniformity.
| |Blended
Tailor payment seamlessly with 40+ styling APIs for a native, cohesive, branded checkout in your Android app or website.
| **Modify and Experiment:** While the Unified Checkout is pre-optimized for maximum conversions, the Hyperswitch Android SDK empowers you to go beyond the standard. Take control with our SDK APIs, allowing you: * **Include New Fields:** Adapt swiftly to various use cases by adding new fields to the payment form, such as collecting billing addresses or zip codes for additional information. * **Prioritize Payment Methods:** Impact your payment mix and conversion rates by prioritizing or promoting specific payment methods based on your customer preferences. * **Switch Themes and Layouts:** Choose from a wide range of pre-designed themes and layouts for the checkout page, aligning the Unified Checkout with your app's aesthetics. Experience the flexibility to modify and experiment, ensuring your app's payment journey aligns precisely with your business requirements and user expectations. Elevate your Android app's payment experience with the Hyperswitch Android SDK. # Kotlin with REST API Integration Integrate hyper SDK to your Kotlin App using hyperswitch-nodeDemo App
You can use this demo app as a reference with your Juspay Hyperswitch credentials to test the setup.buildscript {
repositories {
mavenCentral()
}
dependencies {
classpath "io.hyperswitch:hyperswitch-gradle-plugin:$latest_version"
}
}
buildscript {
repositories {
mavenCentral()
}
dependencies {
classpath "io.hyperswitch:hyperswitch-gradle-plugin:$latest_version"
}
}
var handler: PaymentSessionHandler? = null
paymentSession.getCustomerSavedPaymentMethods { paymentSessionHandler ->
handler = paymentSessionHandler
}
val savedPaymentMethod = handler!!.getCustomerLastUsedSavedPaymentMethodData()
button.setOnClickListener {
handler!!.confirmWithCustomerLastUsedPaymentMethod { paymentResult ->
println(paymentResult)
}
}
| options (Required) | Description |
|---|---|
callback (method) | Callback to get confirm response. |
import Hyperswitch
paymentSession = PaymentSession(publishableKey: <YOUR_PUBLISHABLE_KEY>)
//Create a card element view and pay button.
lazy var hyperCardTextField: PaymentCardTextField = {
let cardTextField = PaymentCardTextField()
return cardTextField
}()
lazy var payButton: UIButton = {
let button = UIButton(type: .custom)
button.layer.cornerRadius = 5
button.backgroundColor = .systemBlue
button.setTitle("Pay", for: .normal)
button.addTarget(self, action: #selector(pay), for: .touchUpInside)
return button
}()
@objc
func pay() {
guard let paymentIntentClientSecret = model.paymentIntentClientSecret else {
return
}
let paymentIntentParams = PaymentIntentParams(clientSecret: paymentIntentClientSecret)
let paymentHandler = PaymentHandler.shared()
paymentHandler.confirmPayment(paymentIntentParams, with: self) {
(status, paymentIntent, error) in
switch (status) {
case .failed:
break
case .canceled:
break
case .succeeded:
break
@unknown default:
fatalError()
break
}
}
}
private var handler: PaymentSessionHandler?
func initSavedPaymentMethodSessionCallback(handler: PaymentSessionHandler)-> Void {
self.handler = handler
}
@objc func launchHeadless(_ sender: Any) {
paymentSession!.getCustomerSavedPaymentMethods(initSavedPaymentMethodSessionCallback)
}
@objc func confirmPayment(_ sender: Any) {
let paymentMethod = self.handler!.getCustomerLastUsedSavedPaymentMethodData(callback)
}
@objc func confirmPayment(_ sender: Any) {
self.handler!.confirmWithLastUsedSavedPaymentMethodData(callback)
}
| options (Required) | Description |
|---|---|
callback (function) | Callback to get confirm response. |
| Color Category | Usage |
|---|---|
| primary | Primary defines the color of the Pay button and selected items |
| background | The color used for the background of your Payment page |
| componentBackground | The color used for the background of inputs, tabs, and other components |
| componentBorder | The color used for the external border of inputs, tabs, and other components in your PaymentSheet |
| componentDivider | The color used for the internal border (meaning the border is shared with another component) of inputs, tabs, and other components in your PaymentSheet |
| primaryText | The color of the header text in your Payment page |
| secondaryText | The color of the label text of input fields |
| componentText | The color of the input text in your PaymentSheet components, such as the user's card number or zip code |
| placeholderText | The color of the placeholder text of input fields |
| icon | The color used for icons in your Payment Sheet, such as the close (x) button |
| error | The color used to indicate errors or destructive actions in your Payment Sheet |
| options (Required) | Description |
|---|---|
callback (function) | Callback to get confirm response. |
Can I create a payment link pointing to my custom domain?
Yes. Your custom domain can be included in the default payment\_link\_config object as part of the business profile update. This involves adding CNAME records and TLS certificates which ends up being a slightly complex process. Please reach out to our [Support](https://join.slack.com/t/hyperswitch-io/shared_invite/zt-1k6cz4lee-SAJzhz6bjmpp4jZCDOtOIg) to test this feature out with your custom domain.Can I configure Payment links through Hyperswitch Control centre?
Currently, the Control centre's capability to create payment links is under development and will be available by Q1'24.Can I create a static payment link which can be used across users?
No, at the moment we do not support creation of static payment links ([request for feature](https://github.com/juspay/hyperswitch/discussions/new?category=ideas-feature-requests))How long is the Payment link valid for?
The payment link is valid for 15 minutes by default. However you can increase the validity to up to 3-months (7890000) by passing the time in seconds in `session_expiry` in the create payment link call.How can I send Payment links via Emails?
Hyperswitch supports generation of the payment link. We are not integrated with any email servers. You'll need to have a mail server integration at your end and ingest the payment links to the emails being sent.Primary theme
Primary theme
Custom seller name
Dynamic details
Background image
Default layout
Layout 2
Accordion layout
Render only the payment widget
Save payment method checkbox
Saved payment methods
Hidden card nickname field when card is requested to be saved
Visible card nickname field when card is requested to be saved
Custom text for payment widget's button
Visible branding (default behaviour)
Hidden branding
| Device-aware | Apple Pay and Google Pay are shown only on supported devices. The SDK auto-detects features like Touch ID / Face ID, no merchant logic needed. |
| Geo-specific filtering | Methods like EPS, Giropay, or SEPA and features such as co-brand cards are shown only in supported regions, using device location or merchant provided locale and context. |
| Config-based enable or disable | Payment methods, card scanning, and third-party SDKs (e.g., Klarna, Netcetera) are enabled via static or connector-based configuration. |
| Dynamic ordering | Methods can be prioritized based on rules. Presenting users with their preferred payment methods boosts convenience and conversion rates. |
| Dynamic Fields | Fields like cardholder name, billing/shipping address, email, and phone are dynamically rendered based on connector requirements. |
| Cross-platform & multi-tenant | Unified SDK across iOS, Android, Flutter, and React Native. Works across SaaS and self-hosted setups. |
| Full Control Over Design & Functionality | Customize both the appearance and behavior of the checkout experience. |
| Advanced Security, No Redirection | Seamlessly integrate native 3DS and Click to Pay for secure, frictionless transactions. |
| Session level overrides | All configurations with respect to payment method display, look-and-feel, and behavior can be overridden at session level. |
# Web Integrate Juspay Hyperswitch unified checkout with your web app for a seamless payment experience #### Global Checkout Experience Juspay Hyperswitch Unified Checkout is an inclusive, consistent and blended payment experience optimized for the best conversion rates.
| /files/AXMCQgXc2vMsBEsXcw5L | Inclusive A variety of global payment methods including cards, buy now pay later and digital wallets are supported by the Unified Checkout, with adaptation to local preferences and ability to local language customization. |
| /files/AXMCQgXc2vMsBEsXcw5L | Consistent With a diverse set of payment methods supported, the Unified Checkout provides a singular consistent payment experience across platforms (web, android and ios) powered by smart payment forms, minimal redirections and intelligent retries. |
| /files/Q3A2l8aZ4v4blbhV6KtA | Blended The Unified Checkout includes 40+ styling APIs, which could be tweaked to make the payment experience blend with your product. Your users will get a fully native and embedded payment experience within your app or website |
| Cover image | ||||
|---|---|---|---|---|
| Prioritizing payment methods You can make an impact on the payment mix or conversion rates by prioritizing/ promoting specific payment methods for your customers. | /files/Vo9U3DsiQaVJgEUJYe5C | |||
Switching themes and layouts of checkout page The Unified Checkout comes with a wide range of pre-designed themes and layouts which you can choose from. | /files/AgnVOivkJHZmZNrIuyUr |
Demo App
You can use this demo app as a reference with your Hyperswitch credentials to test the setup.
{clientSecret && (
)}
```
**2.6 Setup the state (optional)**
Initialize a state to keep track of payment, display errors and control the user interface.
```js
const [message, setMessage] = useState(null);
const [isLoading, setIsLoading] = useState(false);
```
**2.7 Store a reference to `Hyper`**
Access the `hyper-js` library in your CheckoutForm component by using the `useHyper()` and `useWidgets()` hooks. If you need to access Widgets via a class component, use the `WidgetsConsumer` instead. You can find the API for these methods here.
```js
const hyper = useHyper();
const widgets = useWidgets();
```
#### 3. Complete the checkout on the client
{% tabs %}
{% tab title="ExpressCheckout" %}
**Key Features of Hyperswitch's Express Checkout**
* Fast Performance: One-click payment at checkout enables a smooth and frictionless payment experience to customers.
* Multiple Payment Options: Supports ApplePay, PayPal, Klarna, and GooglePay, giving customers a variety of payment choices on top of the speed in checkout.
* Easy Integration: Our SDK can be easily integrated with web applications.
**Benefits of Hyperswitch's Express Checkout Feature**
* Better User Experience: One-click payment makes shopping easier, leading to more sales and fewer abandoned carts.
* Time Savings: Speeds up the checkout process, saving time for both customers and merchants.
* Great for Mobile: Optimized for mobile shopping with ApplePay, PayPal and GooglePay integration for quick purchases on smartphones.
* Collect billing and shipping details directly from ApplePay, Klarna, GooglePay, PayPal
**3.1 Add the ExpressCheckout**
> The Express Checkout Element gives you a single integration for accepting payments through one-click payment buttons. Supported payment methods include ApplePay, GooglePay and PayPal.
Add the `ExpressCheckout` to your Checkout. This embeds an iframe that displays configured payment method types supported by the browser available for the Payment, allowing your customer to select a payment method. The payment methods automatically collects the associated payment details for the selected payment method type.
Define paymentElementOptions:
```js
var expressCheckoutOptions = {
wallets: {
walletReturnUrl: "https://example.com/complete",
//Mandatory parameter for Wallet Flows such as Googlepay, Paypal and Applepay
},
};
```
```js
Alternate Implementation: SDK handles the Confirm Button
For SDK to render the confirm button and handle the confirm payment, in paymentElementOptions, you can send: ```javascript var unifiedCheckoutOptions = { ..., sdkHandleConfirmPayment: { handleConfirm: true, buttonText: "SDK Pay Now", confirmParams: { return_url: "https://example.com/complete", }, }, }; ``` 1. **`handleConfirm (required)`** - A boolean value indicating whether the SDK should handle the confirmation of the payment. 2. **`confirmParams (required)`** - It's an object which takes return\_url. return\_url parameter specifies the URL where the user should be redirected after payment confirmation. 3. **`buttonText (optional)`** - The text to display on the payment button.\ Default value: **Pay Now** For customization, please follow the [`Customization docs`](https://docs.hyperswitch.io/hyperswitch-cloud/integration-guide/web/customization#id-5.-confirm-button).Alternate Implementation: SDK handles the Confirm Button
For SDK to render the confirm button and handle the confirm payment, in paymentElementOptions, you can send: ```html const unifiedCheckoutOptions = { ..., sdkHandleConfirmPayment: { handleConfirm: true, buttonText: "SDK Pay Now", confirmParams: { return_url: "https://example.com/complete", }, }, }; ``` 1. **`handleConfirm (required)`** - A boolean value indicating whether the SDK should handle the confirmation of the payment. 2. **`confirmParams (required)`** - It's an object which takes return\_url. return\_url parameter specifies the URL where the user should be redirected after payment confirmation. 3. **`buttonText (optional)`** - The text to display on the payment button.\ Default value: **Pay Now** For customization, please follow the [`Customization docs`](https://docs.hyperswitch.io/hyperswitch-cloud/integration-guide/web/customization#id-5.-confirm-button).// Source Hyperloader on your HTML file using the <script /> tag
hyper = Hyper.init("YOUR_PUBLISHABLE_KEY",{
customBackendUrl: "YOUR_BACKEND_URL",
//You can configure this as an endpoint for all the api calls such as session, payments, confirm call.
});
| options (Required) | Description |
|---|---|
confirmParams (object) | Parameters that will be passed on to the Hyper API. |
redirect (string) | Can be either 'always' or 'if_required' By default, |
id (string)(optional) | The id used when creating the CardCVCElement. |
| confirmParams | Description |
|---|---|
return_url(string) | The url your customer will be directed to after they complete payment. |
| options (Required) | Description |
|---|---|
confirmParams (object) | Parameters that will be passed on to the Hyper API. |
redirect (string) | Can be either 'always' or 'if_required' By default, |
id (string)(optional) | The id used when creating the CardCVCElement. |
| confirmParams | Description |
|---|---|
return_url(string) | The url your customer will be directed to after they complete payment. |
{/* Render your saved card UI here */}
{/* CVC Element */}
);
}
```
# Customization
Customize your Web unified checkout for Juspay Hyperswitch
#### 1. Layouts
Choose a layout that fits well with your UI pattern. There are two types of layout options as listed below. The layout defaults to accordion if not explicitly specified.
**1.1 Accordion layout**
The accordion layout displays payment methods vertically using an accordion. To use this layout, set the value for layout to accordion. You also have the option to specify other properties, such as those shown in the following example.
```js
var paymentElementOptions = {
layout: {
type: 'accordion',
defaultCollapsed: false,
radios: true,
spacedAccordionItems: false
},
}
--- or ---
var paymentElementOptions = {
layout: 'accordion'
}
{message}
}
var paymentElementOptions = {
wallets: {
walletReturnUrl: `${window.location.origin}`,
applePay: "auto",
googlePay: "auto",
payPal: "auto",
klarna: "never",
style: {
theme: "dark",
type: "default",
height: 55,
buttonRadius: 4,
},
},
}
<PaymentElement id="payment-element" options={paymentElementOptions} />
applePay: showType
googlePay: showType
payPal: showType
klarna: showType
showType can take two values:
"auto": Display when supported."never": Always hidden
style: {
theme: theme,
type: styleType,
height: int,
buttonRadius: int,
}
Configures the wallet's appearance with the following options:
theme: Sets the theme.type: Defines the style type (e.g. buy).height: Specifies the height of the wallet.buttonRadius: Adjusts the button corner radius.
theme: It can take values as dark, light, or outline.type: Specifies the wallet button style with options including checkout, pay, buy, installment, default, book, donate, order, addmoney, topup, rent, subscribe, reload, support, tip, and contribute.
var paymentElementOptions = {
...,
branding: "never", // choose between "never" and "always"
}
<PaymentElement id="payment-element" options={paymentElementOptions} />
var paymentElementOptions = {
...,
paymentMethodsHeaderText: "Select Payment Method",
}
<PaymentElement id="payment-element" options={paymentElementOptions} />
var paymentElementOptions = {
...,
savedPaymentMethodsHeaderText: "Saved Payment Methods",
}
<PaymentElement id="payment-element" options={paymentElementOptions} />
var paymentElementOptions = {
...,
customMessageForCardTerms: "Custom message for Card terms",
}
<PaymentElement id="payment-element" options={paymentElementOptions} />
| /files/AXMCQgXc2vMsBEsXcw5L | Inclusive Global payments, diverse methods - cards, buy now pay later, and digital wallets. Unified Checkout adapts to local preferences, integrates languages for an inclusive solution. |
| /files/Us9HbXHZjiMUXAizn8OO | Consistent Consistent payment experience on Web, Android, and iOS with smart forms, minimal redirects, and intelligent retries. Unified Checkout ensures reliability and uniformity. |
| /files/q5U70Wk9354voSk6bWrZ | Blended Tailor payment seamlessly with 40+ styling APIs for a native, cohesive, branded checkout in your Android app or website. |
Demo App
You can use this demo app as a reference with your Juspay Hyperswitch credentials to test the setup.buildscript {
repositories {
mavenCentral()
}
dependencies {
classpath "io.hyperswitch:hyperswitch-gradle-plugin:$latest_version"
}
}
hyperswitch {
// Optional: Specify main SDK version (defaults to latest if not specified)
sdkVersion = "latest_version"
// Optional features - only add what you need
features = [HyperFeature.SCANCARD, HyperFeature.NETCETERA]
}
buildscript {
repositories {
mavenCentral()
}
dependencies {
classpath "io.hyperswitch:hyperswitch-gradle-plugin:$latest_version"
}
}
var handler: PaymentSessionHandler? = null
paymentSession.getCustomerSavedPaymentMethods { paymentSessionHandler ->
handler = paymentSessionHandler
}
val savedPaymentMethod = handler!!.getCustomerLastUsedSavedPaymentMethodData()
button.setOnClickListener {
handler!!.confirmWithCustomerLastUsedPaymentMethod { paymentResult ->
println(paymentResult)
}
}
| options (Required) | Description |
|---|---|
callback (method) | Callback to get confirm response. |
| /files/AXMCQgXc2vMsBEsXcw5L | Inclusive: Supporting a diverse array of global payment methods, including cards, buy now pay later, and digital wallets, the Unified Checkout adapts to local preferences. Customize the experience further with the ability to integrate local languages, creating a truly inclusive payment solution. |
| /files/Us9HbXHZjiMUXAizn8OO | Consistent: Enjoy a singular and consistent payment experience across platforms, whether on the web, Android, or iOS. Driven by smart payment forms, minimal redirections, and intelligent retries, the Unified Checkout ensures a reliable and uniform payment process. |
| /files/gLu96LykMhTz9C74k3B9 | Blended: Tailor the payment experience to seamlessly integrate with your product using 40+ styling APIs. Achieve a fully native and embedded payment experience within your iOS app or website, creating a cohesive and branded checkout environment. |