API BENZUBER-PAY

API Benzuber-PAY – протокол для обеспечения взаимодействия между внешней платежной системой (PS) и системой Benzuber (BZ).

Протокол позволяет пользователям приложения Benzuber осуществлять оплату за топливо в приложении Benzuber, используя средства внешней платежной системы. В приложении для клиента, при оформлении заказа, доступно соответствующие платежное средство.

Варианты подключения платежного средства

1. Benzuber периодически запрашивает у платежной системы список пользователей, которым доступно платежное средство, и это платежное средство автоматически появляется у пользователя в приложении Benzuber. Идентификация пользователей между BZ и PS происходит по сотовому номеру пользователя. В дальнейших операциях может использоваться как номер телефона, так и токен пользователя в PS.
2. Пользователь в профиле приложения Benzuber добавляет платежное средство и подтверждает право на его использование (получение SMS от PS, действие в приложении PS). После подтверждения PS генерирует уникальный идентификатор (токен) пользователя, который передается в Benzuber и используется при дальнейших операциях.
3. Платежная система на своей стороне управляет доступностью оплаты в Benzuber для пользователя, и присылает в Benzuber список пользователей, имеющих соответствующее разрешение. Это платежное средство появляется у пользователя в приложении Benzuber. Идентификация пользователей между BZ и PS происходит по сотовому номеру пользователя. В дальнейших операциях может использоваться как номер телефона, так и токен пользователя в ПС.

Сценарий обработки оплаты заказа

1. Оформление заказа в приложении Benzuber. Выбор метода оплаты соответствующего платежной системе.
2. Запрос баланса пользователя в выбранной платежной системе.
3. Если баланса достаточно – резервирование (холдирование) или списание полной суммы заказа.
4. Постановка заказа на АЗС и его выполнение.
5. После завершения обработки заказа на АЗС: a. «Полный налив»: подтверждение полной суммы; b. «Частичный налив»: подтверждение фактической суммы или возврат суммы («сдача»); c. Если отпуска топлива не произошло, то производится полный возврат средств

Вариант реализации протокола

Описание варианта реализации протокола в случае если Benzuber периодически опрашивает платежную систему, для получения списка пользователей. В других случаях для реализации протокола необходимо дополнительное согласование с разработчиками платежной системы.

Для обеспечения безопасного доступа и идентификации платежной системы для работы с протоколом предоставляется уникальный ключ apikey, который используется во всех запросах.

Базовый URL_PS – адрес для обращения к платежной системе. Все запросы выполняются HTTP/HTTPS запросами GET вида: URL_PS + /команда?apikey={apikey}

HTTP коды ответа:

200 – запрос выполнен успешно
400 - не правильные параметры запроса 
401 - не действительный apikey
404 - не удалось выполнить операцию 
500 – платёжная система недоступна

Для тестовой и продуктовой среды базовые адреса различные, и согласовываются с отделом разработки.

Запрос списка пользователей.

Периодический запрос списка пользователей в платежной системе. В ответе – массив пользователей, которым доступна оплата в приложении Benzuber. Идентификация пользователей происходит по сотовому телефону. В ответе для каждого пользователя должен содержаться уникальный идентификатор пользователя token), который используется в дальнейших запросах.

Запрос

(GET)URL_PS + /GetAllUser/?apiKey={apikey}

Ответ

Content type: application/json

[
 {
  "name": (string),        
  "phone": (string),             
  "token": (string)         
 },
 ...
]

Запрос информации о доступном балансе пользователя

При оформлении заказа, необходимо проверить возможность оплаты платежным средством. Платежная система может дополнительно в ответ передать фактический баланс пользователя

Запрос

(GET) URL_PS + /GetUser/?apiKey={apikey}&id={id}&sum={sum}

Ответ

Content type: application/json

{
  "response": (string),
  "balance": (string)        
}

Выполнение списания у пользователя

Списание полной суммы заказа с баланса пользователя в платежной системе. В платежной системе при выполнении запроса сумма может быть фактически списана сразу, либо зарезервирована.

Запрос

(GET) URL_PS + /Payment/?apiKey={apikey}&
    id={id}&sum={sum}&orderId={orderId}&descr={description}

Ответ

Content type: application/json

{
  "response": (string),
  "balance": (string)        
}

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

После завершения обработки заказа на АЗС, при необходимости выполняется запрос на частичный или полный возврат средств.

Запрос

(GET) URL_PS + /Payment/?apiKey={apikey}&
    id={id}&sumRefund={sum}&orderId={orderId}&descr={description}

Ответ

Content type: application/json

{
  "response": (string),
  "balance": (string)        
}

Получение списка транзакций

Возможность получения списка транзакций за выбранный период времени, с возможностью фильтрации по пользователям

В связи с тем, что количество фактических транзакций в выборке может быть большое, то предусмотрен асинхронный формат работы, с получением результирующих данных последовательно по частям.

Запрос

(POST) Базовый URL_BZ + /pay/v1/transactions/get/?apikey={apikey}

Request body schema application/json

{
    "date_start": (string),
    "date_end": (string),
    "order_id": (string),
    "client_id": (string),
    "phone": (string)
}

или

{
    "request_id": (string),
    "offset": (string),
    "limit": (string)
}

Ответ

Content type: application/json

{
    "response": (string),
    "transactions": (array),
    "request": (array)
}