# Zen

<div align="left"><img src="https://hyperswitch.io/img/site/zenLogo.svg" alt=""></div>

Zen connects to Hyperswitch as a `PaymentGateway` connector using `HeaderKey` authentication — the API Key is sent as `Authorization: Bearer {api_key}` on every request. Every request also carries a `request-id` header containing a per-request UUID v4 generated by Hyperswitch. All requests use `application/json`. Zen is a modern payments platform offering low fees, conversion optimization, and secure raw card data handling.

### Connector-Specific Notes

* **API Key as Bearer token:** Zen uses `HeaderKey` authentication. The API Key is sent directly as a Bearer token in the `Authorization` header — `Authorization: Bearer {api_key}`. Enter the key as provided by your Zen account manager; no additional encoding is needed.
* **Per-request UUID:** Every Zen request includes a `request-id` header with a freshly generated UUID v4. Hyperswitch generates this automatically on each request.
* **Credentials location:** API Key is obtained from your Zen Account manager. Request Zen support to enable raw card data handling for your account.
* **Webhook support:** Zen delivers webhook events to Hyperswitch. The webhook signature is embedded as a hex-encoded value within the webhook body (`ZenWebhookSignature`). Hyperswitch verifies this on receipt.
* **Capture methods supported:** Automatic, Manual, and SequentialAutomatic.
* Zen is a modern and responsive payments portal providing low fees for conversion boost and increased revenue for merchants.
* For a full list of supported payment methods, visit [hyperswitch.io/pm-list](https://hyperswitch.io/pm-list).

***

### Activating Zen via Hyperswitch

#### Prerequisites

1. You need to be registered with Zen and obtain the API Key from your Zen Account manager. Contact Zen at [zen.com](https://www.zen.com/) for onboarding.
2. You should have a registered Hyperswitch account, accessible from the [Hyperswitch control center](https://app.hyperswitch.io/).
3. Request the Zen support team to enable handling raw card data for your account. This allows Hyperswitch to securely process your customers' payment details.
4. Select all payment methods you wish to use Zen for. Ensure these match the ones configured in your Zen account.

[Steps to activate Zen on the Hyperswitch control center](https://docs.hyperswitch.io/hyperswitch-cloud/connectors/activate-connector-on-hyperswitch)

***

### Responsibility Boundaries

**Hyperswitch owns:** routing decisions, sending the API Key as a Bearer token on every request, generating the per-request `request-id` UUID, retry scheduling, webhook signature verification, and unified error mapping. **Zen owns:** payment execution, card data handling (when raw card processing is enabled), fraud decisioning, and settlement.

**Hyperswitch owns:** presenting the correct API Key on every request. **Zen owns:** validating the Bearer token. If the API Key is rotated in Zen and not updated in Hyperswitch, all requests will fail authentication immediately.

***

### Common Failure Modes

**Authentication failure** Symptom: All requests fail with a Zen authentication error. Fix: Verify the API Key in Hyperswitch matches the one provided by your Zen Account manager. The key is sent as `Authorization: Bearer {api_key}` — enter it without any prefix or encoding.

**Raw card data rejected** Symptom: Card payment requests fail with a data handling or permission error. Fix: Confirm with Zen support that raw card data handling is enabled for your account. Without this, card data cannot be processed through Hyperswitch.

**Webhook signature verification failure** Symptom: Zen events arrive at Hyperswitch but payment statuses do not update. Fix: Verify the Hyperswitch webhook endpoint URL is configured correctly in your Zen account and that the webhook secret matches what Zen expects.

***

Connector implementation: `crates/hyperswitch_connectors/src/connectors/zen.rs`.


---

# Agent Instructions: 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:

```
GET https://docs.hyperswitch.io/integrations/connectors-integrations/payment-processor-capabilities/available-connectors/zen.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.