API выставления счетов

Invoice API позволяет создать одноразовую или многоразовую ссылку на оплату без перехода покупателя на платежную страницу в момент создания счета.

Обычный сценарий работы выглядит так:

Создайте счет методом CreateInvoice.
Сохраните id, invId и url из ответа.
При необходимости отправьте ссылку покупателю через NotifyCustomer.
Проверяйте счет через GetInvoiceInformation или GetInvoiceInformationList.
Если ссылка больше не нужна, вызовите DeactivateInvoice.

Формат запросов

Все методы Invoice API используют POST. В теле запроса передается подписанный JWT, состоящий из трех частей:

BASE64URL_HEADER.BASE64URL_PAYLOAD.SIGNATURE

Передавайте заголовок Content-Type: application/json. Сам JWT должен быть JSON-строкой, поэтому в HTTP-теле его необходимо заключить в двойные кавычки:

"BASE64URL_HEADER.BASE64URL_PAYLOAD.SIGNATURE"

Проверяйте результат операции

Invoice API может вернуть HTTP 200 как при успешной обработке, так и при прикладной ошибке. Всегда проверяйте поле isSuccess в JSON-ответе.

Header содержит тип токена и алгоритм подписи:

{
  "typ": "JWT",
  "alg": "MD5"
}

Поддерживаются MD5, RIPEMD160, SHA1 (HS1), SHA256 (HS256), SHA384 (HS384) и SHA512 (HS512). Если alg не передан, используется алгоритм, выбранный в настройках магазина.

Преобразуйте JSON в Base64Url без символов = в конце.

Payload

Payload — JSON с параметрами конкретного метода. Названия полей передаются в регистре, указанном в примерах: MerchantLogin, InvId, InvoiceType и так далее.

Signature

Для формирования подписи:

Преобразуйте Header и Payload в Base64Url.
Соедините результаты точкой: BASE64URL_HEADER.BASE64URL_PAYLOAD.
Рассчитайте HMAC выбранным алгоритмом.
В качестве секретного ключа используйте строку MerchantLogin:Пароль#1.
Преобразуйте подпись в Base64Url и добавьте ее к токену через точку.

Основной и тестовый пароли

Для создания обычного счета используйте основной пароль №1. Если в AdditionalParameters передан IsTest=1, используйте тестовый пароль №1.

Полный пример формирования запроса

Пример на Node.js создает JWT и отправляет его в CreateInvoice. Замените значения merchantLogin и password1 своими реквизитами.

import crypto from "node:crypto";

const merchantLogin = "your-shop-login";
const password1 = "your-password-1";

const header = {
  typ: "JWT",
  alg: "MD5",
};

const payload = {
  MerchantLogin: merchantLogin,
  InvId: 1001,
  InvoiceType: "OneTime",
  Culture: "ru",
  OutSum: 245.5,
  ExpirationDate: "2026-12-31T23:59:59+03:00",
  Description: "Оплата заказа 1001",
  MerchantComments: "Доставка после подтверждения оплаты",
  UserFields: {
    order_source: "website",
  },
  InvoiceItems: [
    {
      Name: "Товар",
      Quantity: 1,
      Cost: 245.5,
      Tax: "none",
      PaymentMethod: "full_payment",
      PaymentObject: "commodity",
    },
  ],
  Aliases: ["BankCard", "SBP"],
  SuccessUrl2Data: {
    Url: "https://merchant.example/success",
    Method: "GET",
  },
  FailUrl2Data: {
    Url: "https://merchant.example/fail",
    Method: "GET",
  },
  AdditionalParameters: {
    Email: "buyer@example.com",
  },
};

function toBase64Url(value) {
  return Buffer.from(JSON.stringify(value)).toString("base64url");
}

const encodedHeader = toBase64Url(header);
const encodedPayload = toBase64Url(payload);
const signingInput = `${encodedHeader}.${encodedPayload}`;
const secret = `${merchantLogin}:${password1}`;
const signature = crypto
  .createHmac("md5", secret)
  .update(signingInput)
  .digest("base64url");
const jwt = `${signingInput}.${signature}`;

const response = await fetch(
  "https://services.robokassa.ru/InvoiceServiceWebApi/api/CreateInvoice",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
    },
    body: JSON.stringify(jwt),
  },
);

const result = await response.json();

Обратите внимание: в body передается JSON.stringify(jwt), а не исходный объект payload.

Создание счета

Метод: POST
Адрес: https://services.robokassa.ru/InvoiceServiceWebApi/api/CreateInvoice

Метод возвращает ссылку на оплату. Для одноразовой ссылки передайте InvoiceType: "OneTime", для многоразовой — InvoiceType: "Reusable".

Параметры создания счета

Параметр	Описание
`MerchantLogin`	Обязательный. Логин магазина.
`InvoiceType`	Обязательный. Тип ссылки: `OneTime` или `Reusable`.
`InvId`	Номер счета в системе магазина. Если не передан, Robokassa сформирует его автоматически.
`OutSum`	Сумма счета. Можно не передавать, если сумма определяется по `InvoiceItems`.
`Culture`	Язык платежной страницы: `ru` или `en`.
`ExpirationDate`	Дата и время окончания действия счета в формате ISO 8601.
`Description`	Описание заказа для покупателя.
`MerchantComments`	Внутренний комментарий, доступный сотрудникам магазина.
`InvoiceItems`	Позиции заказа для фискализации.
`FiscalParentOpId`	`OpId` родительской операции для связанной фискализации, например при зачете аванса и доплате. Подробнее см. в разделе «Связанная фискализация».
`UserFields`	Пользовательские параметры в формате `ключ: значение`.
`SuccessUrl2Data`	URL успешной переадресации и HTTP-метод.
`FailUrl2Data`	URL неуспешной переадресации и HTTP-метод.
`Aliases`	Способы оплаты, доступные для счета.
`Payments`	Распределение суммы по типам платежа для фискализации.
`CustomUserProperty`	Дополнительное свойство с полями `Name` и `Value`.
`IsWithoutFreeSale`	Запрещает автоматически формировать чек с позицией «Свободная продажа», если номенклатура не передана. После оплаты зарегистрируйте чек отдельным запросом. Подробнее см. в разделе «Регистрация чека после оплаты».
`Sno`	Система налогообложения.
`AdditionalParameters`	Дополнительные параметры платежной формы. Все значения передаются как строки.

Передайте хотя бы один источник суммы: OutSum или InvoiceItems.

Фискализация

Если магазин использует фискализацию, передавайте InvoiceItems. Без номенклатуры касса может создать позицию «Свободная продажа» или не сформировать чек — это зависит от настроек и используемого решения.

Позиции заказа

{
  "InvoiceItems": [
    {
      "Name": "Услуга",
      "Quantity": 1,
      "Cost": 100,
      "Tax": "vat20",
      "PaymentMethod": "full_payment",
      "PaymentObject": "service"
    }
  ]
}

Поле	Описание
`Name`	Наименование товара или услуги.
`Quantity`	Количество.
`Cost`	Цена одной единицы.
`Tax`	Ставка НДС.
`PaymentMethod`	Признак способа расчета.
`PaymentObject`	Признак предмета расчета.
`NomenclatureCode`	Код маркировки товара.
`AgentInfo`	Данные агента. Содержит поле `Type`.
`SupplierInfo`	Данные поставщика: `Name`, `Inn` и массив `Phones`.
`IsNonAgentItem`	Признак неагентской позиции.

Подробнее о допустимых значениях для чека см. в разделе Фискализация.

Дополнительные параметры

AdditionalParameters принимает объект, в котором все значения являются строками:

{
  "AdditionalParameters": {
    "Email": "buyer@example.com",
    "IncCurrLabel": "BankCard",
    "PaymentMethods": "[\"BankCard\",\"SBP\"]"
  }
}

Ключ	Назначение
`IsTest`	Включает тестовый режим при значении `1`. JWT необходимо подписать тестовым паролем №1. Подробнее см. в разделе «Тестовый режим».
`IncCurrLabel`	Предпочтительный способ оплаты. Подробнее см. в разделе «Приоритет способов оплаты».
`PaymentMethods`	Способы оплаты в виде JSON-строки, например `"[\"BankCard\",\"SBP\"]"`. Подробнее см. в разделе «Приоритет способов оплаты».
`Email`	Email покупателя. Передавайте без URL-кодирования.
`ResultURL2`	Дополнительный URL уведомления. Передавайте без URL-кодирования. Подробнее см. в разделе «Дополнительное оповещение об оплате на ResultUrl2».
`StepByStep`	Признак холдирования. Подробнее см. в разделе «Холдирование средств».
`Recurring`	Признак рекуррентного платежа. Подробнее см. в разделе «Периодические платежи».
`Token`	Токен сохраненной карты. Подробнее см. в разделе «Оплата по сохраненной карте».
`Split`	Параметры сплитования платежа. Подробнее см. в разделе «Сплитование платежей».
`Culture`	Язык платежной страницы.
`SuccessUrl2`	Дополнительный URL успешной переадресации. Передавайте без URL-кодирования. Подробнее см. в разделе «Дополнительная переадресация».
`SuccessUrl2Method`	HTTP-метод для `SuccessUrl2`: `GET` или `POST`. Подробнее см. в разделе «Дополнительная переадресация».
`FailUrl2`	Дополнительный URL неуспешной переадресации. Передавайте без URL-кодирования. Подробнее см. в разделе «Дополнительная переадресация».
`FailUrl2Method`	HTTP-метод для `FailUrl2`: `GET` или `POST`. Подробнее см. в разделе «Дополнительная переадресация».
`IsWithoutFreeSale`	Запрещает автоматический чек с позицией «Свободная продажа». Подробнее см. в разделе «Отключение автоматического чека».
`FiscalParentOpId`	`OpId` родительской операции для связанной фискализации. Подробнее см. в разделе «Связанная фискализация».

Совместимость параметров

Из StepByStep, Recurring и Token передавайте только один параметр. Split нельзя использовать вместе с IsTest.

Непустое значение из AdditionalParameters заменяет одноименный параметр основного Payload. Неизвестные ключи игнорируются.

Тестовый счет

Для тестового счета добавьте IsTest и подпишите JWT тестовым паролем №1:

{
  "AdditionalParameters": {
    "IsTest": "1"
  }
}

Для обычного счета не передавайте IsTest и используйте основной пароль №1.

Ответ на создание счета

{
  "id": "01234567-89ab-4cde-8f01-23456789abcd",
  "invId": 1001,
  "url": "https://auth.robokassa.ru/merchant/Invoice/AbCdEfGhIjKlMnOpQrStUv",
  "isSuccess": true
}

Сохраните значения:

id — внутренний UUID счета;
invId — номер счета магазина;
url — ссылка, которую необходимо открыть или передать покупателю.

Пример прикладной ошибки:

{
  "isSuccess": false,
  "message": "Некорректно составлен запрос"
}

Получение одного счета

Метод: POST
Адрес: https://services.robokassa.ru/InvoiceServiceWebApi/api/GetInvoiceInformation

Передайте MerchantLogin и один идентификатор: Id или InvId.

{
  "MerchantLogin": "your-shop-login",
  "InvId": 1001
}

Параметр	Описание
`MerchantLogin`	Обязательный. Логин магазина.
`Id`	Внутренний UUID из ответа `CreateInvoice`.
`InvId`	Номер счета магазина.

Ответ с информацией о счете

{
  "invoiceInformation": {
    "id": "01234567-89ab-4cde-8f01-23456789abcd",
    "invId": 1001,
    "invoiceType": "OneTime",
    "created": "2026-08-14T10:00:00+00:00",
    "modified": "2026-08-14T10:01:00+00:00",
    "culture": "ru",
    "outSum": 245.5,
    "expirationDate": "2026-12-31T20:59:59+00:00",
    "description": "Оплата заказа 1001",
    "invoiceItems": [],
    "isCustomerNotificationEmailSent": false,
    "invoiceStatus": "NotPaid",
    "invoicePaymentUrl": "https://auth.robokassa.ru/merchant/Invoice/AbCdEfGhIjKlMnOpQrStUv",
    "shortInvoicePaymentUrl": "https://auth.robokassa.ru/Merchant/Invoice/AbCdEfGhIjKlMnOpQrStUv",
    "aliases": ["BankCard", "SBP"],
    "userFields": {
      "order_source": "website"
    },
    "payments": [],
    "isWithoutFreeSale": false
  },
  "isSuccess": true
}

Основные статусы счета:

NotPaid — счет не оплачен;
Paid — счет оплачен;
Expired — срок действия закончился или счет деактивирован.

Получение списка счетов

Метод: POST
Адрес: https://services.robokassa.ru/InvoiceServiceWebApi/api/GetInvoiceInformationList

Метод возвращает счета, соответствующие заданным фильтрам. В этом запросе используется InvoiceTypes во множественном числе, а при создании счета — InvoiceType.

{
  "MerchantLogin": "your-shop-login",
  "CurrentPage": 1,
  "PageSize": 10,
  "InvoiceStatuses": ["NotPaid", "Paid", "Expired"],
  "DateFrom": "2026-08-01T00:00:00+00:00",
  "DateTo": "2026-08-31T23:59:59+00:00",
  "IsAscending": false,
  "InvoiceTypes": ["OneTime", "Reusable"],
  "Aliases": ["BankCard", "SBP"],
  "PaymentAliases": ["BankCard"],
  "Keywords": "заказ 1001",
  "SumFrom": 1,
  "SumTo": 10000
}

Параметры фильтрации

Параметр	Описание
`MerchantLogin`	Обязательный. Логин магазина.
`CurrentPage`	Обязательный. Номер страницы, начиная с `1`.
`PageSize`	Обязательный. Количество записей на странице.
`InvoiceStatuses`	Статусы: `NotPaid`, `Paid` и `Expired`.
`DateFrom`	Начало периода создания счетов в формате ISO 8601.
`DateTo`	Конец периода создания счетов в формате ISO 8601.
`InvoiceTypes`	Типы ссылок: `OneTime` и `Reusable`.
`IsAscending`	Сортировка по возрастанию.
`Keywords`	Поиск по сумме, идентификатору, описанию или email.
`Aliases`	Способы оплаты, разрешенные для счета.
`PaymentAliases`	Способы, которые фактически использовались для оплаты.
`SumFrom`	Минимальная сумма.
`SumTo`	Максимальная сумма.

Ответ со списком счетов

{
  "invoiceInformationList": [
    {
      "id": "01234567-89ab-4cde-8f01-23456789abcd",
      "invId": 1001,
      "invoiceType": "OneTime",
      "created": "2026-08-14T10:00:00+00:00",
      "modified": "2026-08-14T10:01:00+00:00",
      "outSum": 245.5,
      "description": "Оплата заказа 1001",
      "invoiceStatus": "NotPaid",
      "invoicePaymentUrl": "https://auth.robokassa.ru/merchant/Invoice/AbCdEfGhIjKlMnOpQrStUv",
      "isCustomerNotificationEmailSent": false,
      "aliases": ["BankCard", "SBP"],
      "invoiceItems": [],
      "userFields": {},
      "payments": [],
      "isWithoutFreeSale": false
    }
  ],
  "total": 1,
  "isSuccess": true
}

invoiceInformationList содержит счета текущей страницы, а total — общее количество счетов, соответствующих фильтрам.

Отправка уведомления покупателю

Метод: POST
Адрес: https://services.robokassa.ru/InvoiceServiceWebApi/api/NotifyCustomer

Метод отправляет покупателю email с информацией о счете и ссылкой на оплату.

{
  "MerchantLogin": "your-shop-login",
  "InvId": 1001,
  "CustomerNotificationEmail": "buyer@example.com",
  "CustomerNotificationName": "Иван",
  "CustomerNotificationPhone": "+79990000000"
}

Параметр	Описание
`MerchantLogin`	Обязательный. Логин магазина.
`InvId`	Обязательный. Номер счета магазина.
`CustomerNotificationEmail`	Email покупателя.
`CustomerNotificationName`	Имя покупателя.
`CustomerNotificationPhone`	Телефон покупателя.

Успешный ответ:

{
  "isSuccess": true
}

После отправки результат можно проверить через GetInvoiceInformation: поле isCustomerNotificationEmailSent изменится на true, а адрес появится в customerNotificationEmail.

Деактивация счета

Метод: POST
Адрес: https://services.robokassa.ru/InvoiceServiceWebApi/api/DeactivateInvoice

Передайте MerchantLogin и один идентификатор счета: EncodedId, Id или InvId.

{
  "MerchantLogin": "your-shop-login",
  "InvId": 1001
}

Параметр	Описание
`MerchantLogin`	Обязательный. Логин магазина.
`EncodedId`	Последний сегмент ссылки на оплату.
`Id`	Внутренний UUID из ответа `CreateInvoice`.
`InvId`	Номер счета магазина.

Например, для ссылки https://auth.robokassa.ru/merchant/Invoice/AbCdEfGhIjKlMnOpQrStUv значением EncodedId будет AbCdEfGhIjKlMnOpQrStUv.

Успешный ответ:

{
  "isSuccess": true
}

После деактивации счет больше нельзя оплатить. В GetInvoiceInformation его статус изменится на Expired.

Формат запросов​

Header​

Payload​

Signature​

Полный пример формирования запроса​

Создание счета​

Параметры создания счета​

Позиции заказа​

Дополнительные параметры​

Тестовый счет​

Ответ на создание счета​

Получение одного счета​

Ответ с информацией о счете​

Получение списка счетов​

Параметры фильтрации​

Ответ со списком счетов​

Отправка уведомления покупателю​

Деактивация счета​