diff --git a/about-hyperswitch/payment-suite-1/payment-method-card/copy-of-payments.md b/about-hyperswitch/payment-suite-1/payment-method-card/copy-of-payments.md index 2884e262..17f12000 100644 --- a/about-hyperswitch/payment-suite-1/payment-method-card/copy-of-payments.md +++ b/about-hyperswitch/payment-suite-1/payment-method-card/copy-of-payments.md @@ -1,26 +1,26 @@ --- +description: >- + Explore Copy of Payments to enhance your payment orchestration capabilities hidden: true icon: money-bills-simple --- - # Copy of Payments The Payment Method SDK provides APIs to securely capture and tokenize payment credentials, with support for vaulting payment details during the initial checkout flow. Upon successful vaulting, a persistent payment method ID is generated, which merchants can store and use to programmatically initiate subsequent transactions without re-collecting sensitive payment data. -#### **Key Features** +### **Key Features** * **Full Token Management** – Create, retrieve, update, and delete payment tokens directly from your server. * **PSP and Network Tokenization** – Generate both PSP tokens and network tokens through a single API. * **Secure Storage** – Store tokens safely in Hyperswitch’s Vault. * **Reduced Frontend Complexity** – Shift tokenization processes to the backend, minimizing frontend dependencies. -#### Understanding Payment and Vault Flow - +### Understanding Payment and Vault Flow
-#### **Vaulting :** +### **Vaulting :** **1. Create Customer (Server-Side)** @@ -42,7 +42,7 @@ Your server makes a [`/v2/payment-methods`](https://api-reference.hyperswitch.io Hyperswitch returns the `payment_method_id` in the response. You can use this payment method ID for future payments for this customer without handling sensitive card data again. -#### **Payment :** +### **Payment :** To charge the customer you will will have to call the [create and confirm](https://api-reference.hyperswitch.io/v2/payments/payments--create-and-confirm-intent) API and pass the `payment_method_id` along with `confirm` as `true` @@ -59,6 +59,6 @@ To generate your Vault API keys, follow these steps: **Integration Documentation -** -* [S2S Vault Tokenization](https://docs.hyperswitch.io/~/revisions/TGn71uwTlQJmyyiYgHpt/explore-hyperswitch/payments-modules/vault/server-to-server-vault-tokenization) +* [S2S Vault Tokenization](https://docs.hyperswitch.io/~/revisions/TGn71uwTlQJmyyiYgHpt/explore-Hyperswitch/payments-modules/vault/server-to-server-vault-tokenization) * [Create Payment API](https://api-reference.hyperswitch.io/v1/payments/payments--create) * [Payment Create and Confirm API](https://api-reference.hyperswitch.io/v2/payments/payments--create-and-confirm-intent) diff --git a/about-hyperswitch/payment-suite-1/payment-method-card/payment-methods-management.md b/about-hyperswitch/payment-suite-1/payment-method-card/payment-methods-management.md index b795a76f..4084496c 100644 --- a/about-hyperswitch/payment-suite-1/payment-method-card/payment-methods-management.md +++ b/about-hyperswitch/payment-suite-1/payment-method-card/payment-methods-management.md @@ -1,8 +1,8 @@ --- -description: Hyperswitch is designed to facilitate the management of saved payment methods +description: >- + Explore Payment Methods Management to enhance your payment orchestration capabilities icon: bars-progress --- - # Payment Methods Management The Hyperswitch Payment Methods Management SDK provides a secure solution for merchants to handle and store payment information without the burden of PCI DSS compliance requirements. By leveraging Hyperswitch's Vault service, merchants can securely store customer payment methods (credit cards, digital wallets, etc.) while minimizing their exposure to sensitive payment data. @@ -11,19 +11,19 @@ The Hyperswitch Payment Methods Management SDK provides a secure solution for me Hyperswitch simplifies the complexities of payment method management, so you can offer a seamless, secure experience to your customers with minimal effort. -#### **Payment Method Creation**: +### **Payment Method Creation**: Easily allow your customers to save new payment methods during checkout, providing a convenient option for future transactions. -#### **Storing Payment Methods**: +### **Storing Payment Methods**: Hyperswitch securely stores customer payment details, enabling repeat purchases without requiring them to re-enter their information each time. -#### **Retrieving Payment Methods**: +### **Retrieving Payment Methods**: Customers can quickly access their saved payment methods, streamlining their checkout process and enhancing their overall experience. -#### **Deleting/Deactivating Payment Methods**: +### **Deleting/Deactivating Payment Methods**: Keep payment options up to date by allowing customers to manage outdated or inactive methods, ensuring a clean and efficient payment experience. @@ -31,7 +31,7 @@ Keep payment options up to date by allowing customers to manage outdated or inac ### Integration Guide : -#### 1. Server-Side Setup +### 1. Server-Side Setup First, you'll need to set up your server to create payment method sessions, which establish secure connections between your frontend and the Hyperswitch Vault. @@ -60,7 +60,7 @@ app.post("/create-payment-method-session", async (req, res) => { try { // Create payment method session on Hyperswitch const response = await fetch( - `${HYPERSWITCH_SERVER_URL}/v2/payment-method-sessions`, + `${Hyperswitch_SERVER_URL}/v2/payment-method-sessions`, { method: "POST", headers: { @@ -96,7 +96,7 @@ app.post("/create-payment-method-session", async (req, res) => { > **Note**: Replace `YOUR_PROFILE_ID` and `YOUR_API_KEY` with your actual credentials from the Hyperswitch dashboard. -#### 2. Client-Side Integration +### 2. Client-Side Integration Once your server endpoint is set up, you'll need to integrate the Vault/Payment Methods Management SDK into your client application. diff --git a/about-hyperswitch/payment-suite-1/payment-method-card/payments.md b/about-hyperswitch/payment-suite-1/payment-method-card/payments.md index ed3bf83c..bbd2402f 100644 --- a/about-hyperswitch/payment-suite-1/payment-method-card/payments.md +++ b/about-hyperswitch/payment-suite-1/payment-method-card/payments.md @@ -1,7 +1,8 @@ --- +description: >- + Explore Payments to enhance your payment orchestration capabilities icon: money-bills-simple --- - # Payments The Payment Method SDK and `/payment-methods` API work in tandem with the `/payments` API to achieve any business objective as listed below. @@ -42,7 +43,7 @@ For logged-in user checkout flow the PM ID is unique to Customer + Payment metho 1. Create a PM session using the [Session Create API ](https://api-reference.hyperswitch.io/v2/payment-method-session/payment-method-session--create-v1)to get a [client secret](https://api-reference.hyperswitch.io/v2/payment-method-session/payment-method-session--create-v1#response-client-secret) 2. For guest user, pass "storage\_type" as "volatile" and skip sending the Customer ID -3. Initialize and mount the [Vault SDK](https://docs.hyperswitch.io/explore-hyperswitch/payments-modules/vault/vault-sdk-integration-1#id-2.2-fetch-the-payment-method-session-and-mount-the-payment-methods-management-element) using the client secret and session\_id +3. Initialize and mount the [Vault SDK](https://docs.hyperswitch.io/explore-Hyperswitch/payments-modules/vault/vault-sdk-integration-1#id-2.2-fetch-the-payment-method-session-and-mount-the-payment-methods-management-element) using the client secret and session\_id 4. The SDK now takes care of the following flows based on user action: 5. Post which the SDK submits the card details via the [PM Confirm API](https://api-reference.hyperswitch.io/v1/payments/payments--confirm) and returns back a [PM Token](https://api-reference.hyperswitch.io/v1/payments/payments--confirm#response-payment-token-one-of-0) (short-lived) in the response 6. Pass this PM token to Merchant Server and exchange for a PM ID from the server using the [PM token exchange API](https://api-reference.hyperswitch.io/v2/payment-methods/payment-method--payment-method-token-to-payment-method-id-v1) @@ -55,7 +56,7 @@ Note - When using the HS SDK, the response always contains a temp token and you ### HS SDK Checkout for repeat customer - no CVV flow 1. Create a PM session using the [Session Create API ](https://api-reference.hyperswitch.io/v2/payment-method-session/payment-method-session--create-v1)to get a [client secret](https://api-reference.hyperswitch.io/v2/payment-method-session/payment-method-session--create-v1#response-client-secret) -2. Initialize and mount the [Vault SDK](https://docs.hyperswitch.io/explore-hyperswitch/payments-modules/vault/vault-sdk-integration-1#id-2.2-fetch-the-payment-method-session-and-mount-the-payment-methods-management-element) using the client secret and session\_id +2. Initialize and mount the [Vault SDK](https://docs.hyperswitch.io/explore-Hyperswitch/payments-modules/vault/vault-sdk-integration-1#id-2.2-fetch-the-payment-method-session-and-mount-the-payment-methods-management-element) using the client secret and session\_id 3. The SDK lists the previously saved cards for customers to select 4. If the card has been vaulted previously with an MIT setup for it, CVV is not collected for it and the SDK returns back a [PM Token](https://api-reference.hyperswitch.io/v1/payments/payments--confirm#response-payment-token-one-of-0) (short-lived) in the responseNote - The PM ID in case of guest checkout is volatile in nature and has a default expiry of 1-hour which can be extended by Merchant at a session level diff --git a/about-hyperswitch/payment-suite-1/payment-method-card/proxy.md b/about-hyperswitch/payment-suite-1/payment-method-card/proxy.md index 2bf454e8..3ce7d314 100644 --- a/about-hyperswitch/payment-suite-1/payment-method-card/proxy.md +++ b/about-hyperswitch/payment-suite-1/payment-method-card/proxy.md @@ -1,8 +1,8 @@ --- -description: Vault your card and use proxy end point for payment processing +description: >- + Explore Proxy to enhance your payment orchestration capabilities icon: almost-equal-to --- - # Proxy The Proxy Payments Service allows merchants to tokenize cards via Hyperswitch Vault and make API calls to PSPs using those tokens. The Vault intercepts these requests, replaces tokens with raw card data (de-tokenization), and forwards them securely to the PSP. @@ -18,7 +18,7 @@ Key Highlights:
-#### **1. Create Payment Method Session (Server-Side)** +### **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#payment-method-session-create) API with the `customer_id`. Hyperswitch responds with a `session_id` and `client_secret`, which are required to authenticate the client-side session. @@ -35,7 +35,7 @@ curl --request POST \ ' ``` -#### **2. Initialize SDK (Client-Side)** +### **2. Initialize SDK (Client-Side)** The merchant client loads the `HyperLoader.js` script and initializes `window.Hyper` using the Publishable Key. Using the `session_id` and `client_secret`, the SDK creates a Payment Method Management (PMM) group and mounts the specific widget instance to the UI. @@ -91,22 +91,22 @@ async function initialize() { initialize(); ``` -#### **3. Collect and Vault Card (Client-Side)** +### **3. Collect and Vault Card (Client-Side)** The customer enters their card details directly into the SDK-managed widget. Upon confirmation, the SDK calls the /`Confirm a payment method session` API. Hyperswitch securely receives the data, stores it in the Vault (retaining the CVV temporarily for the transaction TTL), and returns a success response with the `session_id` to the client. -#### **4. Retrieve Payment Method ID (Server-Side)** +### **4. Retrieve Payment Method ID (Server-Side)** The merchant server calls the "List Payment Methods" API using the `session_id`. Hyperswitch returns a list of payment methods associated with the customer, from which the merchant server selects the appropriate `PM_ID` (Payment Method ID) to use for the transaction. **Execute Proxy Payment (Server-Side)** -The merchant server initiates the payment by sending a request to the [Hyperswitch vault proxy](https://docs.hyperswitch.io/~/revisions/01bZ2maqjwpnmrttix7i/explore-hyperswitch/payments-modules/vault/hyperswitch-vault-pass-through-proxy-payments) endpoint using the `payment_method_id` . The proxy securely replaces the token with the actual card data from the Vault and forwards the request to the Payment Service Provider (PSP), returning the final payment response to the merchant. +The merchant server initiates the payment by sending a request to the [Hyperswitch vault proxy](https://docs.hyperswitch.io/~/revisions/01bZ2maqjwpnmrttix7i/explore-Hyperswitch/payments-modules/vault/hyperswitch-vault-pass-through-proxy-payments) endpoint using the `payment_method_id` . The proxy securely replaces the token with the actual card data from the Vault and forwards the request to the Payment Service Provider (PSP), returning the final payment response to the merchant. **New user payments flow** 1. Create Payment Method Session (Server-Side) The merchant server initiates the flow by calling the Hyperswitch -2. [Initialize SDK (Client-Side) ](../../../explore-hyperswitch/payment-experience/payment-method/)The merchant client loads the `HyperLoader.js` script and initializes `window.Hyper` using the Publishable Key. Using the `session_id` and `client_secret`, the SDK creates a Payment Method Management (PMM) group and mounts the specific widget instance to the UI. +2. [Initialize SDK (Client-Side) ](../../../explore-Hyperswitch/payment-experience/payment-method/)The merchant client loads the `HyperLoader.js` script and initializes `window.Hyper` using the Publishable Key. Using the `session_id` and `client_secret`, the SDK creates a Payment Method Management (PMM) group and mounts the specific widget instance to the UI. 3. Collect and Vault Card (Client-Side) The customer enters their card details directly into the SDK-managed widget. Upon confirmation, the SDK calls the /`Confirm a payment method session` API. Hyperswitch securely receives the data, stores it in the Vault (retaining the CVV temporarily for the transaction TTL), and returns a success response with the `session_id` to the client. 4. Retrieve Payment Method ID (Server-Side) The merchant server calls the "List Payment Methods" API using the `session_id`. Hyperswitch returns a list of payment methods associated with the customer, from which the merchant server selects the appropriate `PM_ID` (Payment Method ID) to use for the transaction. 5. Execute Proxy Payment (Server-Side) The merchant server initiates the payment by sending a request to the @@ -160,7 +160,7 @@ Include the following details: "capture": true, "capture_on": "2019-09-10T10:11:12Z", }, - "destination_url": "https://api.sandbox.checkout.com/payments", + "destination_url": "https://api.sandbox.Checkout.com/payments", "headers": { "Content-Type": "application/json", "Authorization": "Bearer sk_sbox_3uu..." @@ -172,7 +172,7 @@ Include the following details: }' -#### Sample Response +### Sample Response ```bash { @@ -217,7 +217,7 @@ Include the following details: "retrieval_reference_number": "404030119279", "merchant_category_code": "5815", "scheme_merchant_id": "75155", - "scheme": "VISA", + "scheme": "Visa", "aft": false, "pan_type_processed": "fpan", "cko_network_token_available": false, @@ -226,16 +226,16 @@ Include the following details: "expires_on": "2025-06-20T10:10:42.7625936Z", "_links": { "self": { - "href": "https://api.sandbox.checkout.com/payments/pay_7f6x6vki25futmy54uot5c3ama" + "href": "https://api.sandbox.Checkout.com/payments/pay_7f6x6vki25futmy54uot5c3ama" }, "actions": { - "href": "https://api.sandbox.checkout.com/payments/pay_7f6x6vki25futmy54uot5c3ama/actions" + "href": "https://api.sandbox.Checkout.com/payments/pay_7f6x6vki25futmy54uot5c3ama/actions" }, "capture": { - "href": "https://api.sandbox.checkout.com/payments/pay_7f6x6vki25futmy54uot5c3ama/captures" + "href": "https://api.sandbox.Checkout.com/payments/pay_7f6x6vki25futmy54uot5c3ama/captures" }, "void": { - "href": "https://api.sandbox.checkout.com/payments/pay_7f6x6vki25futmy54uot5c3ama/voids" + "href": "https://api.sandbox.Checkout.com/payments/pay_7f6x6vki25futmy54uot5c3ama/voids" } } }, @@ -244,7 +244,7 @@ Include the following details: "date": "Wed, 21 May 2025 10:10:42 GMT", "cko-version": "1.1049.0+54597dfad", "strict-transport-security": "max-age=16000000; includeSubDomains; preload;", - "location": "https://api.sandbox.checkout.com/payments/pay_7f6x6vki25futmy54uot5c3ama", + "location": "https://api.sandbox.Checkout.com/payments/pay_7f6x6vki25futmy54uot5c3ama", "content-length": "1883", "content-type": "application/json; charset=utf-8", "connection": "keep-alive", diff --git a/about-hyperswitch/payment-suite-1/payment-method-management-sdk.md b/about-hyperswitch/payment-suite-1/payment-method-management-sdk.md index 5961053a..1f0aa83f 100644 --- a/about-hyperswitch/payment-suite-1/payment-method-management-sdk.md +++ b/about-hyperswitch/payment-suite-1/payment-method-management-sdk.md @@ -1,12 +1,13 @@ --- +description: >- + Integrate mobile SDK to deliver seamless in-app payment experiences hidden: true --- - # Payment Method Management SDK The Hyperswitch Payment Methods Management SDK provides a secure solution for merchants to handle and store payment information without the burden of PCI DSS compliance requirements. By leveraging Hyperswitch's Vault service, merchants can securely store customer payment methods (credit cards, digital wallets, etc.) while minimizing their exposure to sensitive payment data. -#### Why Integrate the Management SDK? +### Why Integrate the Management SDK? Hyperswitch simplifies the complexities of payment method management, so you can offer a seamless, secure experience to your customers with minimal effort. @@ -16,11 +17,9 @@ Hyperswitch simplifies the complexities of payment method management, so you can 4. **Deleting/Deactivating Payment Methods**: Keep payment options up to date by allowing customers to manage outdated or inactive methods, ensuring a clean and efficient payment experience. -
- **Integration Documentation :** -* [PMM SDK integration Guide](https://docs.hyperswitch.io/~/revisions/0suhZ1q0uwhOXBI31wWf/explore-hyperswitch/payments-modules/vault/payment-methods-management-sdk) +* [PMM SDK integration Guide](https://docs.hyperswitch.io/~/revisions/0suhZ1q0uwhOXBI31wWf/explore-Hyperswitch/payments-modules/vault/payment-methods-management-sdk) diff --git a/about-hyperswitch/payment-suite-1/payment-with-vault-flow/README.md b/about-hyperswitch/payment-suite-1/payment-with-vault-flow/README.md index 4f959f18..c3a29875 100644 --- a/about-hyperswitch/payment-suite-1/payment-with-vault-flow/README.md +++ b/about-hyperswitch/payment-suite-1/payment-with-vault-flow/README.md @@ -1,36 +1,37 @@ --- +description: >- + Implement secure vault solutions to protect sensitive payment card data hidden: true --- - # Payment with Vault Flow In the Payment with Vault flow setup, Hyperswitch acts as the central intelligence layer. You interact with a single unified API, and Hyperswitch manages the entire payment lifecycle across multiple processors. -#### How it Works +### How it Works 1. **Unified Request:** Your backend sends a generic payment request to the Hyperswitch API. 2. **Smart Routing:** The Hyperswitch Orchestrator evaluates your configured business rules (e.g., routing by volume, cost, or region). 3. **Execution:** Hyperswitch transforms the request into the specific format required by the target Connector (Stripe, Adyen, Braintree, etc.). 4. **State Management:** Hyperswitch maintains the payment state machine, handling webhooks, retries, and status updates automatically. -#### Technical Advantages +### Technical Advantages * **Abstracted Complexity:** You do not need to write or maintain processor-specific code. * **Dynamic Routing:** Switch traffic between processors in real-time via the Hyperswitch dashboard or during payment initiation API calls. * **Unified Reporting:** Transaction data across all processors is normalized into a single schema. * Every transaction is processed via a PSP and based on the API calls you can have - zero dollar validation, multi-stage manual capture, or sophisticated recurring logic payment flows. -#### Choose the Right Setup +### Choose the Right Setup Depending on your UI strategy and data sovereignty requirements, the Payment with Vault Flow offers multiple implementation patterns. Each option is designed to help you balance user experience, engineering complexity, and PCI compliance scope in a way that best fits your business. The four primary patterns are: -* [**Hyperswitch SDK + Hyperswitch Vault** ](https://docs.hyperswitch.io/~/revisions/gkH4cp2rB1DvMiW6aktj/about-hyperswitch/payment-suite-1/orchestrator-model/hyperswitch-sdk-+-hyperswitch-vault-setup)— _Unified Flow_:\ +* [**Hyperswitch SDK + Hyperswitch Vault** ](https://docs.hyperswitch.io/~/revisions/gkH4cp2rB1DvMiW6aktj/about-Hyperswitch/payment-suite-1/orchestrator-model/hyperswitch-sdk-+-Hyperswitch-vault-setup)— _Unified Flow_:\ The quickest path to launch, offering a fully integrated experience with zero PCI scope. -* [**Merchant SDK + Hyperswitch Vault**](https://docs.hyperswitch.io/~/revisions/Rp0vynFYJnlasuYRM3en/about-hyperswitch/payment-suite-1/orchestrator-model/merchant-sdk-+-hyperswitch-vault-setup) — _Headless Flow_:\ +* [**Merchant SDK + Hyperswitch Vault**](https://docs.hyperswitch.io/~/revisions/Rp0vynFYJnlasuYRM3en/about-Hyperswitch/payment-suite-1/orchestrator-model/merchant-sdk-+-Hyperswitch-vault-setup) — _Headless Flow_:\ Enables a fully custom UI while retaining secure vaulting, giving you greater control with added implementation effort. -* [**Hyperswitch SDK + External Vault**](https://docs.hyperswitch.io/~/revisions/Rp0vynFYJnlasuYRM3en/about-hyperswitch/payment-suite-1/orchestrator-model/hyperswitch-sdk-+-external-vault-setup) — _Hybrid Flow_:\ +* [**Hyperswitch SDK + External Vault**](https://docs.hyperswitch.io/~/revisions/Rp0vynFYJnlasuYRM3en/about-Hyperswitch/payment-suite-1/orchestrator-model/hyperswitch-sdk-+-external-vault-setup) — _Hybrid Flow_:\ Combines Hyperswitch-managed UI with third-party data storage for teams with specific vaulting requirements. -* [**External SDK + External Vault**](https://docs.hyperswitch.io/~/revisions/Rp0vynFYJnlasuYRM3en/about-hyperswitch/payment-suite-1/orchestrator-model/external-sdk-and-external-vault-setup) — _External Vault Flow_:\ +* [**External SDK + External Vault**](https://docs.hyperswitch.io/~/revisions/Rp0vynFYJnlasuYRM3en/about-Hyperswitch/payment-suite-1/orchestrator-model/external-sdk-and-external-vault-setup) — _External Vault Flow_:\ Provides maximum decoupling and flexibility, ideal for advanced setups that demand full control across the stack. diff --git a/about-hyperswitch/payment-suite-1/payment-with-vault-flow/hyperswitch-sdk-+-hyperswitch-vault-setup.md b/about-hyperswitch/payment-suite-1/payment-with-vault-flow/hyperswitch-sdk-+-hyperswitch-vault-setup.md index 77599931..e6cc9657 100644 --- a/about-hyperswitch/payment-suite-1/payment-with-vault-flow/hyperswitch-sdk-+-hyperswitch-vault-setup.md +++ b/about-hyperswitch/payment-suite-1/payment-with-vault-flow/hyperswitch-sdk-+-hyperswitch-vault-setup.md @@ -1,23 +1,21 @@ --- description: >- - Best for merchants seeking a pre-built, optimized payment UI backed by the + Set up Hyperswitch SDK Hyperswitch Vault to start processing payments quickly full Hyperswitch stack for secure data storage and routing. --- - # Hyperswitch SDK + Hyperswitch Vault Setup In this approach, the Hyperswitch SDK is used on the frontend to capture card details. Card data is securely sent to the Hyperswitch backend and stored in Hyperswitch Vault. Payment orchestration, routing, and connector logic are handled entirely by the Hyperswitch backend. The merchant uses the Hyperswitch Dashboard to configure connectors, routing rules, and orchestration logic. All payment requests are initiated using vault tokens, and raw card data never reaches merchant systems. Since card details are handled entirely by Hyperswitch, merchants are not required to be PCI DSS compliant for card data handling. -#### **Understanding Payment and Vault flow** +### **Understanding Payment and Vault flow** -#### **Vaulting :** +### **Vaulting :**
- **1. Create Payment (Server-Side)**\ The merchant server creates a payment by calling the Hyperswitch [`payments/create`](https://api-reference.hyperswitch.io/v1/payments/payments--create) API with transaction details such as amount and currency. Hyperswitch responds with a `payment_id` and `client_secret`, which are required for client-side processing. @@ -34,8 +32,7 @@ The SDK submits a `payments/confirm` request to Hyperswitch. Hyperswitch authori The final payment and vaulting status is returned to the SDK, which redirects the customer to the merchant’s configured `return_url`. - -#### **Payment Using Stored Card :** +### **Payment Using Stored Card :**
@@ -55,11 +52,8 @@ The SDK sends a `payments/confirm` request with the selected `payment_method_id` The processor returns the authorization result to Hyperswitch, which forwards the final status to the SDK. The customer is redirected to the merchant’s `return_url` with the payment outcome. - - - * **Integration Documentation :** - * **Unified Checkout :**[ Integration guide](https://docs.hyperswitch.io/explore-hyperswitch/merchant-controls/integration-guide) + * **Unified Checkout :**[ Integration guide](https://docs.hyperswitch.io/explore-Hyperswitch/merchant-controls/integration-guide) * [Create Payment API](https://api-reference.hyperswitch.io/v1/payments/payments--create) - * [ Unified Checkout: Saving Payment Methods](https://docs.hyperswitch.io/explore-hyperswitch/payment-orchestration/quickstart/tokenization-and-saved-cards/save-a-payment-method) + * [ Unified Checkout: Saving Payment Methods](https://docs.hyperswitch.io/explore-Hyperswitch/payment-orchestration/quickstart/tokenization-and-saved-cards/save-a-payment-method) diff --git a/about-hyperswitch/payment-suite-1/payment-with-vault-flow/merchant-sdk-+-hyperswitch-vault-setup.md b/about-hyperswitch/payment-suite-1/payment-with-vault-flow/merchant-sdk-+-hyperswitch-vault-setup.md index 25fa5123..1900eab3 100644 --- a/about-hyperswitch/payment-suite-1/payment-with-vault-flow/merchant-sdk-+-hyperswitch-vault-setup.md +++ b/about-hyperswitch/payment-suite-1/payment-with-vault-flow/merchant-sdk-+-hyperswitch-vault-setup.md @@ -1,23 +1,21 @@ --- description: >- - Best for PCI compliant merchants requiring full control over UI rendering + Set up Merchant SDK Hyperswitch Vault to start processing payments quickly while leveraging Hyperswitch Vault for secure storage and payment routing. --- - # Merchant SDK + Hyperswitch Vault Setup In this approach, the merchant uses their own frontend SDK to capture card details. Card data is sent to Hyperswitch backend and stored in Hyperswitch Vault. The merchant must ensure PCI DSS compliance for card capture. Once tokenized, Hyperswitch backend handles orchestration, routing, retries, and connector execution using vault tokens. All orchestration configuration is managed through the Hyperswitch Dashboard. -#### Understanding Payment and Vault Workflow +### Understanding Payment and Vault Workflow -#### **Vaulting :** +### **Vaulting :**
- **1. Create Payment (Server-Side)** The merchant server calls the Hyperswitch `p`[`ayments/create`](https://api-reference.hyperswitch.io/v1/payments/payments--create) API with details such as `customer_id`, `amount`, `currency`, and `api_key`. Hyperswitch responds with a `payment_id` and other metadata required to proceed. @@ -47,8 +45,7 @@ After successful authorization, Hyperswitch securely stores the card data in the Hyperswitch sends the final payment response, including transaction status and the vaulted `payment_method_id`, back to the merchant server. - -#### **Payment Using Stored Card :** +### **Payment Using Stored Card :**
@@ -83,7 +80,6 @@ The Hyperswitch Connector handles the synchronous handshake with the external pr The Hyperswitch Server sends the final transaction state (e.g., `succeeded`, `failed`) to Merchant Server. This allows the backend to update the order status while the frontend notifies the user of the successful payment. - **API Reference :** 1. [Payment Create API ](https://api-reference.hyperswitch.io/v1/payments/payments--create) diff --git a/about-hyperswitch/payment-suite-1/payments-cards/copy-of-subscriptions.md b/about-hyperswitch/payment-suite-1/payments-cards/copy-of-subscriptions.md index 3d48376c..8615cee8 100644 --- a/about-hyperswitch/payment-suite-1/payments-cards/copy-of-subscriptions.md +++ b/about-hyperswitch/payment-suite-1/payments-cards/copy-of-subscriptions.md @@ -1,9 +1,9 @@ --- -description: Augment your subscriptions with payments orchestration capabilities +description: >- + Set up subscription payments to enable recurring billing for your customers hidden: true icon: arrows-rotate-reverse --- - # Copy of Subscriptions Businesses that run on subscription model powered by providers viz. Chargebee, Recurly, Stripe Billing etc. can now augment it with payments orchestration by decoupling the payments from the subscription provider and using them purely for subscription ledger and scheduling, while owning 100% of the card vaulting, payment attempts, and retry logic (owned in-house, or via an ensemble of specialized payment-focused orchestrator and other focused third parties, modularized to work with each other) @@ -25,23 +25,23 @@ Businesses that run on subscription model powered by providers viz. Chargebee, R 5. Subscription is created at Hyperswitch and at the subscription provider's end 6. First invoice is marked as paid and the subscription is activated 7. Subsequent billing cycles are handled independently by Hyperswitch through MIT payments -8. Failed MIT payments can be smartly retries by Hyperswitch ([read more](../../../explore-hyperswitch/payments-modules/revenue-recovery.md)) or by the solution provider of your choice. +8. Failed MIT payments can be smartly retries by Hyperswitch ([read more](../../../explore-Hyperswitch/payments-modules/revenue-recovery.md)) or by the solution provider of your choice. ### Flow Diagram -#### Initial Subscription create flow (with CIT Payment) +### Initial Subscription create flow (with CIT Payment)
-#### MIT payment flow in subsequent billing cycle +### MIT payment flow in subsequent billing cycle
### Integration Guide -#### 1. For non-PCI compliant merchants who wants to use Hyperswitch Payments SDK +### 1. For non-PCI DSS compliant merchants who wants to use Hyperswitch Payments SDK -#### Initial Subscription create flow (with CIT Payment) +### Initial Subscription create flow (with CIT Payment) {% stepper %} {% step %} @@ -66,8 +66,8 @@ curl --location 'http:///account//connectors' \ "business_country": "US", "business_label": "default", "connector_webhook_details": { - "merchant_secret": "hyperswitch", - "additional_secret": "hyperswitch" + "merchant_secret": "Hyperswitch", + "additional_secret": "Hyperswitch" }, "metadata": { "site": "test" @@ -154,7 +154,7 @@ When setting up subscription there are two distinct implementation flows. The correct flow depends on whether you intend to charge the customer immediately or simply validate their details for later use. -#### 1. The Setup with Charge Flow +### 1. The Setup with Charge Flow **Use Case:** Use this when you need to collect a payment immediately (e.g., the first month of a subscription or a setup fee) while simultaneously saving the card details for future automatic charges. @@ -164,16 +164,14 @@ The correct flow depends on whether you intend to charge the customer immediatel * `amount > 0` - -#### 2. The Zero Dollar Authorization Flow +### 2. The Zero Dollar Authorization Flow **Use Case:** Use this for free trials, pay-later models, or delayed billing. This flow validates the payment method details without charging the customer's card. - **Configuration Parameters :** -* Pass below parameters while calling payments API for [Zero Dollar Auth ](https://docs.hyperswitch.io/explore-hyperswitch/payment-orchestration/quickstart/tokenization-and-saved-cards/zero-amount-authorization-1) +* Pass below parameters while calling payments API for [Zero Dollar Auth ](https://docs.hyperswitch.io/explore-Hyperswitch/payment-orchestration/quickstart/tokenization-and-saved-cards/zero-amount-authorization-1) * `setup_future_usage: "off_session"` * `amount: 0` * `payment_type: "setup_mandate"` @@ -181,7 +179,7 @@ The correct flow depends on whether you intend to charge the customer immediatel {% endstep %} {% step %} -Once the customer selects a payment method and enters the details and confirms the subscription, hit the `/subscriptions/:id/confirm` using a similar [implementation as this](../../../explore-hyperswitch/payment-experience/payment/web/react-with-rest-api-integration.md) +Once the customer selects a payment method and enters the details and confirms the subscription, hit the `/subscriptions/:id/confirm` using a similar [implementation as this](../../../explore-Hyperswitch/payment-experience/payment/web/react-with-rest-api-integration.md) {% endstep %} {% step %} @@ -190,8 +188,7 @@ Sync with the subscription status for disbursement of services and future billin {% endstepper %} - -#### 2. For PCI Compliant merchants handling the entire checkout experience +### 2. For PCI DSS compliant merchants handling the entire checkout experience {% stepper %} {% step %} @@ -210,7 +207,7 @@ When setting up subscription there are two distinct implementation flows. The correct flow depends on whether you intend to charge the customer immediately or simply validate their details for later use. -#### 1. The Setup with Charge Flow +### 1. The Setup with Charge Flow **Use Case:** Use this when you need to collect a payment immediately (e.g., the first month of a subscription or a setup fee) while simultaneously saving the card details for future automatic charges. @@ -220,16 +217,14 @@ The correct flow depends on whether you intend to charge the customer immediatel * `amount > 0` - -#### 2. The Zero Dollar Authorization Flow +### 2. The Zero Dollar Authorization Flow **Use Case:** Use this for free trials, pay-later models, or delayed billing. This flow validates the payment method details without charging the customer's card. - **Configuration Parameters :** -* Pass below parameters while calling payments API for [Zero Dollar Auth ](https://docs.hyperswitch.io/explore-hyperswitch/payment-orchestration/quickstart/tokenization-and-saved-cards/zero-amount-authorization-1) +* Pass below parameters while calling payments API for [Zero Dollar Auth ](https://docs.hyperswitch.io/explore-Hyperswitch/payment-orchestration/quickstart/tokenization-and-saved-cards/zero-amount-authorization-1) * `setup_future_usage: "off_session"` * `amount: 0` * `payment_type: "setup_mandate"` @@ -364,10 +359,10 @@ MITs are initiated by invoking the [`/payments`](https://api-reference.hyperswit ### FAQs -#### 1. What are subscriptions providers that are currently supported? +### 1. What are subscriptions providers that are currently supported? Currently we support Chargebee integration. In the upcoming roadmap we are planning to extend support for Recurly, Stripe Billing and Zuora -#### 2. Can the entire experience from plan display, price estimation to payments be handled by Hyperswitch SDK? +### 2. Can the entire experience from plan display, price estimation to payments be handled by Hyperswitch SDK? We are planning to release a Hyperswitch Subscriptions SDK that will take care of the end-to-end experience. diff --git a/about-hyperswitch/payment-suite-1/payments-cards/manual-capture/README.md b/about-hyperswitch/payment-suite-1/payments-cards/manual-capture/README.md index 2dfa4dc6..332fbd64 100644 --- a/about-hyperswitch/payment-suite-1/payments-cards/manual-capture/README.md +++ b/about-hyperswitch/payment-suite-1/payments-cards/manual-capture/README.md @@ -1,10 +1,9 @@ --- description: >- - Understand how to place a hold on your customers' funds and capture them later + Explore Manual Capture to enhance your payment orchestration capabilities either fully or partially and either in one-go or multiple times icon: transmission --- - # Manual Capture {% embed url="https://youtu.be/XtOMZVhvLwQ" %} @@ -21,7 +20,7 @@ But in some cases, merchants would like to place a hold on the customer's funds ### How to do Manual Capture? -#### Step 1 — Create [Payment](https://api-reference.hyperswitch.io/v1/payments/payments--create) with Deferred Capture +### Step 1 — Create [Payment](https://api-reference.hyperswitch.io/v1/payments/payments--create) with Deferred Capture The 'capture\_method' field determines the type of capture for a particular payment and it defaults to 'automatic' if not passed. So, to do manual capture, set `"capture_method" = "manual"` when creating a payment from your server @@ -54,7 +53,7 @@ curl --location 'https://sandbox.hyperswitch.io/payments' \ }' ``` -#### Step 2 — Confirm (Authorization Phase) +### Step 2 — Confirm (Authorization Phase) [Confirm](https://api-reference.hyperswitch.io/v1/payments/payments--confirm) the payment after collecting the payment\_method details from your customer and informing them that the funds in their account would be blocked and charged later once the goods and services are delivered. Unified checkout handles this for automatically. On successful authorization, the payment would transition to `'requires_capture'` status. @@ -82,7 +81,7 @@ curl --location 'https://sandbox.hyperswitch.io/payments//c }' ``` -#### Step 3 — Capture Funds via [Capture API](https://api-reference.hyperswitch.io/v1/payments/payments--capture#payments-capture) +### Step 3 — Capture Funds via [Capture API](https://api-reference.hyperswitch.io/v1/payments/payments--capture#payments-capture) After delivering the goods and services, capture the payment by passing the `payment_id` from above step to `payments/capture` API endpoint. On successful capture, the payment would transition from `'requires_capture'` to `'succeeded'` status. @@ -102,25 +101,18 @@ curl --location 'https://sandbox.hyperswitch.io/payments/pay_At7O43TJJZyP7OmrcdQ ### Capture types available : -#### **Full capture** +### **Full capture** Capture the full amount that was authorized - Here the payments status transitions to 'SUCCEEDED' as soon the `payments/capture` API endpoint is executed for the `payment_id` . -#### **Partial Capture** +### **Partial Capture** Capture only a partial amount from the total amount that was authorized. Once the transaction is executed, the status goes to either `partially_captured` or `partially_captured_and_capturable` 1. When capture method is manual & single capture is supported - `partially_captured` 2. When capture method is manual & multiple captures are supported - `partially_captured_and_capturable`
-Possible states: - -| Connector Capability | Resulting Status | -| -------------------------- | ----------------------------------- | -| Single capture only | `partially_captured` | -| Multiple capture supported | `partially_captured_and_capturable` | - -#### Over Capture +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) +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) diff --git a/about-hyperswitch/payment-suite-1/payments-cards/saved-card/README.md b/about-hyperswitch/payment-suite-1/payments-cards/saved-card/README.md index 15d9afd3..adaa0b96 100644 --- a/about-hyperswitch/payment-suite-1/payments-cards/saved-card/README.md +++ b/about-hyperswitch/payment-suite-1/payments-cards/saved-card/README.md @@ -1,7 +1,8 @@ --- +description: >- + Explore Saved Card to enhance your payment orchestration capabilities icon: hard-drive --- - # Saved Card In this approach, the Hyperswitch SDK is used on the frontend to capture card details. Card data is securely sent to the Hyperswitch backend and stored in Hyperswitch Vault. Payment orchestration, routing, and connector logic are handled entirely by the Hyperswitch backend. @@ -13,8 +14,7 @@ The merchant uses the Hyperswitch Dashboard to configure connectors, routing rul
- -#### **1. Create Payment (Server-Side)** +### **1. Create Payment (Server-Side)** The merchant server creates a payment by calling the Hyperswitch [`payments/create`](https://api-reference.hyperswitch.io/v1/payments/payments--create) API with transaction details such as amount and currency. Hyperswitch responds with a `payment_id` , `customer_id` and `client_secret`, which are required for client-side processing. @@ -29,7 +29,7 @@ curl --location 'https://sandbox.hyperswitch.io/payments' \ "profile_id": , "customer_id": "customer123", "description": "Its my first payment request", - "return_url": "https://example.com", // + "return_url": "https://example.com", // }' ``` @@ -37,7 +37,7 @@ curl --location 'https://sandbox.hyperswitch.io/payments' \ Note - In case the merchant does not pass the customer ID, then the transaction is treated as a Guest customer checkout {% endhint %} -#### **2. Initialize SDK (Client-Side)** +### **2. Initialize SDK (Client-Side)** The merchant client initializes the Hyperswitch SDK using the `client_secret` and `publishable_key`. The SDK fetches eligible payment methods from Hyperswitch and renders a secure payment UI. @@ -50,13 +50,13 @@ async function initialize() { body: JSON.stringify({currency: "USD",amount: 100}), }); const { clientSecret } = await response.json(); - + // Initialise Hyperloader.js var script = document.createElement('script'); script.type = 'text/javascript'; script.src = "https://beta.hyperswitch.io/v1/HyperLoader.js"; - - let hyper; + + let hyper; script.onload = () => { hyper = window.Hyper("YOUR_PUBLISHABLE_KEY",{ customBackendUrl: "YOUR_BACKEND_URL", @@ -70,7 +70,7 @@ async function initialize() { layout: "tabs", wallets: { walletReturnUrl: "https://example.com/complete", - //Mandatory parameter for Wallet Flows such as Googlepay, Paypal and Applepay + //Mandatory parameter for Wallet Flows such as Google Pay, PayPal and Apple Pay }, }; const unifiedCheckout = widgets.create("payment", unifiedCheckoutOptions); @@ -80,15 +80,15 @@ async function initialize() { } ``` -#### **3. Collect Card Details** +### **3. Collect Card Details** The customer selects a card payment method and enters their card details directly within the SDK-managed interface, ensuring sensitive data never passes through merchant systems. -#### **4. Authorize and Store Card** +### **4. Authorize and Store Card** The SDK submits a [`payments/confirm`](https://api-reference.hyperswitch.io/v1/payments/payments--confirm) request to Hyperswitch. Hyperswitch authorizes the payment with the processor and securely stores the card in the Hyperswitch Vault, generating a reusable `payment_method_id`. -#### **5. Return Status** +### **5. Return Status** The final payment and vaulting status is returned to the SDK, which redirects the customer to the merchant’s configured `return_url`. @@ -96,7 +96,7 @@ The final payment and vaulting status is returned to the SDK, which redirects th
-#### **1. Create Payment (Server-Side)** +### **1. Create Payment (Server-Side)** The merchant server initiates the payment by calling the [`payments/create`](https://api-reference.hyperswitch.io/v1/payments/payments--create) API with transaction details such as amount and currency. Hyperswitch responds with a `payment_id` , `customer_id` and `client_secret`, which are required for client-side processing. @@ -111,7 +111,7 @@ curl --location 'https://sandbox.hyperswitch.io/payments' \ "profile_id": , "customer_id": "customer123", "description": "Its my first payment request", - "return_url": "https://example.com", // + "return_url": "https://example.com", // }' ``` @@ -121,7 +121,7 @@ Note -The merchant needs to pass the same customer ID for the SDK to fetch the s In case the merhcnat is not using the SDK then they need to use the List Customer Saved Payment Methods API to fetch th stored payment methods against a customer {% endhint %} -#### **2. Initialize SDK and Fetch Saved Cards** +### **2. Initialize SDK and Fetch Saved Cards** The merchant client initializes the Hyperswitch SDK. The SDK requests eligible payment methods from Hyperswitch, including any saved cards associated with the customer. @@ -134,13 +134,13 @@ async function initialize() { body: JSON.stringify({currency: "USD",amount: 100}), }); const { clientSecret } = await response.json(); - + // Initialise Hyperloader.js var script = document.createElement('script'); script.type = 'text/javascript'; script.src = "https://beta.hyperswitch.io/v1/HyperLoader.js"; - - let hyper; + + let hyper; script.onload = () => { hyper = window.Hyper("YOUR_PUBLISHABLE_KEY",{ customBackendUrl: "YOUR_BACKEND_URL", @@ -154,7 +154,7 @@ async function initialize() { layout: "tabs", wallets: { walletReturnUrl: "https://example.com/complete", - //Mandatory parameter for Wallet Flows such as Googlepay, Paypal and Applepay + //Mandatory parameter for Wallet Flows such as Google Pay, PayPal and Apple Pay }, }; const unifiedCheckout = widgets.create("payment", unifiedCheckoutOptions); @@ -164,22 +164,21 @@ async function initialize() { } ``` -#### **3. Customer Selects a Saved Card** +### **3. Customer Selects a Saved Card** The SDK displays the saved cards in the payment UI, customer enters the CVV. -#### **4. Retrieve Card Data and Authorize** +### **4. Retrieve Card Data and Authorize** The SDK sends a [`payments/confirm`](https://api-reference.hyperswitch.io/v1/payments/payments--confirm) request with the selected `payment_method_id`. Hyperswitch securely retrieves the card data from the Hyperswitch Vault and submits the authorization request to the processor via the Hyperswitch Connector. -#### **5. Return Status** +### **5. Return Status** The processor returns the authorization result to Hyperswitch, which forwards the final status to the SDK. The customer is redirected to the merchant’s `return_url` with the payment outcome. +### Integration Guide : -#### Integration Guide : - -[Unified Checkout ](https://docs.hyperswitch.io/~/revisions/DXTxY8PvOykOfdbFcGmW/explore-hyperswitch/payment-experience/payment/web) +[Unified Checkout ](https://docs.hyperswitch.io/~/revisions/DXTxY8PvOykOfdbFcGmW/explore-Hyperswitch/payment-experience/payment/web) [Payments API](https://api-reference.hyperswitch.io/v1/payments/payments--create) diff --git a/about-hyperswitch/payment-suite-1/payments-cards/saved-card/save-a-payment-method.md b/about-hyperswitch/payment-suite-1/payments-cards/saved-card/save-a-payment-method.md index 00f39103..59c55c7d 100644 --- a/about-hyperswitch/payment-suite-1/payments-cards/saved-card/save-a-payment-method.md +++ b/about-hyperswitch/payment-suite-1/payments-cards/saved-card/save-a-payment-method.md @@ -1,8 +1,8 @@ --- -description: Setting up and managing recurring payments +description: >- + Explore Use cases for Saved card to enhance your payment orchestration capabilities icon: repeat --- - # Use cases for Saved card Hyperswitch supports the following ways of saving a payment method used in a successful payment: @@ -31,10 +31,10 @@ curl --location 'https://sandbox.hyperswitch.io/payments' \ "amount": 6540, "currency": "USD", "profile_id": , - "setup_future_usage":"on_session", + "setup_future_usage":"on_session", "customer_id": "customer123", "description": "Its my first payment request", - "return_url": "https://example.com", // + "return_url": "https://example.com", // }' ``` @@ -80,10 +80,10 @@ curl --location 'https://sandbox.hyperswitch.io/payments' \ "amount": 6540, "currency": "USD", "profile_id": , - "setup_future_usage":"off_session", + "setup_future_usage":"off_session", "customer_id": "customer123", "description": "Its my first payment request", - "return_url": "https://example.com", // + "return_url": "https://example.com", // }' ``` diff --git a/about-hyperswitch/payment-suite-1/payments/README.md b/about-hyperswitch/payment-suite-1/payments/README.md index d68a95a0..aa8f1256 100644 --- a/about-hyperswitch/payment-suite-1/payments/README.md +++ b/about-hyperswitch/payment-suite-1/payments/README.md @@ -1,7 +1,8 @@ --- +description: >- + Explore Payments cards to enhance your payment orchestration capabilities icon: file-invoice-dollar --- - # Payments (cards) Hyperswitch provides flexible payment processing with multiple flow patterns to accommodate different business needs. The system supports one-time payments, saved payment methods, and recurring billing through a comprehensive API design. @@ -9,7 +10,7 @@ Hyperswitch provides flexible payment processing with multiple flow patterns to {% hint style="info" %} ### Integration Path -#### Client-Side SDK Payments (Tokenise Post Payment) +### Client-Side SDK Payments (Tokenise Post Payment) Refer to Payments (Cards) section if your flow requires the SDK to initiate payments directly. In this model, the SDK handles the payment trigger and communicates downstream to the Hyperswitch server and your chosen Payment Service Providers (PSPs). This path is ideal for supporting dynamic, frontend-driven payment experiences. {% endhint %} @@ -18,7 +19,7 @@ Refer to Payments (Cards) section if your flow requires the SDK to initiate pay ### One-Time Payment Patterns -#### 1. Instant Payment (Automatic Capture) +### 1. Instant Payment (Automatic Capture) **Use Case:** Simple, immediate payment processing @@ -34,7 +35,7 @@ Refer to Payments (Cards) section if your flow requires the SDK to initiate pay **Final Status:** `succeeded` -#### 2. Two-Step Manual Capture +### 2. Two-Step Manual Capture **Use Case:** Deferred capture (e.g., ship before charging) @@ -47,9 +48,9 @@ Refer to Payments (Cards) section if your flow requires the SDK to initiate pay 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) +Read more - [here](https://docs.hyperswitch.io/~/revisions/2M8ySHqN3pH3rctBK2zj/about-Hyperswitch/payment-suite-1/payments-cards/manual-capture) -#### 3. Fully Decoupled Flow +### 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. @@ -62,7 +63,7 @@ Read more - [here](https://docs.hyperswitch.io/~/revisions/2M8ySHqN3pH3rctBK2zj/ * **Confirm:** `POST /payments/{payment_id}/confirm` * **Capture:** `POST /payments/{payment_id}/capture` (if manual) -#### 4. 3D Secure Authentication Flow +### 4. 3D Secure Authentication Flow **Use Case:** Enhanced security with customer authentication @@ -74,11 +75,11 @@ Read more - [here](https://docs.hyperswitch.io/~/revisions/2M8ySHqN3pH3rctBK2zj/ **Status Progression:** `processing` → `requires_customer_action` → `succeeded` -Read more - [link](https://docs.hyperswitch.io/~/revisions/9QlGypixZFcbkq8oGjaF/explore-hyperswitch/workflows/3ds-decision-manager) +Read more - [link](https://docs.hyperswitch.io/~/revisions/9QlGypixZFcbkq8oGjaF/explore-Hyperswitch/workflows/3ds-decision-manager) ### Recurring payments and Payment storage -#### 1. Saving Payment Methods +### 1. Saving Payment Methods **During Payment Creation:** @@ -91,7 +92,7 @@ Read more - [link](https://docs.hyperswitch.io/~/revisions/9QlGypixZFcbkq8oGjaF/ * **`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 +### 2. Using Saved Payment Methods
@@ -101,23 +102,23 @@ Read more - [link](https://docs.hyperswitch.io/~/revisions/9QlGypixZFcbkq8oGjaF/ 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` +### 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 +### 3. Customer-Initiated Transaction (CIT) Setup
-Read more - [link](https://docs.hyperswitch.io/~/revisions/j00Urtz9MpwPggJzRCsi/about-hyperswitch/payment-suite-1/payments-cards/recurring-payments) +Read more - [link](https://docs.hyperswitch.io/~/revisions/j00Urtz9MpwPggJzRCsi/about-Hyperswitch/payment-suite-1/payments-cards/recurring-payments) -#### 4. Merchant-Initiated Transaction (MIT) Execution +### 4. Merchant-Initiated Transaction (MIT) Execution
-Read more - [link](https://docs.hyperswitch.io/~/revisions/j00Urtz9MpwPggJzRCsi/about-hyperswitch/payment-suite-1/payments-cards/recurring-payments) +Read more - [link](https://docs.hyperswitch.io/~/revisions/j00Urtz9MpwPggJzRCsi/about-Hyperswitch/payment-suite-1/payments-cards/recurring-payments) ### Status Flow Summary diff --git a/about-hyperswitch/payment-suite-1/s2s-vault-flow.md b/about-hyperswitch/payment-suite-1/s2s-vault-flow.md index 1db46a2f..13a7e639 100644 --- a/about-hyperswitch/payment-suite-1/s2s-vault-flow.md +++ b/about-hyperswitch/payment-suite-1/s2s-vault-flow.md @@ -1,52 +1,48 @@ --- description: >- - Best for PCI compliant merchants who wants to store the card during initial - checkout phase without charging their customers. + Implement secure vault solutions to protect sensitive payment card data hidden: true --- - # S2S Vault flow The Payment method SDK allows you to securely collect payment information and give customers the option to save their payment details for future transactions. By vaulting these details during the initial checkout phase. -#### **Key Features** - -* **Full Token Management** – Create, retrieve, update, and delete payment tokens directly from your server. -* **PSP and Network Tokenization** – Generate both PSP tokens and network tokens through a single API. -* **Secure Storage** – Store tokens safely in Hyperswitch’s Vault. -* **Reduced Frontend Complexity** – Shift tokenization processes to the backend, minimizing frontend dependencies. - -#### Understanding Payment and Vault Flow +## Key Features +- **Full Token Management** – Create, retrieve, update, and delete payment tokens directly from your server. +- **PSP and Network Tokenization** – Generate both PSP tokens and network tokens through a single API. +- **Secure Storage** – Store tokens safely in Hyperswitch's Vault. +- **Reduced Frontend Complexity** – Shift tokenization processes to the backend, minimizing frontend dependencies. +## Understanding Payment and Vault Flow
-#### **Vaulting :** +### Vaulting -**1. Create Customer (Server-Side)** +### 1. Create Customer (Server-Side) Your server begins by calling the Hyperswitch [`/v2/customers`](https://api-reference.hyperswitch.io/v1/customers/customers--create) API to register the customer. Hyperswitch creates a profile and returns a unique `customer_id` that will be associated with the payment method. -**2. Collect Card Details** +### 2. Collect Card Details The customer enters their card details directly into your application's checkout interface. In this server-side flow, your system initially captures the raw card data before securely forwarding it to Hyperswitch. -**3. Create Payment Method (Server-Side)** +### 3. Create Payment Method (Server-Side) Your server makes a [`/v2/payment-methods`](https://api-reference.hyperswitch.io/v1/payment-methods/paymentmethods--create) request to Hyperswitch, passing the collected raw card data along with the `customer_id` generated in step 1. -**4. Vault and Tokenize** +### 4. Vault and Tokenize - Hyperswitch receives the request, securely stores the raw card data in the Vault, and generates a secure token. If PSP or Network tokenization is enabled, Hyperswitch automatically communicates with the external provider to retrieve a token and maps it to payment method ID. +Hyperswitch receives the request, securely stores the raw card data in the Vault, and generates a secure token. If PSP or Network tokenization is enabled, Hyperswitch automatically communicates with the external provider to retrieve a token and maps it to payment method ID. -**5. Return Payment Credentials** +### 5. Return Payment Credentials Hyperswitch returns the `payment_method_id` in the response. You can use this payment method ID for future payments for this customer without handling sensitive card data again. -#### **Payment :** +### Payment -To charge the customer you will will have to call the [create and confirm](https://api-reference.hyperswitch.io/v2/payments/payments--create-and-confirm-intent) API and pass the `payment_method_id` along with `confirm` as `true` +To charge the customer you will have to call the [create and confirm](https://api-reference.hyperswitch.io/v2/payments/payments--create-and-confirm-intent) API and pass the `payment_method_id` along with `confirm` as `true`. {% hint style="info" %} All Vault API (V2) requests require authentication using specific API keys generated from your Vault Merchant account. These keys are distinct from your standard payment processing keys. @@ -59,8 +55,8 @@ To generate your Vault API keys, follow these steps: 4. **Secure Storage:** Copy the generated key and store it securely. You must use this key to authenticate all Vault API (V2) calls. {% endhint %} -**Integration Documentation -** +**Integration Documentation:** -* [S2S Vault Tokenization](https://docs.hyperswitch.io/~/revisions/TGn71uwTlQJmyyiYgHpt/explore-hyperswitch/payments-modules/vault/server-to-server-vault-tokenization) -* [Create Payment API](https://api-reference.hyperswitch.io/v1/payments/payments--create) -* [Payment Create and Confirm API](https://api-reference.hyperswitch.io/v2/payments/payments--create-and-confirm-intent) +- [S2S Vault Tokenization](https://docs.hyperswitch.io/~/revisions/TGn71uwTlQJmyyiYgHpt/explore-Hyperswitch/payments-modules/vault/server-to-server-vault-tokenization) +- [Create Payment API](https://api-reference.hyperswitch.io/v1/payments/payments--create) +- [Payment Create and Confirm API](https://api-reference.hyperswitch.io/v2/payments/payments--create-and-confirm-intent) diff --git a/about-hyperswitch/payment-suite-1/vault-and-forward.md b/about-hyperswitch/payment-suite-1/vault-and-forward.md index b602c67e..944ff92a 100644 --- a/about-hyperswitch/payment-suite-1/vault-and-forward.md +++ b/about-hyperswitch/payment-suite-1/vault-and-forward.md @@ -1,10 +1,8 @@ --- description: >- - Best for merchants who do not want to handle card data and want to maintain - their current integration with the processors. + Implement secure vault solutions to protect sensitive payment card data hidden: true --- - # Vault and Forward In this approach, the Direct Payment Control Model functions by treating Hyperswitch as a secure "pipe." This setup grants you full control over your orchestration logic and the specific API calls sent to processors. The process initiates when the customer enters payment details into the Hyperswitch Vault SDK, where the data is directly tokenized within the Hyperswitch Vault. @@ -13,31 +11,30 @@ For payments, your backend constructs a request intended for your specific proce This architecture allows you to maintain your legacy backend logic while significantly reducing PCI scope. It is particularly well-suited for scenarios where you plan to keep existing processor integrations. but require the removal of sensitive card data from your internal systems. -#### **Understanding Payment and Vault Flow** +## Understanding Payment and Vault Flow
+### Vaulting +### 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#payment-method-session-create) API with the `customer_id`. Hyperswitch responds with a `session_id` and `client_secret`, which are required to authenticate the client-side session. -#### Vaulting - -**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#payment-method-session-create) API with the `customer_id`. Hyperswitch responds with a `session_id` and `client_secret`, which are required to authenticate the client-side session. - -**2. Initialize SDK (Client-Side)** The merchant client loads the `HyperLoader.js` script and initializes `window.Hyper` using the Publishable Key. Using the `session_id` and `client_secret`, the SDK creates a Payment Method Management (PMM) group and mounts the specific widget instance to the UI. - -**3. Collect and Vault Card (Client-Side)** The customer enters their card details directly into the SDK-managed widget. Upon confirmation, the SDK calls the /`Confirm a payment method session` API. Hyperswitch securely receives the data, stores it in the Vault (retaining the CVV temporarily for the transaction TTL), and returns a success response with the `session_id` to the client. - -**4. Retrieve Payment Method ID (Server-Side)** The merchant server calls the "List Payment Methods" API using the `session_id`. Hyperswitch returns a list of payment methods associated with the customer, from which the merchant server selects the appropriate `PM_ID` (Payment Method ID) to use for the transaction. - - +### 2. Initialize SDK (Client-Side) +The merchant client loads the `HyperLoader.js` script and initializes `window.Hyper` using the Publishable Key. Using the `session_id` and `client_secret`, the SDK creates a Payment Method Management (PMM) group and mounts the specific widget instance to the UI. -#### Payment +### 3. Collect and Vault Card (Client-Side) +The customer enters their card details directly into the SDK-managed widget. Upon confirmation, the SDK calls the /`Confirm a payment method session` API. Hyperswitch securely receives the data, stores it in the Vault (retaining the CVV temporarily for the transaction TTL), and returns a success response with the `session_id` to the client. -**Execute Proxy Payment (Server-Side)** The merchant server initiates the payment by sending a request to the [Hyperswitch vault proxy](https://docs.hyperswitch.io/~/revisions/01bZ2maqjwpnmrttix7i/explore-hyperswitch/payments-modules/vault/hyperswitch-vault-pass-through-proxy-payments) endpoint using the `payment_method_id` . The proxy securely replaces the token with the actual card data from the Vault and forwards the request to the Payment Service Provider (PSP), returning the final payment response to the merchant. +### 4. Retrieve Payment Method ID (Server-Side) +The merchant server calls the "List Payment Methods" API using the `session_id`. Hyperswitch returns a list of payment methods associated with the customer, from which the merchant server selects the appropriate `PM_ID` (Payment Method ID) to use for the transaction. +### Payment +### Execute Proxy Payment (Server-Side) +The merchant server initiates the payment by sending a request to the [Hyperswitch vault proxy](https://docs.hyperswitch.io/~/revisions/01bZ2maqjwpnmrttix7i/explore-Hyperswitch/payments-modules/vault/hyperswitch-vault-pass-through-proxy-payments) endpoint using the `payment_method_id` . The proxy securely replaces the token with the actual card data from the Vault and forwards the request to the Payment Service Provider (PSP), returning the final payment response to the merchant. -**Integration Documetation :** +## Integration Documetation -* [Vault SDK Integration](https://docs.hyperswitch.io/~/revisions/TGn71uwTlQJmyyiYgHpt/explore-hyperswitch/payments-modules/vault/vault-sdk-integration) -* [Proxy Payment Integration Guide](https://docs.hyperswitch.io/~/revisions/01bZ2maqjwpnmrttix7i/explore-hyperswitch/payments-modules/vault/hyperswitch-vault-pass-through-proxy-payments) +* [Vault SDK Integration](https://docs.hyperswitch.io/~/revisions/TGn71uwTlQJmyyiYgHpt/explore-Hyperswitch/payments-modules/vault/vault-sdk-integration) +* [Proxy Payment Integration Guide](https://docs.hyperswitch.io/~/revisions/01bZ2maqjwpnmrttix7i/explore-Hyperswitch/payments-modules/vault/hyperswitch-vault-pass-through-proxy-payments)