An X2Y Product Open Source · MIT

HyperSwitch
PHP SDK

A pure-PHP client for the HyperSwitch payment orchestration API.

Framework-agnostic, PSR-18 / PSR-3 compatible, and built for complete coverage of the HyperSwitch v1 API: payments, routing, subscriptions, payouts, disputes, 3DS authentication, and signed webhooks. Zero framework lock-in, immutable typed DTOs, and drift-tested against the first-party v1 OpenAPI spec. Built and open-sourced by X2Y.

View on GitHub Quick start
$ composer require x2y/hyperswitch-client

Ask AI about the HyperSwitch PHP SDK

ChatGPT Claude Gemini Perplexity Meta AI
create-payment.php 
$client = HyperSwitchClient::sandbox(
    httpClient:     new Psr18Client(),
    requestFactory: $psr17,
    streamFactory:  $psr17,
    auth: new MerchantKeyAuthResolver('snd_…'),
);

$response = $client->payments()->create(
    new CreatePaymentRequest(
        amount:   4500,
        currency: Currency::USD,
    )
);

// pay_abc123
echo $response->paymentId;

Why this SDK

A thin, typed, framework-free client you can trust in production.

A 1:1 mirror of the HyperSwitch HTTP API with no business logic to get in your way, drop it into Laravel, Symfony, Magento, or plain PHP.

Framework-agnostic
Zero framework dependencies under src/. You supply any PSR-18 HTTP client (Symfony, Guzzle, or your own) and a PSR-3 logger, the SDK stays a contract, not a lock-in.
Complete v1 coverage
Every operation in the HyperSwitch v1 API — all 150, across payments, routing, subscriptions, payouts, disputes, 3DS authentication, events, and more, each behind a typed resource facade. Plus the v2-compat modular payment-methods surface.
Immutable typed DTOs
Every request and response is an immutable, fully typed object with toArray() / fromArray(). No array guessing, no magic, your IDE autocompletes the entire payment surface.
Signed webhook verification
A built-in HMAC verifier (SHA-512) checks the signature before JSON decode, an invalid signature short-circuits without ever hitting the parser. Typed event decoder included.
Forward compatible
Unknown response fields are preserved in extras, so HyperSwitch can add fields without breaking your build. New fields are a non-disruptive minor bump, never a crash.
Drift-tested & strict
A drift test asserts the SDK still mirrors the first-party HyperSwitch v1 OpenAPI spec — in both directions — and PHPStan runs at level 8. When HyperSwitch ships a change, the test tells you exactly what is missing.

Quick start

Install, authenticate, charge.

Requires PHP 8.1+ and any PSR-18 HTTP client. One Composer command and you're integrated.

terminal
$ composer require x2y/hyperswitch-client
$ composer require symfony/http-client nyholm/psr7
webhook-receiver.php
$decoder = new EventDecoder(
    new SignatureVerifier($key)
);

$event = $decoder->decode($body, $signature);

match ($event->eventType) {
    EventType::PAYMENT_SUCCEEDED
        => $this->markOrderPaid($event->asPayment()),
    EventType::DISPUTE_OPENED
        => $this->flagDispute($event->asDispute()),
    default => $this->logUnhandled($event),
};

API coverage

All 150 v1 operations. 27 typed groups.

Every operation in the HyperSwitch v1 API is mirrored by a typed resource facade. Below is the full surface area.

Group Endpoints
Routing 20
Payments 18
Disputes 12
Subscriptions 12
Payouts 9
Payment Methods (v1) 9
Authentication (3DS) 8
Blocklist 7
Customers 7
Connectors 6
Payment Methods (v2 compat) 6
PaymentMethodSessions (v2 compat) 6
ApiKeys 5
BusinessProfile 5
MerchantAccounts 5
Platform / Organization 5
Refunds 4
Events (webhook delivery) 4
GSM 4
Card Issuers 4
Mandates 3
Relay 2
Profile Acquirers 2
PaymentLinks 1
Poll 1
3DS Decision Rule 1
Proxy (v2 compat) 1

167 endpoints total: the 150 v1 operations plus the 17 forward-looking v2-compat modular payment-methods paths (marked v2 compat). Plus inbound Webhook\EventDecoder for signed event handling.

Architecture

Layered, replaceable, and boring, by design.

Every layer is swappable in isolation: resources don't know about HTTP, the transport doesn't know about API groups, and DTOs don't know about transport. That predictability is what makes the SDK cheap to maintain and safe to upgrade.

  • Resource: A typed facade per API group, the public surface you call.
  • Endpoint: A value object: method, path, auth tier, and DTO references.
  • DTO: Immutable request/response objects with toArray() / fromArray().
  • Transport: The single ApiClient + middleware pipeline over PSR-18.
  • Auth: Per-tier resolvers: admin, merchant, publishable, ephemeral, and JWT.
layers
┌────────────────────────────────────────┐
│ Resource   Typed facade per API group   │
├────────────────────────────────────────┤
│ Endpoint   method · path · auth tier    │
├────────────────────────────────────────┤
│ Dto        immutable typed request/resp │
├────────────────────────────────────────┤
│ Transport  ApiClient + middleware       │
├────────────────────────────────────────┤
│ Auth       AuthTier + per-tier resolver │
└────────────────────────────────────────┘
                  │
                  ▼
          PSR-18 HTTP client
          (consumer-supplied)

We build these for payment providers

This SDK came out of building and maintaining real gateway modules. If you run a payment product and need one for Magento, Adobe Commerce, Mage-OS, Shopify or WooCommerce, that is the work we do.

Payment module development
Free & MIT licensed

Built by X2Y to power real payment integrations.

This SDK powers our HyperSwitch Magento module and client integrations, now open-sourced for the PHP community. Star it, fork it, or let us build your payments integration on top of it.

View on GitHub View on Packagist Need a payments integration?

More from X2Y

Learn how you can grow your ecommerce business with our expert advice.

View all case studies

0%