Payout

PHP

PHP SDK для интеграции с Payment Easy Payout API.

PHP

PHP SDK для интеграции с Payment Easy Payout API.

Установка

git clone https://github.com/unitewt/sdk-payout.git
cd sdk-payout/php
composer install

Требования

PHP >= 8.1
Расширения: openssl, curl, simplexml

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

<?php

require_once 'vendor/autoload.php';

use PayoutSDK\Config;
use PayoutSDK\PayoutClient;
use PayoutSDK\Enums\ServiceCode;
use PayoutSDK\Enums\BankCode;

$config = new Config(
    baseUrl: 'https://your-server.example.com',
    username: 'your_username',
    privateKeyPem: file_get_contents('private-key.pem'),
);

$client = new PayoutClient($config);

// Запрос баланса
$balance = $client->balance();
echo "Баланс: {$balance->balance} копеек\n";

// Выплата на карту
$resp = $client->payment(
    id: 'unique-tx-id',
    sum: 100000, // 1000 рублей в копейках
    service: ServiceCode::BANK_CARD,
    account: '4277255555555555',
    date: new \DateTime(),
    phone: '79999999999',
);

if ($resp->isFinal()) {
    echo "Успех: " . ($resp->isSuccessful() ? 'да' : 'нет') . "\n";
}

// Проверка статуса
$status = $client->getStatus('unique-tx-id');
echo "code={$status->code}, state={$status->state}, final={$status->final}\n";

Конфигурация

$config = new Config(
    baseUrl: 'https://your-server.example.com',
    username: 'your_username',
    privateKeyPem: file_get_contents('private-key.pem'),
    serverPublicKeyPem: file_get_contents('server-public-key.pem'), // опционально
    timeoutSeconds: 300, // по умолчанию 300
);

Параметр	Тип	Обязательный	По умолчанию	Описание
`baseUrl`	`string`	да	—	URL сервера
`username`	`string`	да	—	Имя пользователя
`privateKeyPem`	`string`	да	—	RSA приватный ключ (PEM)
`serverPublicKeyPem`	`?string`	нет	`null`	Публичный ключ сервера
`timeoutSeconds`	`int`	нет	`300`	cURL таймаут (секунды)

API

`PayoutClient`

Метод	Описание	Возвращает
`balance()`	Запрос баланса	`BalanceResponse`
`payment(...)`	Выполнение выплаты	`PaymentResponse`
`getStatus($txId)`	Проверка статуса	`PaymentResponse`

Параметры `payment()`

Параметр	Тип	Обязательный	Описание
`$id`	`string`	да	Уникальный ID транзакции (до 64 байт)
`$sum`	`int`	да	Сумма в копейках
`$service`	`ServiceCode`	да	Тип сервиса
`$account`	`string`	да	Номер карты / телефона / кошелька
`$date`	`\DateTimeInterface`	да	Дата транзакции
`$phone`	`string`	да	Телефон плательщика
`$payeeBankCode`	`?string`	нет	Код банка получателя (для СБП)

`PaymentResponse`

Свойство/Метод	Тип	Описание
`$id`	`string`	Ваш ID транзакции
`$code`	`int`	Код результата
`$state`	`int`	Состояние платежа
`$final`	`int`	1 = финальный статус
`$trans`	`string`	ID транзакции на стороне шлюза
`$fee`	`?int`	Комиссия в копейках
`$errorDescription`	`?string`	Описание ошибки
`isSuccessful()`	`bool`	code=0, state=60, final=1
`isFailed()`	`bool`	code=20, state=80, final=1
`isNotFound()`	`bool`	code=15, state=-2, final=1
`isProcessing()`	`bool`	code=1, state=40, final=0
`isFinal()`	`bool`	final=1

`BalanceResponse`

Свойство	Тип	Описание
`$balance`	`int`	Баланс в копейках
`$overdraft`	`int`	Овердрафт в копейках

Сервисы

ServiceCode::BANK_CARD    // 24 — банковские карты
ServiceCode::QIWI_WALLET  // 25 — кошельки QIWI
ServiceCode::SBP           // 26 — СБП
ServiceCode::MOBILE_PHONE  // 28 — мобильные телефоны

Коды банков (СБП)

BankCode::SBERBANK_OF_RUSSIA  // '100000000111'
BankCode::TINKOFF_BANK        // '100000000004'
BankCode::ALFA_BANK           // '100000000008'
// ... 238 банков

Выплата через СБП

$resp = $client->payment(
    id: 'sbp-tx-id',
    sum: 50000,
    service: ServiceCode::SBP,
    account: '79876543210',
    date: new \DateTime(),
    phone: '79999999999',
    payeeBankCode: BankCode::SBERBANK_OF_RUSSIA->value,
);

Обработка ошибок

SDK определяет три класса исключений:

PayoutException — базовый класс (extends \RuntimeException)
ApiException — ошибки API (свойства: $transactionId, $statusCode)
SignatureException — ошибки подписи

use PayoutSDK\Exceptions\ApiException;
use PayoutSDK\Exceptions\SignatureException;

try {
    $resp = $client->payment(...);
} catch (ApiException $e) {
    echo "API ошибка: {$e->getMessage()}, status={$e->statusCode}\n";
} catch (SignatureException $e) {
    echo "Ошибка подписи: {$e->getMessage()}\n";
}

Примеры

examples/generate_keys.php — генерация RSA-ключей
examples/integration_test.php — полный интеграционный тест

export PAYOUT_BASE_URL="https://your-server.example.com"
export PAYOUT_USERNAME="your_username"
export PAYOUT_PRIVATE_KEY_PATH="./private-key.pem"

php examples/integration_test.php

Node.js

Node.js SDK для интеграции с Payment Easy Payout API.

Python

Python SDK для интеграции с Payment Easy Payout API.