Unitpay PHP SDK

PHP SDK for the Unitpay.ru payment REST API.

A thin, stateless SDK: build a signed redirect to Unitpay's hosted payment page or call the API server-to-server, attach 54-FZ fiscal receipts, and verify inbound webhooks. Everything hangs off one entry point, Unitpay\Unitpay, which hands out service objects.

Official Unitpay documentation: help.unitpay.ru

Upgrading from 3.x? 4.0 changes the TransportInterface contract and starts rejecting webhooks older than 5 minutes. If you use the SDK's own transport and your server clock is synchronised, it is a version bump — see the v4 Migration Guide.

Upgrading from 2.x? 3.0 moved every class into the Unitpay\ namespace and replaced api('method', [...]) with typed service methods. There is no compatibility shim — see the v3 Migration Guide, then the v4 guide.

Requirements

• PHP >= 7.4
• ext-json
• ext-ctype

No Composer dependencies. ext-curl is optional: the default transport uses it when present and falls back to file_get_contents() otherwise.

Installation

composer require unitpay/php-sdk

Then load the Composer autoloader — the package is PSR-4 (Unitpay\ → src/):

require__DIR__ . '/vendor/autoload.php';

See Getting Started for the dev-master option.

Quick Start

<?phprequire__DIR__ . '/vendor/autoload.php';
useUnitpay\Model\CashItem;
useUnitpay\Unitpay;
$unitpay = newUnitpay('unitpay.ru', $secretKey);
$unitpay
->setBackUrl('https://domain.com')
->setCustomerEmail('customer@domain.com')
->setCashItems([newCashItem('Iphone 6 Skin Cover', 1, 900)]);
$redirectUrl = $unitpay->form($publicId, 900, $orderId, 'Payment for item', 'RUB');
header('Location: ' . $redirectUrl);

Prefer a server-to-server call? Use $unitpay->payments()->initPayment(...) — see Getting Started.

Key Features

• Hosted form or API — form() builds a signed redirect URL; payments()->initPayment(...) does a server-to-server call.
• Service objects — payments(), subscriptions(), payouts(), reference(), each with typed methods, so required parameters are enforced at the call site.
• 54-FZ fiscal receipts — attach CashItem line items to any payment.
• Secure webhooks — webhook()->checkHandlerRequest() trusts a callback only when both the SHA-256 signature and the source-IP allowlist pass.
• Dynamic IP allowlist — refresh Unitpay's webhook IPs from the published feed, fail-safe.
• Swappable transport — inject any Unitpay\Http\TransportInterface to plug in your own HTTP stack or to test without the network.
• Typed exceptions — all implement UnitpayExceptionInterface.
• Zero dependencies — no Composer packages; ext-json + ext-ctype (ext-curl optional).

Documentation

Guide	Description
Getting Started	Requirements, installation, first payment (form / API)
Fiscal Receipts	54-FZ receipt line items via CashItem
API Methods	Full service reference and account-level calls
Webhooks	Payment handler + keeping the IP allowlist fresh
Telemetry	Anonymous SDK fingerprint and naming your integration
v4 Migration Guide	Upgrading from 3.x to 4.0
v3 Migration Guide	Upgrading from 2.x to 3.0

Runnable samples for every method group live in examples/.

Contributing

Please feel free to contribute to this project! Pull requests and feature requests welcome!

License

MIT — see LICENSE.md.