enigmoss / php-sdk
Official PHP SDK for the Enigmoss Project API v4: payments, static wallets, payouts, refunds, transfers and signed webhooks.
Requires
- php: ^8.1
- ext-json: *
Requires (Dev)
- friendsofphp/php-cs-fixer: ^3.64
- guzzlehttp/guzzle: ^7.8 || ^8.0
- orchestra/testbench: ^8.0 || ^9.0 || ^10.0 || ^11.0
- phpat/phpat: ^0.11
- phpstan/phpstan: ^2.1
- phpstan/phpstan-strict-rules: ^2.0
- phpunit/phpunit: ^10.5 || ^11.5 || ^12.0
- psr/log: ^1.1 || ^2.0 || ^3.0
- psr/simple-cache: ^3.0
- shipmonk/composer-dependency-analyser: ^1.8
- symfony/framework-bundle: ^6.4 || ^7.4 || ^8.0
- symfony/http-client: ^6.4 || ^7.4 || ^8.0
Suggests
- ext-curl: Required by the built-in default transport (CurlTransport).
- ext-pdo: Enigmoss\Webhook\PdoWebhookDeduplicator: atomic webhook deduplication in your database.
- laravel/framework: Laravel 10+: auto-discovered EnigmossServiceProvider, facade, webhook route.
- psr/http-client: Use any PSR-18 client through Enigmoss\Bridge\Psr18\Psr18Transport.
- psr/http-factory: PSR-17 factories for the PSR-18 transport.
- psr/log: Log SDK calls through Enigmoss\Bridge\Psr3\LoggerObserver.
- psr/simple-cache: Share the API origin learned from the fallback host between processes through Enigmoss\Bridge\Psr16\Psr16OriginStore.
- symfony/http-kernel: Symfony 6.4+: EnigmossBundle, webhook argument resolver.
Provides
None
Conflicts
None
Replaces
None
README
The official PHP SDK for the Enigmoss Project API v4: accept crypto payments, run static wallets, send payouts and refunds, and receive signed webhooks, with typed objects and money-safe retries.
- Typed DTOs. Requests, responses, enums and webhook events are real classes with real types. No arrays-of-arrays.
- Zero runtime dependencies. Only
ext-json, plusext-curlfor the default transport. Bring your own HTTP client through PSR-18 or Symfony HttpClient if you prefer. - Money-safe retries and idempotency. Create calls derive their
Idempotency-Keyfrom yourorder_id; the SDK never retries a money-moving call in a way that could pay twice. A create ends in one of three outcomes (created, definitely not created, pending reconcile): see Errors. - Webhook verification. HMAC-SHA256 signature check, replay window, key rotation, typed events and an atomic deduplicator (
claim()/release(), including a PDO implementation). - Laravel and Symfony bridges. Auto-discovered service provider, facade, webhook route and artisan commands; a Symfony bundle with autowiring and a controller argument resolver.
- Testing helpers.
MockTransport,Fixtures,WebhookSimulator,Enigmoss::fake(), and examples that run offline.
Requirements and supported versions
| Component | Supported versions |
|---|---|
| PHP | 8.1, 8.2, 8.3, 8.4, 8.5 |
| Laravel (optional bridge) | 10, 11, 12, 13 |
| Symfony (optional bridge) | 6.4, 7.4, 8.x |
Extensions: ext-json (always), ext-curl (default transport only).
PHP-version policy. A PHP version is dropped only in a major release of the SDK, never in a minor or patch release. See Versioning and BC.
Install
composer require enigmoss/php-sdk
Quickstart
The API base URL is white-label: use "your API host from the dashboard". https://api.example.com below is a placeholder.
<?php declare(strict_types=1); require __DIR__ . '/vendor/autoload.php'; use Enigmoss\ClientConfig; use Enigmoss\EnigmossClient; use Enigmoss\Payment\CreatePaymentRequest; use Enigmoss\Secret; $enigmoss = new EnigmossClient(new ClientConfig( baseUrl: 'https://api.example.com', projectId: '3f2b8c1e-5d4a-4e7b-9c6f-1a2b3c4d5e6f', paymentKey: new Secret((string) getenv('ENIGMOSS_PAYMENT_KEY')), )); $payment = $enigmoss->payments->create(new CreatePaymentRequest(amount: '10.50', currencyCode: 'USDT', orderId: 'order-42')); if ($payment->paymentUrl === null) { // may be null: do not redirect to an empty URL http_response_code(502); exit; } header('Location: ' . $payment->paymentUrl);
Amounts are always decimal strings ("10.50"), never floats.
Webhook endpoint quickstart
Webhooks are signed with your payment key. Verify the raw body, answer 2xx quickly, and do heavy work in a queue.
<?php declare(strict_types=1); require __DIR__ . '/vendor/autoload.php'; use Enigmoss\Event\PaymentEvent; use Enigmoss\Exception\WebhookVerificationException; use Enigmoss\Secret; use Enigmoss\Webhook\WebhookVerifier; $verifier = new WebhookVerifier('3f2b8c1e-5d4a-4e7b-9c6f-1a2b3c4d5e6f', new Secret((string) getenv('ENIGMOSS_PAYMENT_KEY'))); try { $event = $verifier->constructEvent((string) file_get_contents('php://input'), WebhookVerifier::headersFromGlobals()); } catch (WebhookVerificationException $e) { http_response_code(400); exit; } if ($event instanceof PaymentEvent) { $payment = $event->payment(); if ($payment->walletId !== null) { // A deposit to a static wallet: there is no orderId. Identify the customer by walletId. } elseif ($payment->isSuccessful()) { // Paid and final (status->isPaid() && isFinal): claim $event->id for deduplication, // then enqueue fulfilment of $payment->orderId. } } http_response_code(200);
isSuccessful() is the one fulfilment rule: a paid payment can be non-final while an automatic conversion settles. Deduplicate with WebhookDeduplicatorInterface::claim() (atomic); Webhooks shows the pattern and the PdoWebhookDeduplicator.
A complete version is in examples/webhook-endpoint.php. All examples can run offline: ENIGMOSS_EXAMPLE_MOCK=happy php examples/create-payment.php (see examples).
Documentation
Start here
- Getting started: install, first request, first webhook, and why there is no sandbox.
- Configuration: every
ClientConfigoption,Secret, multiple projects, transports. - Authentication and keys: payment key vs payout key, which keys a scenario needs, endpoint-to-permission matrix.
Resources
- Payments: invoices, statuses, cancel, mark paid, AML links.
- Wallets: static wallets and their deposits.
- Refunds: refund a payment or a blocked wallet.
- Payouts: the quote, create, reconcile flow.
- Balances and transfers: balances, transactions, transfers to the personal account.
- Catalog: payment methods, payout methods, exchange rates.
Webhooks
- Webhooks: verification, events, delivery rules, deduplication.
- Webhook events API: the events journal, redelivery and replay.
Reliability
- Errors: exception hierarchy, error codes, violations, the
outcomeUnknown()table, the three outcomes and the catch order. - Idempotency and retries: how the SDK keeps money calls safe.
- Pagination:
list(),iterate(),findByOrderId(), cursors.
Frameworks and tooling
Project
- Security and SECURITY.md
- Versioning and BC
- Changelog, Upgrade guide, Contributing
docs/llms.txt: a compact API summary for AI coding assistants- Runnable examples
License
MIT. See LICENSE.