Рекуррентные платежи
При оплате заказа физическим лицом есть возможность применить рекуррентные платежи. Это позволит сохранить токен банковской карты пользователя, для последующего списания с неё средств без участия клиента, например, для списания средств по подписке.
Привязка карты
Схема получения токена карты
- Магазин создает в системе «Инвойсбокс» заказ через метод API с указанием параметров
savePaymentData
иclientId
. - Система возвращает ссылку на платёжную страницу для оплаты заказа.
- Магазин перенаправляет покупателя по полученной ссылке.
- Покупатель заполняет необходимые для оплаты сведения подтверждает оплату.
- Система «Инвойсбокс» перенаправляет покупателя обратно на сайт Магазина.
- Система «Инвойсбокс» оповещает Магазин об успешной оплате заказа с указанием токена.
- Магазин сохраняет и привязывает полученный токен к пользователю.
- Магазин передаёт в систему «Инвойсбокс» информацию об отгрузке через метод API для разблокировки средств.
Создание заказа
Для привязки карты к покупателю и получения токена, необходимо создать заказ с указанием следующих параметров:
savePaymentData
иclientId
в invoiceSetting
Если целью заказа является только привязка банковской карты, необходимо включить режим холдирования средств, указав подтип
заказа subType
= hold
, для дальнейшего расхолдирования (разблокировки) средств.
Для оплаты товаров и услуг, эту опцию так же можно использовать, если этого требуют бизнес-процессы.
Пример:
{
....
"subType": "hold",
"invoiceSetting": {
"savePaymentData": true,
"clientId": "client-12345"
}
}
Далее, клиента следует перенаправить на страницу оплаты по ссылке, полученной в параметре paymentUrl
в
ответе на запрос создания заказа.
После успешного холдирования (блокировки) средств, магазину будет направлено уведомление об оплате,
в котром будет находится информация о платеже в объекте PaymentInfo, в том числе параметр
paymentToken
, который необходимо сохранить и привязать к плательщику (пользователю) для последующего проведения платежей.
Пример:
{
....
"paymentInfo": {
"paymentToken": "token-abc123",
"cardholderName": "CARDHOLDER NAME",
"expiration": "13/26",
"maskedPan": "220071**6742",
"paymentSystem": "MIR"
}
}
Если заказ был инициирован только для привязки карты, то необходимо разблокировать средства, путём
создания отгрузки с пустым набором basketItems
и флагом final
= true
.
Для заказов, используемых только для привязки карты, рекомендуется использовать небольшие суммы заказа, например, до 1 рубля.
Подтверждение оплаты заказов с использованием токена
Теперь можно использовать сохранённый токен для подтверждения оплаты в последующих заказах. Для этого создаем заказ и получаем его идентификатор, а затем вызываем метод подтверждения платежа с указанием платёжного токена:
- метод:
POST
- ресурс:
/v3/billing/api/payment/confirm
- тело запроса - объект ConfirmRequest
- тело ответа - объект OrderResponse
ConfirmRequest
Свойство | Обязательное | Тип | Описание | Пример |
---|---|---|---|---|
orderId | да | string | Идентификатор заказа | 0193690f-a122-d2cd-ac46-9da9e848723c |
type | да | string, enum | Тип подтверждения оплаты | paymentToken |
paymentToken | да | string | Платёжный токен карты клиента | cc11a4881764e0e02573f83c99811ed9 |
В случае успешной оплаты в ответе у заказа status
поменяется на paid
или hold
, в зависимости от подтипа заказа.
Ошибки
При использовании метода могут возникнуть следующие ошибки:
Пример ошибки при попытке списания средств ошибочным токеном
{
"error": {
"message": "Ошибка списания средств",
"code": "invalid_argument",
"fields": []
}
}
Пример ошибки при попытке списания средств по уже оплаченному заказу
{
"error": {
"message": "Заказ уже оплачен",
"code": "already_paid",
"fields": []
}
}
Удаление привязанной карты
- метод:
POST
- ресурс:
/v3/processing/api/payment-token/delete
- тело запроса - объект DeletePaymentTokenRequest
DeletePaymentTokenRequest
Свойство | Обязательное | Тип | Описание | Пример |
---|---|---|---|---|
clientId | да | string | Идентификатор клиента | client-12345 |
paymentToken | да | string | Платёжный токен карты клиента | cc11a4881764e0e02573f83c99811ed9 |
Пример ответа в случае успешного удаления
{
"data": {},
"extendedData": []
}
Пример ошибки удаления токена
{
"error": {
"message": "Неверное состояние связки",
"code": "invalid_argument",
"fields": []
}
}
Пример ошибки, когда токен не найден
{
"error": {
"message": "Error",
"code": "not_found",
"fields": []
}
}