README.md

Getting Started

Official PHP SDK for the Vatly API. Handle subscriptions, one-off payments, tax compliance, and billing for your SaaS.

Looking for the exact field list? These guides cover the common paths. The authoritative, machine-readable schema for every endpoint lives in the OpenAPI spec — point your AI assistant or codegen tooling at it when an example leaves a field ambiguous.

Installation

Install the SDK via Composer.

composer require vatly/vatly-api-php

---

Quick start

Initialize the client with your API key and create a checkout.

API Keys

Get your API keys from the Vatly Dashboard under Settings > API.

Name	Type	Description
live_	prefix	Production transactions, real charges.
test_	prefix	Sandbox testing, no real charges.

use Vatly\API\VatlyApiClient;

$vatly = new VatlyApiClient();
$vatly->setApiKey('live_your_api_key_here');

// Create a checkout
$checkout = $vatly->checkouts->create([
    'products' => [
        ['id' => 'subscription_plan_abc123', 'quantity' => 1]
    ],
    'redirectUrlSuccess' => 'https://yourapp.com/success',
    'redirectUrlCanceled' => 'https://yourapp.com/canceled',
]);

// Redirect customer to checkout
header('Location: ' . $checkout->getCheckoutUrl());

---

Idempotency

The SDK automatically adds an Idempotency-Key header to every POST and PATCH request. This is enabled by default, so checkout creation and subscription updates are already protected without extra configuration.

GET and DELETE requests do not include an idempotency header.

Override the next mutating request

Use setIdempotencyKey() when you want to supply the key yourself. The value is used for the next POST or PATCH request and then cleared automatically.

$vatly->setIdempotencyKey('checkout-create-123');

$checkout = $vatly->checkouts->create([
    'products' => [
        ['id' => 'subscription_plan_abc123', 'quantity' => 1],
    ],
    'redirectUrlSuccess' => 'https://yourapp.com/success',
    'redirectUrlCanceled' => 'https://yourapp.com/canceled',
]);

This also works with resource methods that do not expose request options directly:

$vatly->setIdempotencyKey('subscription-update-123');

$subscription->update([
    'quantity' => 2,
]);

Per-request options on supported endpoint methods

Methods that accept a second or third options array can override the header with idempotencyKey.

$checkout = $vatly->checkouts->create([...], [
    'idempotencyKey' => 'checkout-create-123',
]);

$subscription = $vatly->subscriptions->update('subscription_123', [
    'quantity' => 2,
], [
    'idempotencyKey' => 'subscription-update-123',
]);

Custom generator or disable auto-generation

If you need a specific key format, provide your own generator implementation.

use Vatly\API\HttpClient\Idempotency\IdempotencyKeyGeneratorContract;

final class MyIdempotencyKeyGenerator implements IdempotencyKeyGeneratorContract
{
    public function generate(): string
    {
        return bin2hex(random_bytes(16));
    }
}

$vatly->setIdempotencyKeyGenerator(new MyIdempotencyKeyGenerator());

To stop the SDK from generating keys automatically:

$vatly->clearIdempotencyKeyGenerator();

---

Resources

The SDK provides access to all Vatly API resources.

Resource	Description
Checkouts	Create hosted payment pages
Customers	Manage customer records
Subscriptions	Recurring billing
Subscription Plans	Define subscription products
One-Off Products	Single purchase products
Orders	Transaction records
Refunds	Process refunds
Chargebacks	Handle disputes
Webhooks	Real-time event notifications
Webhook Endpoints	Register delivery endpoints

---

Error handling

The SDK throws specific exceptions for different error types.

Exception types

Name	Type	Description
ApiException	exception	API errors, including authentication, validation, and transport failures.

use Vatly\API\Exceptions\ApiException;

try {
    $checkout = $vatly->checkouts->create([...]);
} catch (ApiException $e) {
    // API error (network, auth, validation, etc.)
    echo $e->getMessage();
}

---

Requirements

• PHP 8.0+
• cURL extension
• JSON extension