Skip to content

Home

Jump to bottom
Aleksandr Panasyuk edited this page Dec 10, 2018 · 9 revisions

Краткая инструкция

Перед тем, как приступить к использованию этого гема, автор настоятельно рекомендует (хотя бы бегло) ознакомиться с официальной документацией к JSON API эквайринга Сбербанка.

Гем sberbank-acquiring упрощает логику составления и выполнения запросов к JSON API эквайринга Сбербанка. Он может выполнить любой запрос к вышеупомянутому интерфейсу и корректно обработать ответ. Что под капотом?

SBRF::Acquiring::Client

Объекты этого класса предлагается использовать в качестве фасада к основной функциональности библиотеки - выполнению запросов к API эквайринга Сбербанка. Это значит, что любые изменения в API удаленного сервиса должны будут минимально влиять на интерфейс этого класса. Так задумано, чтобы можно было следовать обновлениям удаленного API обновляя версию этого гема.

Тестовый режим

Чтобы использовать тестовый сервер для выполнения запросов, необходимо инициализировать объект клиента c аргументом test: true:

test_client = SBRF::Acquiring::Client.new(token: 'token', test: true)

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

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

Поддерживаются оба варианта аутентификации: по паре логин-пароль и по токену.

client = SBRF::Acquiring::Client.new(username: ENV['SBRF_USERNAME'], password: ENV['SBRF_PASSWORD'])
# или
client = SBRF::Acquiring::Client.new(token: ENV['SBRF_TOKEN'])

Выполнение запросов

Объект клиента поддерживает следующие методы для отправки запросов:

Название метода Путь API
#deposit /payment/rest/deposit.do
#get_order_status_extended /payment/rest/getOrderStatusExtended.do
#payment /payment/rest/payment.do
#payment_sber_pay /payment/rest/paymentSberPay.do
#refund /payment/rest/refund.do
#register /payment/rest/register.do
#register_pre_auth /payment/rest/registerPreAuth.do
#reverse /payment/rest/reverse.do
#verify_enrollment /payment/rest/verifyEnrollment.do

Этот список будет дополняться по мере запросов от пользователей этого гема.

Автор предлагает именовать методы, которые выполняют запросы к API "командами".

Аргументы этих команд принимают Hash, ключи которого могут быть как строками, так и символами. Как в underscore_case, так и в camelCase. Это сделано для того, чтобы к коде программы не нарушать конвенции именования ключей хэшей, так как, в большинстве случаев используется underscore_case, а JSON API принимает параметры в camelCase. Пример:

client.register(
  amount: 1000,
  order_number: 'order#1',
  return_url: 'https://example.com/sberbank/success',
  json_params: { email: 'test@example.com' }
)

Следующая особенность использования этого гема - параметры в формате JSON. Согласно документации, JSON API принимает в запросах структурированные параметры в формате JSON. Это относится к объектам, лежащим ниже первого уровня. То есть параметр json_params: { email: 'test@example.com' } должен быть представлен в виде параметра так: jsonParams={"email":"test@example.com"}. Чтобы достичь этого, при подготовке параметров, код клиента сначала рекурсивно преобразует все ключи в camelCase, а затем преобразует все структуры ниже первого уровня в JSON. В результате получаются вот такие параметры запроса: amount=1000&orderNumber=order%231&returnUrl=https%3A%2F%2Fexample.com%2Fsberbank%2Fsuccess&jsonParams=%7B%22email%22%3A%22test%40example.com%22%7D

Выполнение произвольных запросов

Объект клиента позволяет выполнять произвольные запросы к JSON API при том же способе обработки параметров.

client.execute(path: '/payment/rest/getOrderStatusExtended.do', params: { order_id: 'some-order-id' })

Результатом запроса можно будет пользоваться точно так же, как и результатом команды.

Результат команды

Все команды возвращают (и должны возвращать) объект класса SBRF::Acquiring::CommandResponseDecorator, либо схожий по интерфейсу и поведению объект.

Список методов, поддерживаемых результатом команды:

Название Класс результата Описание
#body String Тело HTTP ответа от сервера
#data Hash Результат парсинга JSON тела ответа от сервера. Может быть nil, если не удалось распарсить ответ
#error? Boolean true, если данные не удалось распарсить или в ответе есть errorCode отличный от нуля.
#http_response или #http наследник Net::HTTPResponse
#request SBRF::Acquiring::Request
#success? Boolean !error?

В дополнение к этим методам можно запрашивать поля первого уровня структуры #data в underscore_case:

response = client.register(amount: 1000, order_id: 1)
response.data #=> { "orderId" => "f3ced54d-45df-7c1a-f3ce-d54d04b11830", "formUrl" => "https://3dsec.sberbank.ru/payment/merchants/sbersafe/payment_ru.html?mdOrder=f3ced54d-45df-7c1a-f3ce-d54d04b11830" }
response.order_id #=> "f3ced54d-45df-7c1a-f3ce-d54d04b11830"
response.form_url #=> "https://3dsec.sberbank.ru/payment/merchants/sbersafe/payment_ru.html?mdOrder=f3ced54d-45df-7c1a-f3ce-d54d04b11830"
reponse.absent_field
NoMethodError: undefined method `absent_field' for #<Sberbank::Acquiring::CommandResponseDecorator:0x007fa5c41b1d10>
Clone this wiki locally