README

PHP-клиент для CloudPayments API. Пакет предоставляет DTO для запросов, DTO для ответов, обработку HTTP-запросов через Guzzle и классы для данных webhook-уведомлений.

Проект основан на кодовой базе flowwow/cloudpayments-php-client, развивается независимо и использует namespace Excent\Cloudpayments.

Оглавление

• Требования
• Установка
• Быстрый старт
• 3-D Secure
• Поддерживаемые методы
• Запросы
• Ответы
• Уведомления
• Идемпотентность
• Обработка ошибок
• Разработка
• Версионирование
• License

Требования

• PHP ^8.1
• Guzzle ^7.4
• Composer

Установка

composer require axcherednikov/cloudpayments-php-client

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

<?php

declare(strict_types=1);

use Excent\Cloudpayments\Library;
use Excent\Cloudpayments\Request\CardsPayment;

require __DIR__ . '/vendor/autoload.php';

$client = new Library(
    $_ENV['CLOUDPAYMENTS_PUBLIC_ID'],
    $_ENV['CLOUDPAYMENTS_API_PASSWORD']
);

$request = new CardsPayment(
    100.00,
    'RUB',
    '127.0.0.1',
    'CARD_CRYPTOGRAM_PACKET'
);

$response = $client->paymentsCardsCharge($request);

if ($response->success) {
    echo $response->model->transactionId;
}

Если нужно переопределить endpoint CloudPayments, передайте URL третьим аргументом конструктора:

$client = new Library($publicId, $apiPassword, $customApiUrl);

3-D Secure

Методы paymentsCardsCharge() и createPaymentByCard2Step() возвращают TransactionWith3dsResponse. Если требуется 3-D Secure, is3dsError() вернет true, а данные для перенаправления будут доступны в model.

use Excent\Cloudpayments\Request\Post3DS;

$response = $client->paymentsCardsCharge($request);

if ($response->is3dsError()) {
    $acsUrl = $response->model->acsUrl;
    $paReq = $response->model->paReq;
    $transactionId = $response->model->transactionId;

    // Передайте пользователя на страницу ACS банка, затем обработайте PaRes.
    $client->post3Ds(new Post3DS($transactionId, 'PARES_FROM_ACS'));
}

Поддерживаемые методы

Библиотека работает с методами из CloudPayments API через request/response DTO.

Запросы

Параметры API передаются через DTO из namespace Excent\Cloudpayments\Request.

use Excent\Cloudpayments\Request\ApplepayStartSession;

$request = new ApplepayStartSession(
    'https://apple-pay-gateway.apple.com/paymentservices/startSession'
);

$response = $client->startSession($request);

DTO наследуются от BaseRequest и преобразуются в формат CloudPayments через asArray():

• amount превращается в Amount;
• значения null не попадают в запрос;
• true и false передаются как строковые значения, ожидаемые API;
• вложенные DTO и массивы DTO преобразуются рекурсивно.

Некоторые DTO для совместимости с существующим публичным контрактом заполняются через публичные свойства:

use Excent\Cloudpayments\Request\NotificationsUpdate;

$request = new NotificationsUpdate();
$request->type = 'pay';
$request->isEnabled = true;
$request->address = 'https://example.com/cloudpayments/pay';

$client->siteNotificationsUpdate($request);

Ответы

Все response DTO наследуются от CloudResponse.

Поддерживаемые модели:

Если CloudPayments вернет поля, которых нет в модели, они будут доступны через getAdditionalProperties().

$extra = $response->model->getAdditionalProperties();

Уведомления

Библиотека включает DTO для данных webhook-уведомлений. Классы мапят поля CloudPayments вида TransactionId в свойства вида transactionId.

use Excent\Cloudpayments\Hook\HookPay;

$hook = new HookPay($_POST);

echo $hook->transactionId;

Классы уведомлений:

Webhook DTO только преобразуют входные данные в объект. Проверку подписи, бизнес-валидацию и формирование ответа для CloudPayments нужно реализовать на стороне приложения.

Идемпотентность

Для идемпотентных запросов библиотека отправляет заголовок X-Request-ID.

Автоматический ключ строится из метода и данных запроса:

$client->setIdempotency(true);

$response = $client->createPaymentByCard2Step($request);

Можно задать ключ явно:

$client->setIdempotencyKey('order-100500-auth');

$response = $client->createPaymentByCard2Step($request);

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

Request DTO могут выбрасывать BadTypeException, если переданы некорректные значения. HTTP-слой может выбросить исключения Guzzle, а разбор JSON - JsonException.

use Excent\Cloudpayments\Exceptions\BadTypeException;
use GuzzleHttp\Exception\GuzzleException;

try {
    $response = $client->paymentsRefund($request);
} catch (BadTypeException $exception) {
    // Некорректные параметры request DTO.
} catch (GuzzleException $exception) {
    // Ошибка HTTP-запроса.
} catch (JsonException $exception) {
    // Ответ API не удалось разобрать как JSON.
}

Разработка

composer install
composer bin phpstan install
composer bin rector install
composer bin php-cs-fixer install

composer test
make phpstan
make rector
make lint

Полезные команды:

CI запускает тесты на поддерживаемых версиях PHP и отдельные quality checks для PHPStan, Rector и PHP CS Fixer.

Версионирование

Проект следует SemVer:

• patch-релизы исправляют ошибки, документацию, тесты и статический анализ без изменения публичного контракта;
• minor-релизы могут добавлять новые методы и DTO обратно совместимым образом;
• major-релизы могут содержать несовместимые изменения.

License

MIT. See LICENSE.