voronkovich / sberbank-acquiring-client
Client for working with Sberbank's acquiring REST API
Fund package maintenance!
Ko Fi
Installs: 257 931
Dependents: 2
Suggesters: 0
Security: 0
Stars: 191
Watchers: 19
Forks: 56
Open Issues: 1
Requires
- php: ^7.1||^8
- ext-json: *
README
PHP client for Sberbank, Alfabank and YooKassa REST APIs.
Requirements
- PHP 7.1 or above (Old version for PHP 5 you can find here)
- TLS 1.2 or above (more information you can find here)
php-json
extension installed
Installation
composer require 'voronkovich/sberbank-acquiring-client'
Usage
Instantiating a client
In most cases to instantiate a client you need to pass your username
and password
to a factory:
use Voronkovich\SberbankAcquiring\ClientFactory; // Sberbank production environment $client = ClientFactory::sberbank(['userName' => 'username', 'password' => 'password']); // Sberbank testing environment $client = ClientFactory::sberbankTest(['userName' => 'username', 'password' => 'password']); // Alfabank production environment $client = ClientFactory::alfabank(['userName' => 'username', 'password' => 'password']); // Alfabank testing environment $client = ClientFactory::alfabankTest(['userName' => 'username', 'password' => 'password']); // YooKassa production environment $client = ClientFactory::yookassa(['userName' => 'username', 'password' => 'password']);
Alternatively you can use an authentication token
:
$client = ClientFactory::sberbank(['token' => 'sberbank-token']);
More advanced example:
use Voronkovich\SberbankAcquiring\ClientFactory; use Voronkovich\SberbankAcquiring\Currency; use Voronkovich\SberbankAcquiring\HttpClient\HttpClientInterface; $client = ClientFactory::sberbank([ 'userName' => 'username', 'password' => 'password', // A language code in ISO 639-1 format. // Use this option to set a language of error messages. 'language' => 'ru', // A currency code in ISO 4217 format. // Use this option to set a currency used by default. 'currency' => Currency::RUB, // An HTTP method to use in requests. // Must be "GET" or "POST" ("POST" is used by default). 'httpMethod' => HttpClientInterface::METHOD_GET, // An HTTP client for sending requests. // Use this option when you don't want to use // a default HTTP client implementation distributed // with this package (for example, when you have'nt // a CURL extension installed in your server). 'httpClient' => new YourCustomHttpClient(), ]);
Also you can use an adapter for the Guzzle:
use Voronkovich\SberbankAcquiring\ClientFactory; use Voronkovich\SberbankAcquiring\HttpClient\GuzzleAdapter; use GuzzleHttp\Client as Guzzle; $client = ClientFactory::sberbank([ 'userName' => 'username', 'password' => 'password', 'httpClient' => new GuzzleAdapter(new Guzzle()), ]);
Also, there are available adapters for Symfony and PSR-18 HTTP clents.
Low level method "execute"
You can interact with the Gateway REST API using a low level method execute
:
$client->execute('/ecomm/gw/partner/api/v1/register.do', [ 'orderNumber' => 1111, 'amount' => 10, 'returnUrl' => 'http://localhost/sberbank/success', ]); $status = $client->execute('/ecomm/gw/partner/api/v1/getOrderStatusExtended.do', [ 'orderId' => '64fc8831-a2b0-721b-64fc-883100001553', ]);
But it's more convenient to use one of the shortcuts listed below.
Creating a new order
use Voronkovich\SberbankAcquiring\Currency; // Required arguments $orderId = 1234; $orderAmount = 1000; $returnUrl = 'http://mycoolshop.local/payment-success'; // You can pass additional parameters like a currency code and etc. $params['currency'] = Currency::EUR; $params['failUrl'] = 'http://mycoolshop.local/payment-failure'; $result = $client->registerOrder($orderId, $orderAmount, $returnUrl, $params); $paymentOrderId = $result['orderId']; $paymentFormUrl = $result['formUrl']; header('Location: ' . $paymentFormUrl);
If you want to use UUID identifiers (ramsey/uuid) for orders you should convert them to a hex format:
use Ramsey\Uuid\Uuid; $orderId = Uuid::uuid4(); $result = $client->registerOrder($orderId->getHex(), $orderAmount, $returnUrl);
Use a registerOrderPreAuth
method to create a 2-step order.
Getting a status of an exising order
use Voronkovich\SberbankAcquiring\OrderStatus; $result = $client->getOrderStatus($orderId); if (OrderStatus::isDeposited($result['orderStatus'])) { echo "Order #$orderId is deposited!"; } if (OrderStatus::isDeclined($result['orderStatus'])) { echo "Order #$orderId was declined!"; }
Also, you can get an order's status by using you own identifier (e.g. assigned by your database):
$result = $client->getOrderStatusByOwnId($orderId);
Reversing an exising order
$result = $client->reverseOrder($orderId);
Refunding an exising order
$result = $client->refundOrder($orderId, $amountToRefund);
SBP payments using QR codes
Currently only supported by Alfabank, see docs.
$result = $client->getSbpDynamicQr($orderId, [ 'qrHeight' => 100, 'qrWidth' => 100, 'qrFormat' => 'image', ]); echo sprintf( '<a href="%s"><img src="%s" /></a>', $result['payload'], 'data:image/png;base64,' . $result['renderedQr'] );
See Client
source code to find methods for payment bindings and dealing with 2-step payments.
License
Copyright (c) Voronkovich Oleg. Distributed under the MIT.