parazeet/paymaster_api_php_sdk

paymaster_api_php_sdk

v1.1 2026-07-08 11:40 UTC

Requires

• php: ^8.1
• guzzlehttp/guzzle: ^7.0

MIT

• parazeet

Published on Packagist.org on 2026-07-08 12:56 UTC

README

PHP SDK для PayMaster API v2.

Requirements

• PHP ^8.1
• guzzlehttp/guzzle ^7.0

Installation

composer require "parazeet/paymaster_api_php_sdk"

Setup

Создайте клиент с API-ключом (токены в кабинете). Для POST-запросов рекомендуется передавать Idempotency-Key (например через ramsey/uuid).

use parazeet\PayMaster\PayMasterApi;
use parazeet\PayMaster\Config\Config;
use parazeet\PayMaster\Validator\ResponseValidator;
use Ramsey\Uuid\Uuid;

$api = new PayMasterApi(
    new Config('YOUR_API_KEY', Uuid::uuid4()->toString()),
    new ResponseValidator()
);

Базовый URL: https://paymaster.ru/api/v2/.

Available methods

Method	HTTP	Returns
$api->post($request)	POST /{resource}/	Response
$api->getId($request, $id)	GET /{resource}/{id}	Response
$api->getQuery($request, $query)	GET /{resource}/?...	Response (list items)
$api->put($request, $id, $type?)	PUT /{resource}/{id}[/{type}]	Response или true

Поведение put()

Вызов	Endpoint	Успешный ответ
put($payment, $id, 'complete')	PUT /payments/{id}/complete	PaymentResponse (JSON body)
put($payment, $id, 'confirm')	PUT /payments/{id}/confirm	true (пустой HTTP 200)
put($payment, $id, 'cancel')	PUT /payments/{id}/cancel	true
put($token, $id, 'complete')	PUT /paymenttokens/{id}/complete	PaymentTokenResponse
put($token, $id, 'revoke')	PUT /paymenttokens/{id}/revoke	true
put($sticker->active(false), $id)	PUT /stickers/{id}	true

$type опциональный: если null, вызывается PUT /{resource}/{id} без суффикса (для активации стикеров).

Request classes

Class	Resource	Typical operations
InvoiceRequest	invoices	создание ссылки на оплату
PaymentRequest	payments	create / get / list / complete / confirm / cancel
RefundRequest	refunds	create / get / list
TokenizationRequest	tokenization	ссылка на привязку карты
PaymentTokenRequest	paymenttokens	create / get / complete / revoke
ReceiptRequest	receipts	create / get / list
StickerRequest	stickers	create / get / list / activate

Examples

Invoice (ссылка на оплату)

use parazeet\PayMaster\Requests\InvoiceRequest;

$invoice = (new InvoiceRequest())
    ->merchantId('YOUR_MERCHANT_ID')
    ->testMode(true)
    ->invoice(['description' => 'test payment'])
    ->amount(['value' => 11, 'currency' => 'RUB'])
    ->paymentMethod('BankCard')
    ->protocol([
        'returnUrl' => 'https://example.com/return',
        'callbackUrl' => 'https://example.com/callback',
    ])
    ->customer([
        'email' => '[e-mail]',
        'phone' => '79081234567',
        'account' => 'user-1',
    ]);

$response = $api->post($invoice);
// $response->invoice->paymentId, $response->invoice->url

Payment — создание

use parazeet\PayMaster\Requests\PaymentRequest;

$payment = (new PaymentRequest())
    ->merchantId('YOUR_MERCHANT_ID')
    ->invoice(['description' => 'test payment'])
    ->amount(['value' => 10.50, 'currency' => 'RUB'])
    ->paymentData([
        'paymentMethod' => 'BankCard',
        'token' => ['id' => 'TOKEN_ID'],
    ])
    ->protocol([
        'returnUrl' => 'https://example.com/return',
        'callbackUrl' => 'https://example.com/callback',
        'threeDSCompleteUrl' => 'https://example.com/3ds-complete',
    ]);

$response = $api->post($payment);

Payment — get / list

$response = $api->getId(new PaymentRequest(), '12769');
// $response->payments->completed — дата завершения (если есть)

$list = $api->getQuery(new PaymentRequest(), [
    'merchantId' => 'YOUR_MERCHANT_ID',
    'start' => '2021-08-01T06:00:00Z',
    'end' => '2021-08-01T06:30:00Z',
]);
// $list->payments — массив Payment
// $list->cursor — указатель следующей страницы или null

// Следующая страница:
if ($list->cursor !== null) {
    $list = $api->getQuery(new PaymentRequest(), [
        'merchantId' => 'YOUR_MERCHANT_ID',
        'start' => '2021-08-01T06:00:00Z',
        'end' => '2021-08-01T06:30:00Z',
        'cursor' => $list->cursor,
    ]);
}

Payment — complete (3DS) / confirm (capture) / cancel

// Complete — API возвращает детали платежа
$complete = (new PaymentRequest())->completeData([
    'PARes' => '...',
    // или: 'cres', 'code', 'threeDSCompInd'
]);
$paymentResponse = $api->put($complete, '12769', 'complete');

// Confirm (capture) — пустой 200 → true
$confirm = (new PaymentRequest())->confirmData([
    'amount' => ['value' => 10.50, 'currency' => 'RUB'],
]);
$ok = $api->put($confirm, '12769', 'confirm');

// Cancel
$ok = $api->put(new PaymentRequest(), '12769', 'cancel');

Для complete / confirm в toArray() попадает только соответствующий action-payload (completeData / confirmData), не create-тело платежа.

Tokenization (ссылка на привязку)

use parazeet\PayMaster\Requests\TokenizationRequest;

$tokenLink = (new TokenizationRequest())
    ->merchantId('YOUR_MERCHANT_ID')
    ->type('recurring')
    ->purpose('Подписка')
    ->paymentMethod('bankcard')
    ->customer(['account' => 'user-1']);

$response = $api->post($tokenLink);
// $response->tokenization->tokenId, $response->tokenization->url

Payment token — создание / get / complete / revoke

use parazeet\PayMaster\Requests\PaymentTokenRequest;

// Create
$create = (new PaymentTokenRequest())
    ->merchantId('YOUR_MERCHANT_ID')
    ->type('recurring')
    ->purpose('Подписка')
    ->paymentData(['paymentMethod' => 'sbp'])
    ->customer(['account' => 'user-1'])
    ->protocol([
        'returnUrl' => 'https://example.com/return',
        'callbackUrl' => 'https://example.com/token-callback',
    ]);

$tokenResponse = $api->post($create);
// $tokenResponse->paymentToken->id
// $tokenResponse->paymentToken->status
// $tokenResponse->paymentToken->confirmation  // External / 3DS и т.д.

// Get
$tokenResponse = $api->getId(new PaymentTokenRequest(), 'TOKEN_ID');

// Complete (3DS)
$complete = (new PaymentTokenRequest())->completeData(['PARes' => '...']);
$tokenResponse = $api->put($complete, 'TOKEN_ID', 'complete');

// Revoke
$ok = $api->put(new PaymentTokenRequest(), 'TOKEN_ID', 'revoke');

Receipt (чеки)

Resource: receipts (POST/GET /api/v2/receipts).

use parazeet\PayMaster\Requests\ReceiptRequest;

$receipt = (new ReceiptRequest())
    ->paymentId('13167')
    ->amount(['value' => 10, 'currency' => 'RUB'])
    ->type('Payment')
    ->client(['email' => '[e-mail]'])
    ->items([
        [
            'name' => 'Услуга',
            'quantity' => 1,
            'price' => 10,
            'vatType' => 'None',
            'paymentSubject' => 'Service',
            'paymentMethod' => 'FullPrepayment',
        ],
        // ...дополнительные позиции
    ])
    ->settlements([
        'cashless' => 10,
        // 'advance' => 0,
        // 'loan' => 0,
        // 'consideration' => 0,
    ]);

$response = $api->post($receipt);
// $response->receipt->providerOperationId
// $response->receipt->fiscalData  // fiscalDeviceId, shiftNumber, receiptNumber, ...

// Одна позиция также поддерживается (будет обёрнута в массив):
// ->items(['name' => '...', 'quantity' => 1, ...])

Sticker — создание / активация

use parazeet\PayMaster\Requests\StickerRequest;

$sticker = (new StickerRequest())
    ->merchantId('YOUR_MERCHANT_ID')
    ->stickerType('Sbp')
    ->paymentPurpose('Оплата товара')
    ->amount(['value' => 39.90, 'currency' => 'RUB']);

$response = $api->post($sticker);
// $response->sticker->id, $response->sticker->payload

// Activate / deactivate: PUT /stickers/{id} с body {"active": bool}
$ok = $api->put((new StickerRequest())->active(true), $stickerId);
$ok = $api->put((new StickerRequest())->active(false), $stickerId);

Не передавайте третьим аргументом 'active' — согласно API путь без суффикса: PUT /stickers/{id}.

Свойство ответа: $response->sticker (раньше ошибочно называлось $receipt).

Refund

use parazeet\PayMaster\Requests\RefundRequest;

$refund = (new RefundRequest())
    ->paymentId('12870')
    ->amount(['value' => 5.5, 'currency' => 'RUB']);

$response = $api->post($refund);

Error handling

При ошибке API SDK выбрасывает исключения из parazeet\PayMaster\Exceptions\* (например ErrorContentFormatException, ErrorUnauthorizedException, UnknownCodeException, EmptyResponseException, PayMasterHttpException, ErrorSyntaxException).

Валидация ошибок срабатывает только для error-envelope {code, message, errors?} — успешный платёж/refund с полем resultCode (без верхнего code) исключения не бросает.

Известные коды ошибок API (validation_error, not_authorized, idempotency_key_violation, invalid_operation, payment_token_revoked, payment_token_blocked) и коды авторизации — мапятся в ResponseValidator.

HTTP-статус вне 2xx → PayMasterHttpException (доступны statusCode(), responseBody()).

Пустой body на GET/POST или невалидный JSON → PayMasterHttpException / ErrorSyntaxException.

Notes

• SSL verification включён (verify => true).
• Таймауты по умолчанию: timeout = 10s, connect_timeout = 5s.
• Idempotency-Key передаётся только в POST (через Config); GET/PUT — без этого заголовка.
• Для POST/PUT всегда выставляется Content-Type: application/json.
• Булевы флаги (testMode, dualMode, cashlink, active) сериализуются через isset — явное false попадает в JSON.
• В receipt поддерживается опциональный блок settlements (cashless, advance, loan, consideration) — в InvoiceRequest / PaymentRequest / RefundRequest / ReceiptRequest::settlements().
• Списки (getQuery): ответ содержит items и опциональный cursor — $response->cursor; следующую страницу запрашивайте с 'cursor' => $response->cursor.
• Поля list-ответов парсятся null-safe (?? null) — отсутствие опциональных ключей не падает.