Search by

enigmoss / php-sdk

enigmoss

Official PHP SDK for the Enigmoss Project API v4: payments, static wallets, payouts, refunds, transfers and signed webhooks.

v1.0.0 2026-11-20 13:10 UTC

This package is auto-updated.

Last update: 2026-11-20 13:27:15 UTC


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.

Packagist Version PHP >= 8.1 License: MIT

  • Typed DTOs. Requests, responses, enums and webhook events are real classes with real types. No arrays-of-arrays.
  • Zero runtime dependencies. Only ext-json, plus ext-curl for 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-Key from your order_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 ClientConfig option, 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

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

License

MIT. See LICENSE.