Zen

Connect Zen to Juspay Hyperswitch to accept payments with low fees, boost conversions, and manage raw card data securely through the Hyperswitch control center.

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.

Activating Zen via Hyperswitch

Prerequisites

You need to be registered with Zen and obtain the API Key from your Zen Account manager. Contact Zen at zen.com for onboarding.
You should have a registered Hyperswitch account, accessible from the Hyperswitch control center.
Request the Zen support team to enable handling raw card data for your account. This allows Hyperswitch to securely process your customers' payment details.
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

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.

Last updated 25 days ago

Was this helpful?