avlyalin/laravel-sberbank-acquiring

Provides functionality to interoperate with Sberbank acquiring system

Maintainers

Details

github.com/avlyalin/laravel-sberbank-acquiring

Source

Issues

Installs: 1 743

Dependents: 0

Suggesters: 0

Security: 0

Stars: 20

Watchers: 5

Forks: 11

Open Issues: 2

0.1.2 2020-07-27 20:32 UTC

Requires

Requires (Dev)

MIT aef993a2778cca222662c19c94b994225866860a

  • Aleksey Lyalin <lyalin.alexey.woop@gmail.com>

restapiclientlaravelsberbankacquiring

This package is auto-updated.

Last update: 2025-04-28 07:00:20 UTC

README

CI codecov MIT license

Пакет предоставляет вашему приложению функциональность для работы с платежами с использованием эквайринга от Сбербанка. Возможности:

  • Создание и хранение платежей
  • Логирование операций по платежам

Перед использованием рекомендуется ознакомиться с документацией, предоставляемой Сбербанком.

Требования

  • PHP >= 7.2
  • Laravel >= 5.8
  • Расширения PHP: ext-json, ext-curl
  • Реляционная БД

Установка

Добавьте пакет в зависимости:

composer require avlyalin/laravel-sberbank-acquiring

Опубликуйте файл настроек:

php artisan vendor:publish --provider="Avlyalin\SberbankAcquiring\Providers\AcquiringServiceProvider" --tag=config

Запустите миграции:

php artisan migrate

Обзор

Таблицы

Для хранения истории платежей и операций создаётся несколько таблиц:

  • acquiring_payments - базовая таблица платежей, хранит общую информацию по платежам всех платежных систем
  • acquiring_payment_operations - операции по платежам
  • acquiring_sberbank_payments - платежи напрямую через систему Сбербанка
  • acquiring_apple_pay_payments - платежи через Apple Pay
  • acquiring_samsung_pay_payments - платежи через Samsung Pay
  • acquiring_google_pay_payments - платежи через Google Pay
  • acquiring_payment_statuses - справочник статусов платежей
  • acquiring_payment_operation_types - справочник типов операций
  • acquiring_payment_systems - справочник платежных систем

Диаграмма: screenshot of conversion

Связь базового платежа и платежей в разных платежных системах организована на уровне ORM через полиморфную связь.

Клиент

Пакет содержит два класса-клиента для работы с эквайрингом:

  • ApiClient - вызывает API Сбербанка
  • Client - обёртка для ApiClient, сохраняет платежи и операции в БД, использует файл настроек. Рекомендуется пользоваться им.

ApiClient и Client добавлены в Service Container и могут быть использованы в Dependency Injection. Резолвинг классов:

use Avlyalin\SberbankAcquiring\Client\ApiClient;
use Avlyalin\SberbankAcquiring\Client\Client;

$client = $this->app->make(Client::class);

$apiClient = $this->app->make(ApiClient::class);

Операции

На данный момент поддерживаются следующие операции эквайринга:

Операция Документация Сбербанка
Регистрация заказа Ссылка
Регистрация заказа с предавторизацией Ссылка
Запрос завершения оплаты заказа Ссылка
Запрос отмены оплаты заказа Ссылка
Запрос возврата средств оплаты заказа Ссылка
Получение статуса заказа Ссылка
Запрос оплаты через Apple Pay Ссылка
Запрос оплаты через Samsung Pay Ссылка
Запрос оплаты через Google Pay Ссылка
Запрос сведений о кассовом чеке Ссылка
Запрос деактивации связки Ссылка
Запрос активации связки Ссылка
Запрос списка всех связок клиента Ссылка
Запрос списка связок определённой банковской карты Ссылка
Запрос изменения срока действия связки Ссылка

Регистрация заказа

Обязательный аргумент - сумма.

use Avlyalin\SberbankAcquiring\Client\HttpClientInterface;
use Avlyalin\SberbankAcquiring\Client\Client;

$client = $this->app->make(Client::class);
$acquiringPayment = $client->register(
    1000, // сумма
    ['orderNumber' => '123-456'], // необязательные параметры
    HttpClientInterface::METHOD_GET, // метод запроса
    ['Cache-Control' => 'no-cache'] // хэдеры запроса
);
$status = $acquiringPayment->status->name; // 'Зарегистрирован'

Если во втором аргументе не указаны параметры returnUrl и failUrl, то они берутся из файла настроек.

Регистрация заказа с предавторизацией

Обязательный аргумент - сумма.

use Avlyalin\SberbankAcquiring\Client\HttpClientInterface;
use Avlyalin\SberbankAcquiring\Client\Client;

$client = $this->app->make(Client::class);
$acquiringPayment = $client->registerPreAuth(
    1000, // сумма
    ['orderNumber' => '123-456'], // необязательные параметры
    HttpClientInterface::METHOD_GET, // метод запроса
    ['Cache-Control' => 'no-cache'] // хэдеры запроса
);
$status = $acquiringPayment->status->name; // 'Зарегистрирован'

Если во втором аргументе не указаны параметры returnUrl и failUrl, то они берутся из файла настроек.

Запрос завершения оплаты заказа

Обязательные аргументы: id модели платежа (AcquiringPayment), сумма.

use Avlyalin\SberbankAcquiring\Client\HttpClientInterface;
use Avlyalin\SberbankAcquiring\Client\Client;

$client = $this->app->make(Client::class);
$acquiringPayment = $client->deposit(
    1, // id модели платежа (AcquiringPayment)
    1000, // сумма
    [], // необязательные параметры
    HttpClientInterface::METHOD_GET, // метод запроса
    ['Cache-Control' => 'no-cache'] // хэдеры запроса
);

Запрос отмены оплаты заказа

Обязательный аргумент - id модели платежа (AcquiringPayment).

use Avlyalin\SberbankAcquiring\Client\HttpClientInterface;
use Avlyalin\SberbankAcquiring\Client\Client;

$client = $this->app->make(Client::class);
$acquiringPayment = $client->reverse(
    1, // id модели платежа (AcquiringPayment)
    ['language' => 'EN'], // необязательные параметры
    HttpClientInterface::METHOD_GET, // метод запроса
    ['Cache-Control' => 'no-cache'] // хэдеры запроса
);

Запрос возврата средств оплаты заказа

Обязательные аргументы: id модели платежа (AcquiringPayment), сумма.

use Avlyalin\SberbankAcquiring\Client\HttpClientInterface;
use Avlyalin\SberbankAcquiring\Client\Client;

$client = $this->app->make(Client::class);
$acquiringPayment = $client->refund(
    1, // id модели платежа (AcquiringPayment)
    500, // сумма
    ['language' => 'EN'], // необязательные параметры
    HttpClientInterface::METHOD_GET, // метод запроса
    ['Cache-Control' => 'no-cache'] // хэдеры запроса
);

Получение статуса заказа

Обязательный аргумент - id модели платежа (AcquiringPayment).

use Avlyalin\SberbankAcquiring\Client\HttpClientInterface;
use Avlyalin\SberbankAcquiring\Client\Client;

$client = $this->app->make(Client::class);
$acquiringPayment = $client->getOrderStatusExtended(
    1, // id модели платежа (AcquiringPayment)
    ['language' => 'EN'], // необязательные параметры
    HttpClientInterface::METHOD_GET, // метод запроса
    ['Cache-Control' => 'no-cache'] // хэдеры запроса
);

Запрос оплаты через Apple Pay

Обязательный аргумент - paymentToken, полученный от системы Apple Pay. Подробнее здесь.

use Avlyalin\SberbankAcquiring\Client\HttpClientInterface;
use Avlyalin\SberbankAcquiring\Client\Client;

$client = $this->app->make(Client::class);
$acquiringPayment = $client->payWithApplePay(
    'vnkXadsIDvejvKQPvcxbTqeEhfbPOG', // Токен, полученный от системы Apple Pay
    [ // необязательные параметры
        'orderNumber' => '123_abc',
        'language' => 'EN',
        'description' => 'payment description',
    ],
    HttpClientInterface::METHOD_GET, // метод запроса
    ['Cache-Control' => 'no-cache'] // хэдеры запроса
);

Запрос оплаты через Samsung Pay

Обязательный аргумент - paymentToken, полученный от системы Samsung Pay. Подробнее здесь.

use Avlyalin\SberbankAcquiring\Client\HttpClientInterface;
use Avlyalin\SberbankAcquiring\Client\Client;

$client = $this->app->make(Client::class);
$acquiringPayment = $client->payWithSamsungPay(
    'vnkXadsIDvejvKQPvcxbTqeEhfbPOG', // Токен, полученный от системы Samsung Pay
    [ // необязательные параметры
        'orderNumber' => '123_abc',
        'language' => 'EN',
        'description' => 'payment description',
    ],
    HttpClientInterface::METHOD_GET, // метод запроса
    ['Cache-Control' => 'no-cache'] // хэдеры запроса
);

Запрос оплаты через Google Pay

Обязательные аргументы: paymentToken, полученный от системы Google Pay, сумма. Подробнее здесь.

use Avlyalin\SberbankAcquiring\Client\HttpClientInterface;
use Avlyalin\SberbankAcquiring\Client\Client;

$client = $this->app->make(Client::class);
$acquiringPayment = $client->payWithGooglePay(
    'vnkXadsIDvejvKQPvcxbTqeEhfbPOG', // Токен, полученный от системы Google Pay
    1000,
    [ // необязательные параметры
        'orderNumber' => '123_abc',
        'language' => 'EN',
        'description' => 'payment description',
    ],
    HttpClientInterface::METHOD_GET, // метод запроса
    ['Cache-Control' => 'no-cache'] // хэдеры запроса
);

Запрос сведений о кассовом чеке

Описание здесь.

use Avlyalin\SberbankAcquiring\Client\HttpClientInterface;
use Avlyalin\SberbankAcquiring\Client\ApiClient;

$apiClient = $this->app->make(ApiClient::class);
$response = $apiClient->getReceiptStatus(
    [ // параметры
        'orderId' => 'kvp431_Wmvx_gqQx',
        'language' => 'EN'
    ],
    HttpClientInterface::METHOD_GET, // метод запроса
    ['Cache-Control' => 'no-cache'] // хэдеры запроса
);

if ($response->isOk) {
    print_r($response->getResponseArray());
} else {
    print_r($response->getErrorMessage());
}

Запрос активации связки

Обязательный аргумент - идентификатор созданной ранее связки. Подробнее здесь.

use Avlyalin\SberbankAcquiring\Client\HttpClientInterface;
use Avlyalin\SberbankAcquiring\Client\ApiClient;

$apiClient = $this->app->make(ApiClient::class);
$response = $apiClient->bindCard(
    '131-cvlg-1vcvc-14cvx', // id связки
    [], // необязательные параметры
    HttpClientInterface::METHOD_GET, // метод запроса
    ['Cache-Control' => 'no-cache'] // хэдеры запроса
);

if ($response->isOk) {
    print_r($response->getResponseArray());
} else {
    print_r($response->getErrorMessage());
}

Запрос деактивации связки

Обязательный аргумент - идентификатор созданной ранее связки. Подробнее здесь.

use Avlyalin\SberbankAcquiring\Client\HttpClientInterface;
use Avlyalin\SberbankAcquiring\Client\ApiClient;

$apiClient = $this->app->make(ApiClient::class);
$response = $apiClient->unBindCard(
    '131-cvlg-1vcvc-14cvx', // id связки
    [], // необязательные параметры
    HttpClientInterface::METHOD_GET, // метод запроса
    ['Cache-Control' => 'no-cache'] // хэдеры запроса
);

if ($response->isOk) {
    print_r($response->getResponseArray());
} else {
    print_r($response->getErrorMessage());
}

Запрос списка всех связок клиента

Обязательный аргумент - номер (идентификатор) клиента в системе магазина. Подробнее здесь.

use Avlyalin\SberbankAcquiring\Client\HttpClientInterface;
use Avlyalin\SberbankAcquiring\Client\ApiClient;

$apiClient = $this->app->make(ApiClient::class);
$response = $apiClient->getBindings(
    'client-id-1', // номер (идентификатор) клиента
    [], // необязательные параметры
    HttpClientInterface::METHOD_GET, // метод запроса
    ['Cache-Control' => 'no-cache'] // хэдеры запроса
);

if ($response->isOk) {
    print_r($response->getResponseArray());
} else {
    print_r($response->getErrorMessage());
}

Запрос списка связок определённой банковской карты

Описание здесь.

use Avlyalin\SberbankAcquiring\Client\HttpClientInterface;
use Avlyalin\SberbankAcquiring\Client\ApiClient;

$apiClient = $this->app->make(ApiClient::class);
$response = $apiClient->getBindingsByCardOrId(
    'client-id-1', // номер (идентификатор) клиента
    [], // необязательные параметры
    HttpClientInterface::METHOD_GET, // метод запроса
    ['Cache-Control' => 'no-cache'] // хэдеры запроса
);

if ($response->isOk) {
    print_r($response->getResponseArray());
} else {
    print_r($response->getErrorMessage());
}

Запрос изменения срока действия связки

Обязательный аргумент - идентификатор созданной ранее связки. Подробнее здесь.

use Avlyalin\SberbankAcquiring\Client\HttpClientInterface;
use Avlyalin\SberbankAcquiring\Client\ApiClient;

$apiClient = $this->app->make(ApiClient::class);
$response = $apiClient->getBindingsByCardOrId(
    '131-cvlg-1vcvc-14cvx', // id связки
    [ // параметры
        'newExpiry' => 202012,
    ],
    HttpClientInterface::METHOD_GET, // метод запроса
    ['Cache-Control' => 'no-cache'] // хэдеры запроса
);

if ($response->isOk) {
    print_r($response->getResponseArray());
} else {
    print_r($response->getErrorMessage());
}

Запрос проверки вовлечённости карты в 3DS

Обязательный аргумент - маскированный номер карты, которая использовалась для оплаты (PAN). Подробнее здесь.

use Avlyalin\SberbankAcquiring\Client\HttpClientInterface;
use Avlyalin\SberbankAcquiring\Client\ApiClient;

$apiClient = $this->app->make(ApiClient::class);
$response = $apiClient->verifyEnrollment(
    '4111111111111111', // номер карты
    HttpClientInterface::METHOD_GET, // метод запроса
    ['Cache-Control' => 'no-cache'] // хэдеры запроса
);

if ($response->isOk) {
    print_r($response->getResponseArray());
} else {
    print_r($response->getErrorMessage());
}

Настройки

Ознакомьтесь с файлом настроек.

Аутентификация

Для аутентификации при обращении к платёжному шлюзу можно использовать следующие данные, полученные при регистрации:

  • пара логин/пароль служебной учетной записи
  • токен
  • логин продавца (при использовании платежных систем Apple Pay, Samsung Pay, Google Pay)

файл конфигурации предоставляет параметры для задания данных аутентификации:

...
    'auth' => [
        'userName' => env('SBERBANK_USERNAME', ''),
        'password' => env('SBERBANK_PASSWORD', ''),
        'token' => env('SBERBANK_TOKEN', ''),
    ],
    'merchant_login' => env('SBERBANK_MERCHANT_LOGIN', ''),
...

Задать данные можно либо отредактировав файл конфигурации, либо указав их в .env:

SBERBANK_USERNAME=your_username
SBERBANK_PASSWORD=your_password
SBERBANK_TOKEN=your_token
SBERBANK_MERCHANT_LOGIN=your_merchant_login

Обновление статусов платежей

Некоторые операции не позволяют определить новый статус платежа. Для обновления статусов реализована artisan-команда, вызывающая операцию getOrderStatusExtended для всех платежей с заданным статусом.

Команда принимает аргумент id - набор id статусов платежей, для которых нужно обновить статус:

php artisan sberbank-acquiring:update-statuses --id=1 --id=7

Рекомендуется добавить команду в шедулер (app/Console/Kernel.php):

    use Avlyalin\SberbankAcquiring\Commands\UpdateStatusCommand;
    use Avlyalin\SberbankAcquiring\Models\AcquiringPaymentStatus;

    protected function schedule(Schedule $schedule)
    {
        $schedule->command(UpdateStatusCommand::class, [
            '--id' => [
                AcquiringPaymentStatus::NEW,
                AcquiringPaymentStatus::ACS_AUTH,
            ],
        ])->everyMinute();
    }

События (Events)

На данный момент реализовано одно событие:

Событие Описание Параметр
UpdateStatusCommandHasFailed Во время обновления статусов платежей возникли ошибки Массив исключений

Исключения (Exceptions)

Пакет выбрасывает исключения, в случае возникновения ошибок.

Исключение Причина
HttpClientException В ответ на запрос сервер вернул код, отличный от 200
NetworkException Не удалось выполнить запрос
JsonException Не удалось декодировать JSON ответ сервера
ResponseProcessingException Не удалось сохранить ответ сервера
ConfigException Ошибка файла конфигурации
ModelNotFoundException Не удалось найти модель (платеж)
\InvalidArgumentException Некорректные параметры запроса
\Throwable При сохранении модели возникла ошибка

Поддержка

Если этот проект оказался для вас полезным, вы можете поддержать его развитие здесь.

Лицензия (License)

The MIT License (MIT). Please see License File for more information.