Link Поиск Меню Развернуть Документ

Рекуррентные платежи

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

Привязка карты

Схема получения токена карты

sequenceDiagram autonumber participant Покупатель participant Магазин participant Инвойсбокс rect rgb(204, 245, 204) Магазин->>Инвойсбокс: Вызов метода создания заказа Инвойсбокс->>Магазин: Идентификатор заказа и ссылка на оплату Магазин->>Покупатель: Перенаправление на платёжную страницу Покупатель->>Инвойсбокс: Подтверждение оплаты счёта Инвойсбокс->>Покупатель: Перенаправление покупателя на сайт магазина Инвойсбокс->>Магазин: Уведомление об успешной оплате и токен карты Магазин-->>Инвойсбокс: Вызов метода отгрузки для разблокировки средств end
  1. Магазин создает в системе «Инвойсбокс» заказ через метод API с указанием параметров savePaymentData и clientId.
  2. Система возвращает ссылку на платёжную страницу для оплаты заказа.
  3. Магазин перенаправляет покупателя по полученной ссылке.
  4. Покупатель заполняет необходимые для оплаты сведения подтверждает оплату.
  5. Система «Инвойсбокс» перенаправляет покупателя обратно на сайт Магазина.
  6. Система «Инвойсбокс» оповещает Магазин об успешной оплате заказа с указанием токена.
  7. Магазин сохраняет и привязывает полученный токен к пользователю.
  8. Магазин передаёт в систему «Инвойсбокс» информацию об отгрузке через метод API для разблокировки средств.

Создание заказа

Для привязки карты к покупателю и получения токена, необходимо создать заказ с указанием следующих параметров:

Если целью заказа является только привязка банковской карты, необходимо включить режим холдирования средств, указав подтип заказа 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": []
  }
}