# Инвойсбокс API — Проведение платежей > Раздел документации целиком. Полное оглавление: https://docs.invoicebox.ru/llms.txt ## Проведение платежей - [Схема взаимодействия](https://docs.invoicebox.ru/raw/payment/schema.md) (раздел «Платёжные инструменты и банки») - [Получение счёта](https://docs.invoicebox.ru/raw/payment/get.md) (раздел «Платёжные инструменты и банки») - [Подтверждение оплаты счёта](https://docs.invoicebox.ru/raw/payment/confirm_payment.md) (раздел «Платёжные инструменты и банки») - [Вход через ID вашего банка](https://docs.invoicebox.ru/raw/payment/auth-id.md) (раздел «Платёжные инструменты и банки») - [Платёжные инструменты и банки](https://docs.invoicebox.ru/raw/payment/payment.md) --- # Схема взаимодействия # Схема взаимодействия с платёжным инструментом
sequenceDiagram autonumber participant Покупатель participant Платёжный инструмент participant Инвойсбокс rect rgba(43, 170, 93, 0.13) Покупатель->>Платёжный инструмент: Выбор способа оплаты и переход на страницу платёжного инструмента Платёжный инструмент->>Инвойсбокс: Вызов метода получения информации по счёту Покупатель->>Платёжный инструмент: Подтверждение оплаты счёта Платёжный инструмент->>Инвойсбокс: Вызов метода подтверждения оплаты счёта Платёжный инструмент->>Покупатель: Перенаправление на платёжную страницу end
1. Покупатель оформляет заказ и выбирает способ оплаты через платёжный инструмент. Покупатель перенаправляется на страницу авторизации платёжного инструмента с идентификатором счёта. Ссылка на страницу авторизации предоставляется платёжным инструментом. Также могут быть переданы ссылки возврата на случай обработки негативных сценариев при работе с API. 1. Система платёжного инструмента получает информацию по счёту из системы «Инвойсбокс» по API [через метод API](/docs/payment/get/). 1. Покупатель подтверждает оплату счёта. 1. Система платёжного инструмента подтверждает оплату счёта в системе «Инвойсбокс» по API [через метод API](/docs/payment/confirm_payment/). 1. Платёжный инструмент перенаправляет покупателя по полученной ссылке (в запросе информации по счёту) на платёжную страницу системы «Инвойсбокс». --- --- # Получение счёта # Получение счёта Счета читаются одним запросом — списком или по идентификатору: - метод: `GET` - ресурс: `/v3/payment/api/invoice` или `/v3/payment/api/invoice/{invoiceId}` - тело ответа - коллекция объектов [InvoiceResponse](/docs/payment/get/#invoiceresponse) в свойстве `data`, постраничность — в `metaData` (см. [формат ответа выборки](/docs/api/filters/#формат-ответа-выборки)) #### Пример запроса и ответа ```http GET /v3/payment/api/invoice/01771534-196a-1105-839a-82422289d6d9 ``` В запросе возможно применения фильтров и сортировок. Пример запроса с фильтром по идентификатору счёта ```http GET /v3/payment/api/invoice?id=01771534-196a-1105-839a-82422289d6d9 ``` Пример запроса с фильтром по статусу ```http GET /v3/payment/api/invoice?status=paid ``` Пример запроса с фильтром по ИНН ```http GET /v3/payment/api/invoice?customer[type][eq]=legal&customer[vatNumber][eq]=2323232323 ``` Пример запроса с фильтром по номеру телефона ```http GET /v3/payment/api/invoice?customer[type][eq]=private&customer[phone][eq]=79001231212 ``` Ответ: ``` json { "data": [ { "id": "01771534-1a57-f184-dee3-ebeb91dded76", "number": "123-123212", "createdAt": "2026-08-01T10:00:00+03:00", "expirationDate": "2026-08-04T10:00:00+03:00", "description": "Оплата номера в отеле", "amount": 19658.45, "currencyId": "RUB", "status": "created" } ] } ``` ## InvoiceResponse | Свойство | Обязательное | Тип | Описание | Пример значения | |----------------------|--------------|-------------------------------|-------------------------------------------------------------------------|----------------------------------------| | id | да | string(36) | Идентификатор счёта | `01771534-1a57-f184-dee3-ebeb91dded76` | | number | да | string(50) | Номер счёта | `123-123212` | | createdAt | да | datetime | Дата создания счёта | `2023-12-22T00:00:00+00:00` | | expirationDate | да | datetime | Срок оплаты счёта | `2023-12-25T00:00:00+00:00` | | description | да | string(1000) | Описание счёта | `Оплата номера в отеле` | | amount | да | float | Сумма счёта (к оплате) | `19658.45` | | vatAmount | да | float | Сумма НДС в счёте | `156.56` | | currencyId | да | string(3) enum | Код валюты счёта в соответствии с [ISO 4217](/docs/dictionary/iso4217/) | `RUB`, `USD`,`EUR`, `GBP` | | customer | нет | [Customer](#customer) | Информация о плательщике | | | paymentOrderTemplate | нет | [PaymentOrderTemplate](#paymentordertemplate) | Шаблон платёжного поручения (детали платежа) | | | status | нет | string(50) enum | Статус оплаты счёта (paid, pending, canceled, partial) | `paid` | | paymentUrl | да | string(1000) | Ссылка для перехода на платёжный шлюз на страницу счёта | | ## Customer | Свойство | Обязательное | Тип | Описание | Пример значения | |---------------------|--------------|-----------------|-------------------|------------------------------------------------------| | type | да | string(10) enum | Тип заказчика | `legal` - юр. лицо, `private` - физ лицо | | name | нет | string(500) | Наименование или имя | `ООО «Ромашка»` | | phone | нет | string(100) | Номер телефона | `79001112233` | | email | нет | string(100) | Электронная почта | `buh@example.invbox.ru` | | vatNumber | нет | string(20) | ИНН | `7701234560` | | registrationAddress | нет | string(1000) | Юр. адрес | `190000, Санкт-Петербург, Невский пр. 147, офис 321` | ## PaymentOrderTemplate | Свойство | Обязательное | Тип | Описание | Пример значения | |---------------------------|--------------|-----------------|--------------------|----------------------------------------------------------------| | type | да | string(10) enum | Тип получателя | `legal` - юр. лицо, `private` - физ лицо | | amount | да | float | Сумма счёта (к оплате) | `19658.45` | | currencyId | да | string(3) enum | Код валюты счёта в соответствии с [ISO 4217](/docs/dictionary/iso4217/) | `RUB`, `USD`,`EUR`, `GBP` | | name | да | string(500) | Наименование | `ООО Ромашка` | | vatNumber | да | string(20) | ИНН | `7710044140` | | taxRegistrationReasonCode | да | string(9) | КПП | `770001001` | | settlementAccount | да | string(20) | Номер расчт. счёта | `40702810800190000253` | | correspondentAccount | да | string(20) | Номер корр. счёта | `30101810700000000187` | | bankName | да | string(100) | Наименование банка | `ПАО ВТБ` | | bic | да | string(9) | БИК | `044039142` | | kbk | да | string(20) | Код бюджетной классификации (КБК) | `18210501011011000110` | | oktmo | да | string(7) | ОКТМО | `40000000` | | uin | да | string(25) | УИН | `34934876203474` | | paymentPurpose | да | string(210) | Назначение платежа | `Оплата по счёту №10-2946153 за авиабилеты, НДС не выделяется` | --- --- # Подтверждение оплаты счёта # Подтверждение оплаты заказа Оплата счёта подтверждается одним вызовом: - метод: `POST` - ресурс: `/v3/payment/api/invoice/confirm` - тело запроса - объект [CreateInvoicePaymentRequest](#createinvoicepaymentrequest) - тело ответа - объект [InvoicePaymentResponse](#invoicepaymentresponse) - Возможные [ошибки](/docs/dictionary/error/) #### Пример запроса ``` json POST /v3/payment/api/invoice/confirm Authorization: Bearer b37c4c689295904ed21eee5d9a48d42e Content-Type: application/json User-Agent: MyApp 1.0 Accept: application/json { "paymentOperationId" : "117a58b0-7dc9-424c-8f07-b8a865e8bcc7", "paymentOrderNumber" : "1342", "paymentOrderDate" : "2023-04-01", "amount" : 19658.45, "currencyId" : "RUB", "customer" : { "type" : "legal", "name" : "ООО Ромашка", "vatNumber" : "7710044140", "taxRegistrationReasonCode" : "770001001", "settlementAccount" : "40702810800190000253", "correspondentAccount" : "30101810700000000187", "bankName" : "ПАО ВТБ", "bic" : "044039142" } } ``` Ответ: ``` json { "data": { "id": "8c0e116d-31a5-4210-b62e-6b6917851f69", "invoiceId": "01771534-1a57-f184-dee3-ebeb91dded75", "paymentOperationId": "117a58b0-7dc9-424c-8f07-b8a865e8bcc7", "amount": 19658.45, "currencyId": "RUB", "status": "paid" } } ``` ## CreateInvoicePaymentRequest | Свойство | Обязательное | Тип | Описание | Пример значения | |--------------------|--------------|-----------------|----------------------------|----------------------------------------| | invoiceId | да | string(36) | Id счёта | `01771534-1a57-f184-dee3-ebeb91dded75` | | paymentOperationId | да | string(36) | Id операции | `117a58b0-7dc9-424c-8f07-b8a865e8bcc7` | | amount | да | float | Сумма платежа | `19658.45` | | currencyId | да | string(3) enum | Код валюты счёта в соответствии с [ISO 4217](/docs/dictionary/iso4217/) | `RUB`, `USD`,`EUR`, `GBP` | | paymentOrder | нет | [PaymentOrder](#paymentorder) | Детали платежа) | | | status | нет | string(50) enum | Статус платежа (paid, pending) | `paid` | ## PaymentOrder | Свойство | Обязательное | Тип | Описание | Пример значения | |---------------------------|--------------|-----------------|----------------------------|----------------------------------------------------------------| | type | да | string(10) enum | Тип плательщика | `legal` - юр. лицо, `private` - физ лицо | | number | нет | string(36) | Номер платёжного поручения | `1342` | | date | нет | string(36) | Дата платёжного поручения | `2023-04-01` | | amount | да | float | Сумма платежа | `19658.45` | | currencyId | да | string(3) enum | Код валюты счёта в соответствии с [ISO 4217](/docs/dictionary/iso4217/) | `RUB`, `USD`,`EUR`, `GBP` | | name | нет | string(500) | Наименование плательщика | `ООО Ромашка` | | phone | нет | string(100) | Номер телефона | `79001112233` | | vatNumber | нет | string(20) | ИНН | `7710044140` | | taxRegistrationReasonCode | нет | string(9) | КПП | `770001001` | | settlementAccount | нет | string(20) | Номер расчт. счёта | `40702810800190000253` | | correspondentAccount | нет | string(20) | Номер корр. счёта | `30101810700000000187` | | bankName | нет | string(100) | Наименование банка | `ПАО ВТБ` | | bic | нет | string(9) | БИК | `044039142` | | kbk | нет | string(20) | Код бюджетной классификации (КБК) | `18210501011011000110` | | paymentPurpose | нет | string(210) | Назначение платежа | `Оплата по счёту №10-2946153 за авиабилеты, НДС не выделяется` | ## InvoicePaymentResponse Повторяет свойства объекта [CreateInvoicePaymentRequest](#createinvoicepaymentrequest) с дополнительными свойствами: | Свойство | Обязательное | Тип | Описание | Пример значения | |------------|--------------|------------|-----------------------------------------------|-----------------------------------------| | id | да | string(36) | Идентификатор транзакции в системе Инвойсбокс | `8c0e116d-31a5-4210-b62e-6b6917851f69` | ## NotificationErrorCode | Код ошибки | Описание | |------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------| | `out_of_service` | Техническая ошибка обработки запроса, при получении этого кода ошибки необходимо пытаться повторить запрос еще несколько раз в течение последующих суток. | | `invoice_already_paid` | Счёт уже оплачен другим инструментом оплаты | | `invoice_not_found` | Счёт не найден в учётной системе | | `signature_error` | Ошибка проверки подписи запроса | > [!WARNING] > Обратите внимание, в случае, если аналогичный запрос на оплату уже был обработан ранее успешно и заказ был отмечен как оплаченный, то в этом случае будет возвращён статус успешной обработки `success`. В случае, если заказ был оплачен ранее под другим идентификатором или иным платёжным инструментом, вернётся ошибка `invoice_already_paid`. ## Подпись запроса При отправке запросе необходимо сформировать и передать подпись тела запроса в заголовке `X-Signature`. При ошибке проверки подписи будет сформирован ответ [NotificationError](/docs/merchant/notification/status/#notificationerror) с [NotificationErrorCode](#notificationerrorcode) `signature_error`. Электронная подпись формируется путем криптографического преобразования содержимого тела запроса с использованием ключа и согласованного алгоритма. По умолчанию используется алгоритм sha1 и метод hmac. --- --- # Вход через ID вашего банка # Вход через ID вашего банка На платёжной странице и в приложении Инвойсбокс может быть реализован механизм авторизации через систему ID вашего банка. Клиенты вашего банка получат улучшений опыт взаимодействия с сервисом и смогут подтверждать оплату заказов в пару кликов. Поддерживаются различные стандарты авторизации, в том числе oAuth. Свяжитесь с нами сейчас и мы произведём интеграцию в кратчайшие сроки. --- --- # Платёжные инструменты и банки # Платёжные инструменты и банки Инвойсбокс API для платёжных инструментов, банков и НКО позволяет получать информацию по заказам, а также подтверждать их оплату. Пожалуйста, ознакомьтесь со [схемой взаимодействия](/docs/payment/schema/). ### Использование системы авторизации банка (банковский ID) Если открытое API банка позволяет интегрировать систему авторизации, она может быть добавлена в сервисы Инвойсбокс. См. [дополнительную информацию](/docs/payment/auth-id/). ## Читайте также - [API Инвойсбокс.Бизнес](/docs/business/) ---