> For the complete documentation index, see [llms.txt](https://docs.hyperswitch.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hyperswitch.io/integration-guide/workflows/vault/deployment-models/self-hosted-orchestration-with-external-or-third-party-pci-vault.md).

# Self-hosted & Outsourced PCI

> **Deployment Model:** Merchant self-hosts Hyperswitch Orchestration Layer
>
> **PCI Scope:** Outsourced to an external vault provider like VGS, TokenEx

### Overview

In this deployment model, merchants **self-host** the Juspay Hyperswitch orchestration layer on their own infrastructure while **outsourcing** all PCI DSS responsibilities to an external, PCI-compliant vault provider. Sensitive cardholder data (PAN, CVV, expiry) never touches the merchant's servers.

This architecture gives merchants full control over orchestration logic, routing rules, and business configurations while eliminating the burden of achieving and maintaining PCI DSS Level 1 compliance in-house

### Why This Model?

<table><thead><tr><th width="204.40625">Concern</th><th>How It's Addressed</th></tr></thead><tbody><tr><td><strong>PCI Compliance</strong></td><td>Fully offloaded to the vault provider (VGS, Tokenex, etc.)</td></tr><tr><td><strong>Hosting Independence</strong></td><td>Merchant retains complete control of the Hyperswitch deployment</td></tr><tr><td><strong>Sensitive Data Exposure</strong></td><td>Raw card data never enters the merchant's environment</td></tr><tr><td><strong>Token Portability</strong></td><td><code>payment_method_id</code> unifies <code>vault_token</code> + <code>psp_token</code> + <code>customer_id</code> for cross-platform use</td></tr><tr><td><strong>Operational Simplicity</strong></td><td>No need to manage HSMs, key rotation, or cardholder data environments</td></tr></tbody></table>

#### **Supported providers include (but are not limited to):**

* **VGS (Very Good Security)** — Provides inbound/outbound proxy routes for card data. Hyperswitch sends PSP payloads through VGS's forward proxy, which replaces tokens with raw card data in transit.
* **Tokenex** — Offers a transparent gateway proxy. Hyperswitch sends tokenized payloads to Tokenex's proxy, which detokenizes and forwards to the PSP.
* **Any vault that supports SDK to accept PCI raw info and have proxy API for detokenizing and making call to PSP** — Hyperswitch's modular vault architecture supports any vault that provides an SDK for secure card collection and a proxy/detokenize API.

Hyperswitch's modular vault architecture supports configuring multiple vault connectors simultaneously. You can route different merchants or payment methods to different vaults based on your business logic.

### Integration Steps

#### Self-Hosted Hyperswitch Managed Merchant Client

The merchant loads the **Hyperswitch Unified Checkout SDK**, which embeds the **Third Party Vault SDK** to collect card information for tokenization via Third Party vault.

<details>

<summary><strong>New User Payment Flow</strong></summary>

* The merchant loads the [Hyperswitch Payments SDK](https://docs.hyperswitch.io/explore-hyperswitch/payment-experience/payment) via a [Payments Create API](https://api-reference.hyperswitch.io/v1/payments/payments--create) request. The Hyperswitch SDK in turn loads the external vault SDK configured in the merchant account.
* The end user enters their card details directly into the external vault SDK's secure iframe/fields.
* The external vault SDK tokenizes the card and returns a `vault_token` along with card metadata (last four digits, card brand, expiry) to the Hyperswitch SDK.
* The Hyperswitch SDK sends a [Payment Confirm API](https://api-reference.hyperswitch.io/v1/payments/payments--confirm) request containing the `vault_token` and card metadata to the self-hosted Hyperswitch backend.
* Hyperswitch constructs the PSP payload using the `vault_token`.
* The PSP payload (containing the `vault_token`) is sent to the **Proxy endpoint** of the external vault.
* The external vault replaces the `vault_token` with the raw card data and forwards the request to the PSP.
* The PSP responds with `approved` or `declined` along with a `psp_token`. The vault proxy relays this response back to Hyperswitch.
* Hyperswitch generates a `payment_method_id` linking `customer_id`, `vault_token`, and `psp_token`.
* The `payment_method_id` and `vault_token` are returned to the merchant via webhooks.

</details>

<details>

<summary><strong>Repeat User Payment Flow</strong></summary>

* The Hyperswitch SDK loads stored payment methods using the `customer_id` from the [Payments Create API](https://api-reference.hyperswitch.io/v1/payments/payments--create) request.
* The end user selects a saved card
* The SDK sends a [Payment Confirm API](https://api-reference.hyperswitch.io/v1/payments/payments--confirm) request and sends the corresponding `payment_method_id`
* Hyperswitch resolves the `payment_method_id` to identify the associated `psp_token` and processes the payment by sending the transaction to the corresponding PSP as a MIT

</details>

<details>

<summary><strong>Merchant-Initiated Transaction (MIT) Flow</strong></summary>

* The merchant triggers an [MIT or Recurring transaction](https://docs.hyperswitch.io/about-hyperswitch/payment-suite-1/payments-cards/recurring-payments) using the `payment_method_id.`
* Hyperswitch resolves the `payment_method_id` to identify the associated `psp_token` and processes the payment by sending the transaction to the corresponding PSP as a MIT

</details>

<figure><img src="/files/SA9gfLbvdnKxCN6r2IzO" alt="Self-Hosted Orchestration with Third Party Vault Flow"><figcaption><p>Payment flow showing self-hosted orchestration layer with Third Party Vault</p></figcaption></figure>

### Key Concepts

#### `payment_method_id`

A **universal, portable token** generated by Hyperswitch that serves as the single reference for a stored payment method. It connects:

| Entity        | Description                                                         |
| ------------- | ------------------------------------------------------------------- |
| `customer_id` | The Hyperswitch customer identifier                                 |
| `vault_token` | The token issued by the external vault representing the stored card |
| `psp_token`   | The token issued by the PSP after a successful transaction          |

This abstraction allows merchants to:

* Switch PSPs without re-collecting card data.
* Switch vault providers without breaking existing customer references.
* Use a single identifier across all payment flows (first-time, repeat, MIT/recurring).

***

### Configuration Guide

#### Configuring the External Vault in Juspay Hyperswitch

To enable an external vault with your self-hosted Hyperswitch instance, follow these configuration steps:

#### **Step 1: Generate API Key**

1. **Access Dashboard** — Log into the Hyperswitch Control Centre.
2. **Navigate to API Keys** — In the left-hand navigation menu, select **Developers > API Keys**.
3. **Create Key** — Click **Create New API Key**.
4. **Secure Storage** — Copy the generated key immediately and store it securely (it will not be shown again). Use this key in the `api-key` header for all Vault API calls.

<figure><img src="/files/FcVvfmYdCWXa3dSsvJdq" alt="API Keys Dashboard"><figcaption><p>Navigate to Developers > API Keys to create and manage your API credentials</p></figcaption></figure>

#### **Step 2: Access Profile ID**

1. **Navigate to Payment Settings** — In the left-hand navigation menu, select **Developers > Payment Settings**.
2. **Copy Profile ID** — Locate and copy your **Profile ID** from the Payment Settings page. This ID is required for API calls that need to specify which merchant profile to use.

<figure><img src="/files/wju234zdrd6DunoeFf2q" alt="Payment Settings - Profile ID"><figcaption><p>Navigate to Developers > Payment Settings to access your Profile ID</p></figcaption></figure>

#### **Step 3: Enable Vault Connector**

1. **Navigate to Vault Processor** — In the left-hand navigation menu, select **Connectors > Vault Processor**.
2. **Configure Vault Provider** — Add your vault provider credentials and configuration:

<figure><img src="/files/wTtTiAYkxWRfrO82cyaI" alt="Vault Processor Setup"><figcaption><p>Navigate to Connectors > Vault Processor to configure your vault provider</p></figcaption></figure>

**Required Credentials by Provider:**

| Provider    | Required Credentials               |
| ----------- | ---------------------------------- |
| **VGS**     | Vault ID, Client Secret, Client ID |
| **Tokenex** | Token Scheme, API Key, Tokenex ID  |

3. **Enable in Payment Settings** — Navigate to **Developers > Payment Settings**, under **Vault** tab, enable the vault and choose the vault processor from the dropdown, then click **Update**.

<figure><img src="/files/D1Au2KwrTLQ4Ih8muDVs" alt="Enable Vault in Payment Settings"><figcaption><p>Navigate to Developers > Payment Settings to enable your vault</p></figcaption></figure>

***

### Comparison: Self-Hosted Vault Deployment Models

<table><thead><tr><th width="138.015625">Feature</th><th>Self-Hosted + In-House PCI</th><th>Self-Hosted + Outsourced PCI (This Model)</th><th>SaaS + Outsourced PCI</th></tr></thead><tbody><tr><td><strong>Hosting</strong></td><td>Merchant</td><td>Merchant</td><td>Juspay (SaaS)</td></tr><tr><td><strong>PCI Scope</strong></td><td>Merchant (Level 1)</td><td>Vault Provider</td><td>Juspay + Vault Provider</td></tr><tr><td><strong>Vault</strong></td><td>Merchant's own vault</td><td>VGS / Tokenex</td><td>VGS / Tokenex</td></tr><tr><td><strong>Card Data on Server</strong></td><td>Yes</td><td>No</td><td>No</td></tr><tr><td><strong>Orchestration Control</strong></td><td>Full</td><td>Full</td><td>Managed</td></tr><tr><td><strong>Setup Complexity</strong></td><td>High</td><td>Medium</td><td>Low</td></tr><tr><td><strong>Compliance Maintenance</strong></td><td>High</td><td>None</td><td>None</td></tr><tr><td><strong>Token Portability</strong></td><td>Depends</td><td>Yes (<code>payment_method_id</code>)</td><td>Yes (<code>payment_method_id</code>)</td></tr></tbody></table>

***

### Security Considerations

* **TLS Everywhere:** All communication between Hyperswitch, the vault, and PSPs must use TLS 1.2+.
* **Credential Rotation:** Regularly rotate vault API keys and proxy credentials.
* **Audit Logging:** Enable Hyperswitch audit logs for all vault operations (tokenize, detokenize, proxy calls) to maintain compliance evidence.
* **Network Segmentation:** Even though PCI is outsourced, restrict network access between your Hyperswitch deployment and the vault to only the required endpoints and ports.
* **Webhook Verification:** Always verify webhook signatures for `payment_method_id` callbacks to prevent spoofing.

***

### FAQ

**Q: Does raw card data ever touch my self-hosted Hyperswitch server?** A: No, the card is tokenized on the client side or by the vault SDK before it reaches your server.

**Q: Can I switch vault providers without affecting existing customers?** A: Yes. Since Hyperswitch uses `payment_method_id` as the universal reference, you can migrate vault tokens between providers. Hyperswitch will update the internal mapping from `payment_method_id` → new `vault_token`.

**Q: What PCI SAQ level applies to me in this model?** A: Typically **SAQ A-EP** (if you host the checkout page) or **SAQ A** (if the vault SDK iframe handles all card input). Consult your QSA for a definitive assessment.

**Q: Can I use multiple vault providers simultaneously?** A: Hyperswitch's modular vault architecture supports configuring multiple vault connectors. You can route different merchants or payment methods to different vaults based on your business logic.

***

### Related Documentation

* [Vault — Modular Vaulting in Hyperswitch](https://docs.hyperswitch.io/explore-hyperswitch/workflows/vault)
* [SaaS Orchestration with Third-Party Vault](https://docs.hyperswitch.io/explore-hyperswitch/workflows/vault/saas-orchestration-with-third-party-vault)
* [Payments SDK Integration](https://docs.hyperswitch.io/explore-hyperswitch/payment-experience/payment)
* [Recurring Payments](https://docs.hyperswitch.io/about-hyperswitch/payment-suite-1/payments-cards/recurring-payments)
* [PCI DSS 4.0 Compliance](https://hyperswitch.io/pci.pdf)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.hyperswitch.io/integration-guide/workflows/vault/deployment-models/self-hosted-orchestration-with-external-or-third-party-pci-vault.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.