README

Официальный PHP SDK для Subster — сервиса для приема платежей, автоплатежей и управления подписками. SDK помогает работать с Subster API из PHP-кода: создавать клиентов, запускать hosted checkout, открывать billing portal, менять тарифы подписок, передавать usage-based использование и получать оплаченные счета.

Полный контракт API, параметры запросов и ответы доступны в официальной API-документации.

Быстрые ссылки

Требования

PHP 8.1 или выше.
Composer.

Установка

composer require subster-payments/php-sdk

Переход со старого имени пакета

Если в проекте уже установлен пакет subster/php-sdk, замените его на новое имя:

composer remove subster/php-sdk --no-update
composer require subster-payments/php-sdk:^1.0 -W

Namespace SDK остается прежним: Subster\PhpSdk.

Laravel Boost и AI skills

Пакет поставляется с Laravel Boost skill для AI-ассистентов. Если в вашем Laravel-приложении установлен Laravel Boost, обновите skills после установки SDK:

php artisan boost:install --skills

После этого AI-ассистент сможет использовать контекст Subster PHP SDK при задачах интеграции платежей, checkout, billing portal, подписок, usage-based billing и оплаченных счетов.

Быстрый старт

Получите API-ключ в Subster и создайте клиент SDK. Ключ передается в API как Bearer token.

use Subster\PhpSdk\SubsterConnector;

$subster = new SubsterConnector('your-api-key');

Минимальный сценарий интеграции обычно состоит из двух шагов: создать клиента Subster и отправить его на hosted checkout для оплаты тарифа.

use Subster\PhpSdk\DataObjects\CreateCheckoutSessionData;
use Subster\PhpSdk\DataObjects\CreateCustomerData;

$customer = $subster->customers()->create(
    CreateCustomerData::from([
        'email' => 'customer@example.ru',
        'name' => 'Иван Петров',
    ])
);

$session = $subster->checkoutSessions()->create(
    CreateCheckoutSessionData::from([
        'customer' => $customer->id,
        'items' => [
            [
                'plan' => 'your-plan-id',
            ],
        ],
        'success_url' => 'https://example.ru/billing/success',
        'cancel_url' => 'https://example.ru/billing/cancel',
    ])
);

// Redirect the customer to $session->url.

Основные сценарии

Клиенты

Создавайте и обновляйте клиентов аккаунта перед оформлением платежей.

use Subster\PhpSdk\DataObjects\CreateCustomerData;
use Subster\PhpSdk\DataObjects\UpdateCustomerData;

$customer = $subster->customers()->create(
    CreateCustomerData::from([
        'email' => 'customer@example.ru',
        'name' => 'Иван Петров',
    ])
);

$updatedCustomer = $subster->customers()->update(
    UpdateCustomerData::from([
        'id' => $customer->id,
        'name' => 'Иван Сергеевич Петров',
    ])
);

Checkout-сессии

Checkout-сессия возвращает URL платежной страницы Subster. В items сейчас передается тариф plan; для разовых оплат и usage-based тарифов можно указать quantity.

use Subster\PhpSdk\DataObjects\CreateCheckoutSessionData;
use Subster\PhpSdk\DataObjects\CreateCheckoutSessionItemData;

$session = $subster->checkoutSessions()->create(
    CreateCheckoutSessionData::from([
        'customer' => 'customer-id',
        'items' => [
            CreateCheckoutSessionItemData::from([
                'plan' => 'your-one-time-plan-id',
                'quantity' => 5,
            ]),
        ],
        'success_url' => 'https://example.ru/billing/success',
        'cancel_url' => 'https://example.ru/billing/cancel',
    ])
);

Raw arrays также поддерживаются:

'items' => [
    [
        'plan' => 'your-one-time-plan-id',
        'quantity' => 5,
    ],
],

Статус checkout-сессии можно получить по ее ID:

$status = $subster->checkoutSessions()->get('checkout-session-id');

Платный trial

Для подписок можно передать данные trial в subscription_data. Допустимые единицы длительности: hour, day, week, month, year.

use Subster\PhpSdk\DataObjects\CheckoutSessionTrialData;
use Subster\PhpSdk\DataObjects\CheckoutSessionTrialDurationData;
use Subster\PhpSdk\DataObjects\CreateCheckoutSessionData;
use Subster\PhpSdk\DataObjects\CreateCheckoutSessionSubscriptionData;

$session = $subster->checkoutSessions()->create(
    CreateCheckoutSessionData::from([
        'customer' => 'customer-id',
        'items' => [
            [
                'plan' => 'your-recurring-plan-id',
            ],
        ],
        'subscription_data' => CreateCheckoutSessionSubscriptionData::from([
            'trial' => CheckoutSessionTrialData::from([
                'amount' => 100,
                'duration' => CheckoutSessionTrialDurationData::from([
                    'unit' => 'day',
                    'count' => 14,
                ]),
            ]),
        ]),
        'success_url' => 'https://example.ru/billing/success',
        'cancel_url' => 'https://example.ru/billing/cancel',
    ])
);

Billing portal

Billing portal позволяет клиенту управлять подпиской, способом оплаты и счетами через hosted-страницу Subster.

use Subster\PhpSdk\DataObjects\CreateBillingPortalSessionData;

$portalSession = $subster->billingPortalSessions()->create(
    CreateBillingPortalSessionData::from([
        'customer' => 'customer-id',
        'return_url' => 'https://example.ru/billing',
    ])
);

// Redirect the customer to $portalSession->url.

Смена тарифа подписки

changePlan меняет тариф подписки. Если требуется доплата, Subster вернет checkout URL.

use Subster\PhpSdk\DataObjects\ChangeSubscriptionPlanData;

$change = $subster->subscriptions()->changePlan(
    'subscription-id',
    ChangeSubscriptionPlanData::from([
        'plan' => 'target-plan-id',
        'success_url' => 'https://example.ru/billing/success',
        'cancel_url' => 'https://example.ru/billing/cancel',
    ])
);

if ($change->mode === 'checkout') {
    // Redirect the customer to $change->url.
}

По умолчанию Subster делает перерасчет при немедленном upgrade и учитывает неиспользованное время текущего периода. Для тарифов-пакетов, где клиент должен оплатить полную стоимость нового тарифа, передайте proration_behavior: none.

$change = $subster->subscriptions()->changePlan(
    'subscription-id',
    ChangeSubscriptionPlanData::from([
        'plan' => 'larger-package-plan-id',
        'success_url' => 'https://example.ru/billing/success',
        'proration_behavior' => 'none',
    ])
);

Usage-based подписки

Для usage-based подписок сначала передайте стартовое quantity при создании checkout-сессии. Для последующих периодов фиксируйте текущее значение использования через recordUsage. quantity — это абсолютный snapshot использования, а не дельта.

use Subster\PhpSdk\DataObjects\CreateCheckoutSessionData;
use Subster\PhpSdk\DataObjects\RecordSubscriptionUsageEventData;

$session = $subster->checkoutSessions()->create(
    CreateCheckoutSessionData::from([
        'customer' => 'customer-id',
        'items' => [
            [
                'plan' => 'your-usage-based-plan-id',
                'quantity' => 20,
            ],
        ],
        'success_url' => 'https://example.ru/billing/success',
        'cancel_url' => 'https://example.ru/billing/cancel',
    ])
);

$event = $subster->subscriptions()->recordUsage(
    'subscription-id',
    RecordSubscriptionUsageEventData::from([
        'quantity' => 35,
        'occurred_at' => '2026-01-16T10:30:00+00:00',
        'idempotency_key' => 'tenant-users-2026-01-16',
        'metadata' => ['source' => 'tenant-admin'],
    ])
);

Оплаченные счета

Получайте оплаченные счета с фильтрами по клиенту, подписке и дате оплаты. Ответ включает данные клиента, подписки и позиции счета.

use Subster\PhpSdk\DataObjects\ListInvoicesData;

$invoices = $subster->invoices()->all(ListInvoicesData::from([
    'customer' => 'customer-id',
    'paid_at_gte' => '2026-01-01',
    'paid_at_lte' => '2026-01-31',
    'limit' => 10,
]));

foreach ($invoices->data as $invoice) {
    // $invoice->customer, $invoice->subscription, and $invoice->items are included.
}

Если $invoices->has_more равен true, запросите следующую страницу с ID последнего счета:

$nextPage = $subster->invoices()->all(ListInvoicesData::from([
    'starting_after' => $invoices->data->items[array_key_last($invoices->data->items)]->id,
]));

Позиции счета содержат nullable поле $item->pricing_model. Для usage-based счетов metadata может включать детали backend meter и snapshot использования, по которому был сформирован счет.

Ошибки и полный API-контракт

SDK использует Saloon и выбрасывает исключения для неуспешных HTTP-ответов. Для обработки ошибок ориентируйтесь на статус API-ответа и тело ошибки Subster.

Полный список endpoint-ов, обязательные поля, форматы дат, варианты валидационных ошибок и webhook-сценарии смотрите в официальной API-документации.

Тесты

composer test

Changelog

Список изменений находится в CHANGELOG.

License

The MIT License (MIT). See License File for more information.

subster-payments/php-sdk

包简介

关键字：

README 文档