PHP

PHP 8.1+, cURL, no other dependencies
Every create sends an Idempotency-Key, so retries never double-charge
Network errors, 429 and 5xx are retried with backoff
all() walks every page of a list
Webhook::verify() checks Standard Webhooks signatures

Install

composer require utopia-payments/utopia-php:^0.1

Composer installs the tagged release from Packagist. The public source is at Utopia-Payments/utopia-php.

Quick start

Create a secret key in Dashboard → Developers and keep it on your server.

use Utopia\Utopia;

$utopia = new Utopia(getenv('UTOPIA_API_KEY'));

$session = $utopia->checkoutSessions->create([
    'product_cart' => [['product_id' => 'pdt_…', 'quantity' => 1]],
    'customer' => ['email' => 'customer@example.com'],
    'return_url' => 'https://your-store.com/thank-you',
    'metadata' => ['order_id' => '1001'],
]);

header('Location: ' . $session['checkout_url']);

Amounts are integers in minor units: 34900 is AED 349.00. Responses are associative arrays shaped like the API's JSON. See Currencies and amounts, especially for KWD, BHD and OMR.

Resources

The client exposes $account, $products, $customers, $checkoutSessions, $payments, $subscriptions, $webhookEndpoints and $events.

Subscriptions

$plan = $utopia->products->create([
    'name' => 'Pro',
    'price' => 9900,
    'currency' => 'AED',
    'billing' => 'recurring',
    'billing_interval' => 'month',
]);

$session = $utopia->checkoutSessions->create([
    'product_cart' => [['product_id' => $plan['product_id']]],
    'customer' => ['email' => 'member@example.com'],
]);

// Later: stop renewing when the paid period ends.
$utopia->subscriptions->cancel('sub_…', atPeriodEnd: true);

Webhooks

Laravel

Route::post('/webhooks/utopia', function (Request $request) {
    $event = \Utopia\Webhook::verify(
        $request->getContent(),
        $request->headers->all(),
        config('services.utopia.webhook_secret'),
    );
    // …
    return response()->noContent();
});

See Webhooks for plain PHP and the events.

Webhook::verify() is static and needs no API key or Utopia client.

Lists

$page = $utopia->payments->list(['limit' => 50, 'status' => 'succeeded']);

foreach ($utopia->payments->all(['limit' => 100]) as $payment) {
    echo $payment['payment_id'], PHP_EOL;
}

Errors

use Utopia\Exception\NotFoundException;
use Utopia\Exception\UtopiaException;

try {
    $utopia->payments->retrieve('pay_…');
} catch (NotFoundException $e) {
    // …
} catch (UtopiaException $e) {
    echo $e->getHttpStatus(), ' ', $e->getErrorCode(), ': ', $e->getMessage();
}

Exception classes: InvalidRequestException, AuthenticationException, PermissionDeniedException, NotFoundException, ConflictException, RateLimitException, ApiException, ApiConnectionException, WebhookVerificationException.

Options

new Utopia('sk_live_…', [
    'timeout' => 30,     // seconds
    'max_retries' => 2,
    'base_url' => 'https://utopia-payments.com/api/v1',
]);

On this page