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 full coverage of the public API surface: payments, subscriptions, payouts, disputes, and signed webhooks. Zero framework lock-in, immutable typed DTOs, and drift-tested against the upstream API. Built and open-sourced by X2Y.

View on GitHub Quick start
$ composer require x2y/hyperswitch-client
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.
Full API coverage
17 of 17 HyperSwitch resource groups and ~83 endpoints: payments, subscriptions, payouts, mandates, disputes, connectors, and more, each behind a typed resource facade.
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 matches the upstream Postman collection, 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

17 of 17 resource groups. ~83 endpoints.

Every Postman group is mirrored by a typed resource facade. Below is the full surface area.

Group Endpoints
Payments 11
Subscriptions 11
Payouts 6
Customers 6
PaymentMethods (V1) 6
PaymentMethodSessions 6
Refunds 4
Disputes 4
Mandates 3
ApiKeys 5
Connectors 5
BusinessProfile 5
MerchantAccounts 4
Platform 3
Relay 2
PaymentLinks 1
Proxy 1

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.
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)
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%