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

Создание ссылки без перенаправления на оплату

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

Запрос представляет собой JWT-строку, которая передается в теле HTTP-запроса.

Параметры запроса

• Header
• Payload
• Signature

Header

Заголовок состоит из двух параметров в формате JSON.

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

Вместо MD5 можно использовать любой из алгоритмов: MD5, RIPEMD160, SHA1 (или HS1), SHA256 (или HS256), SHA384 (или HS384), SHA512 (или HS512).

Если параметр alg не передан, используется метод, указанный в настройках магазина.

Полученный JSON преобразуется в Base64Url. Пример результата:

eyJ0eXAiOiJKV1QiLCJhbGciOiJNRDUifQ

Payload

Полезная нагрузка содержит основной запрос в формате JSON.

{
  "MerchantLogin": "robo-demo-test",
  "InvoiceType": "OneTime",
  "Culture": "ru",
  "InvId": null,
  "OutSum": 1,
  "Description": "as",
  "MerchantComments": "no comment",
  "UserFields": {
    "shp_info": "test"
  },
  "InvoiceItems": [
    {
      "Name": "Тест1",
      "Quantity": 1,
      "Cost": 0.5,
      "Tax": "vat20",
      "PaymentMethod": "full_payment",
      "PaymentObject": "commodity"
    },
    {
      "Name": "Тест2",
      "Quantity": 1,
      "Cost": 0.5,
      "Tax": "vat0",
      "PaymentMethod": "full_prepayment",
      "PaymentObject": "commodity",
      "NomenclatureCode": "IYVITCUR%XE^$X%C^T&VITC^RX&%ERC^TIRX%&ERCUITRXE&ZX%R^CTIR^XUE%ZN1m9E+1¦?5O?6¦?168"
    }
  ],
  "SuccessUrl2Data": {
    "Url": "https://robokassa.com/",
    "Method": "GET"
  },
  "FailUrl2Data": {
    "Url": "https://www.google.com/",
    "Method": "POST"
  }
}

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

Полученный JSON также необходимо преобразовать в Base64Url. Пример результата:

ewogICAiTWVyY2hhbnRMb2dpbiI6InJvYm8tZGVtby10ZXN0IiwKICAgIkludm9pY2VUeXBlIjoiT25lVGltZSIsCiAgICJDdWx0dXJlIjoicnUiLAogICAiSW52SWQiOjgwMCwKICAgIk91dFN1bSI6MSwKICAgIkRlc2NyaXB0aW9uIjoiYXMiLAogICAiTWVyY2hhbnRDb21tZW50cyI6Im5vIGNvbW1lbnQiLAogICAiSW52b2ljZUl0ZW1zIjpbCiAgICAgIHsKICAgICAgICAgIk5hbWUiOiLQotC10YHRgjEiLAogICAgICAgICAiUXVhbnRpdHkiOjEsCiAgICAgICAgICJDb3N0IjowLjUsCiAgICAgICAgICJUYXgiOiJ2YXQyMCIsCiAgICAgICAgICJQYXltZW50TWV0aG9kIjoiZnVsbF9wYXltZW50IiwKICAgICAgICAgIlBheW1lbnRPYmplY3QiOiJjb21tb2RpdHkiCiAgICAgIH0sCiAgICAgIHsKICAgICAgICAgIk5hbWUiOiLQotC10YHRgjIiLAogICAgICAgICAiUXVhbnRpdHkiOjEsCiAgICAgICAgICJDb3N0IjowLjUsCiAgICAgICAgICJUYXgiOiJ2YXQwIiwKICAgICAgICAgIlBheW1lbnRNZXRob2QiOiJmdWxsX3ByZXBheW1lbnQiLAogICAgICAgICAiUGF5bWVudE9iamVjdCI6ImNvbW1vZGl0eSIsCiAgICAgICAgICJOb21lbmNsYXR1cmVDb2RlIjoiSVlWSVRDVVIlWEVeJFglQ15UJlZJVENeUlgmJUVSQ15USVJYJSZFUkNVSVRSWEUmWlglUl5DVElSXlhVRSVaTjFtOUUrMcKmPzVPPzbCpj8xNjgiCiAgICAgIH0KICAgXQp9

Описание параметров Payload

Параметр	Значение
MerchantLogin	Обязательный. Логин магазина.
InvoiceType	Обязательный для CreateInvoice. Тип ссылки: одноразовая (OneTime) или многоразовая (Reusable).
OutSum	Обязательный. Сумма счёта.
Culture	Необязательный. Язык (ru или en).
InvId	Необязательный. Номер счета в магазине.
Description	Необязательный. Название товара или услуги.
MerchantComments	Необязательный. Внутренний комментарий для сотрудников. Отображается в личном кабинете в разделе «Выставление счетов».
UserFields	Необязательный. Пользовательские параметры в формате ключ: значение.
InvoiceItems	Необязательный. Номенклатура для фискализации (структура аналогична Receipt). Если параметр не передан, в чеке будет указано значение «Свободная продажа», что не соответствует требованиям налогового законодательства, может привести к штрафам, а на ряде решений по фискализации чек не будет сформирован.
SuccessUrl2Data/FailUrl2Data	Необязательные. Настройки дополнительных redirect-URL c указанием метода.

Пример массива InvoiceItems:

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

Signature

Подпись используется для проверки подлинности токена. Она формируется из заголовка и полезной нагрузки.

1. Соберите строку Header.Payload, где используются результаты, полученные на предыдущих шагах.

   eyJ0eXAiOiJKV1QiLCJhbGciOiJNRDUifQ.ewogICAiTWVyY2hhbnRMb2dpbiI6InJvYm8tZGVtby10ZXN0IiwKICAgIkludm9pY2VUeXBlIjoiT25lVGltZSIsCiAgICJDdWx0dXJlIjoicnUiLAogICAiSW52SWQiOjgwMCwKICAgIk91dFN1bSI6MSwKICAgIkRlc2NyaXB0aW9uIjoiYXMiLAogICAiTWVyY2hhbnRDb21tZW50cyI6Im5vIGNvbW1lbnQiLAogICAiSW52b2ljZUl0ZW1zIjpbCiAgICAgIHsKICAgICAgICAgIk5hbWUiOiLQotC10YHRgjEiLAogICAgICAgICAiUXVhbnRpdHkiOjEsCiAgICAgICAgICJDb3N0IjowLjUsCiAgICAgICAgICJUYXgiOiJ2YXQyMCIsCiAgICAgICAgICJQYXltZW50TWV0aG9kIjoiZnVsbF9wYXltZW50IiwKICAgICAgICAgIlBheW1lbnRPYmplY3QiOiJjb21tb2RpdHkiCiAgICAgIH0sCiAgICAgIHsKICAgICAgICAgIk5hbWUiOiLQotC10YHRgjIiLAogICAgICAgICAiUXVhbnRpdHkiOjEsCiAgICAgICAgICJDb3N0IjowLjUsCiAgICAgICAgICJUYXgiOiJ2YXQwIiwKICAgICAgICAgIlBheW1lbnRNZXRob2QiOiJmdWxsX3ByZXBheW1lbnQiLAogICAgICAgICAiUGF5bWVudE9iamVjdCI6ImNvbW1vZGl0eSIsCiAgICAgICAgICJOb21lbmNsYXR1cmVDb2RlIjoiSVlWSVRDVVIlWEVeJFglQ15UJlZJVENeUlgmJUVSQ15USVJYJSZFUkNVSVRSWEUmWlglUl5DVElSXlhVRSVaTjFtOUUrMcKmPzVPPzbCpj8xNjgiCiAgICAgIH0KICAgXQp9

2. Закодируйте строку с помощью HMAC и выбранного алгоритма. В качестве секретного ключа используйте идентификатор магазина и пароль №1 в формате robo-demo-test:pass1. Представьте результат в Base64.

   IzOJPWjDkzajNttt8dFQFg

3. Соберите окончательный токен, соединив три части через точку.

   eyJ0eXAiOiJKV1QiLCJhbGciOiJNRDUifQ.ewogICAiTWVyY2hhbnRMb2dpbiI6InJvYm8tZGVtby10ZXN0IiwKICAgIkludm9pY2VUeXBlIjoiT25lVGltZSIsCiAgICJDdWx0dXJlIjoicnUiLAogICAiSW52SWQiOjgwMCwKICAgIk91dFN1bSI6MSwKICAgIkRlc2NyaXB0aW9uIjoiYXMiLAogICAiTWVyY2hhbnRDb21tZW50cyI6Im5vIGNvbW1lbnQiLAogICAiSW52b2ljZUl0ZW1zIjpbCiAgICAgIHsKICAgICAgICAgIk5hbWUiOiLQotC10YHRgjEiLAogICAgICAgICAiUXVhbnRpdHkiOjEsCiAgICAgICAgICJDb3N0IjowLjUsCiAgICAgICAgICJUYXgiOiJ2YXQyMCIsCiAgICAgICAgICJQYXltZW50TWV0aG9kIjoiZnVsbF9wYXltZW50IiwKICAgICAgICAgIlBheW1lbnRPYmplY3QiOiJjb21tb2RpdHkiCiAgICAgIH0sCiAgICAgIHsKICAgICAgICAgIk5hbWUiOiLQotC10YHRgjIiLAogICAgICAgICAiUXVhbnRpdHkiOjEsCiAgICAgICAgICJDb3N0IjowLjUsCiAgICAgICAgICJUYXgiOiJ2YXQwIiwKICAgICAgICAgIlBheW1lbnRNZXRob2QiOiJmdWxsX3ByZXBheW1lbnQiLAogICAgICAgICAiUGF5bWVudE9iamVjdCI6ImNvbW1vZGl0eSIsCiAgICAgICAgICJOb21lbmNsYXR1cmVDb2RlIjoiSVlWSVRDVVIlWEVeJFglQ15UJlZJVENeUlgmJUVSQ15USVJYJSZFUkNVSVRSWEUmWlglUl5DVElSXlhVRSVaTjFtOUUrMcKmPzVPPzbCpj8xNjgiCiAgICAgIH0KICAgXQp9.IzOJPWjDkzajNttt8dFQFg

Отправьте полученную строку в теле POST-запроса (тело заключите в двойные кавычки). В ответе вернется короткая ссылка на оплату.

Деактивация созданного счета или ссылки

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

Используется та же структура и алгоритм формирования токена, что при создании ссылки. В Payload необходимо передать идентификатор магазина и один из идентификаторов счета.

{
  "MerchantLogin": "robo-demo-test",
  "InvId": 851
}

Идентификаторы счета

Параметр	Значение
EncodedId	Последняя часть ссылки счета, например 6hucaX7-BkKNi4lyi-Iu2g в ссылке https://auth.robokassa.ru/merchant/Invoice/6hucaX7-BkKNi4lyi-Iu2g.
Id	Идентификатор счета, возвращается в ответе на создание счета.
InvId	Номер счета, указанный продавцом при создании ссылки. Если не был передан, генерируется автоматически и доступен в ответе на создание счета и в разделе «Выставление счетов».

Запрос статуса созданного счета или ссылки

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

Структура токена совпадает с запросом на создание ссылки. В Payload передайте набор параметров:

В этом методе используется параметр InvoiceTypes (множественное число) — он отличается от InvoiceType, который передается при создании ссылки через CreateInvoice.

{
  "MerchantLogin": "robo-demo-test",
  "CurrentPage": 1,
  "PageSize": 10,
  "InvoiceStatuses": [
    "paid",
    "expired",
    "notpaid"
  ],
  "Keywords": "Продажа курсов",
  "DateFrom": "2025-03-28T08:36:02.651371+00:00",
  "DateTo": "2025-03-28T08:36:02.651371+00:00",
  "IsAscending": true,
  "InvoiceTypes": [
    "onetime",
    "reusable"
  ],
  "PaymentAliases": [
    "Qiwi"
  ],
  "SumFrom": 1.5,
  "SumTo": 10000
}

Описание параметров

Параметр	Значение
CurrentPage	Обязательный. Номер текущей страницы (от 1).
PageSize	Обязательный. Количество записей в ответе.
InvoiceStatuses	Обязательный. Статус счета. Возможные значения: Paid — оплаченные, Expired — просроченные, Notpaid — неоплаченные.
Keywords	Необязательный. Строка ключевых слов для поиска по сумме, идентификатору, описанию или email.
DateFrom	Обязательный. Нижняя граница фильтра по дате создания счета в формате ISO 8601 (YYYY-MM-DDThh:mm:ss.ffffff±hh:mm).
DateTo	Обязательный. Верхняя граница фильтра по дате создания счета.
IsAscending	Необязательный. Флаг сортировки по возрастанию.
InvoiceTypes	Обязательный. Тип ссылки: одноразовая (OneTime) или многоразовая (Reusable).
PaymentAliases	Необязательный. Список псевдонимов способов оплаты.
SumFrom	Необязательный. Минимальная сумма счета.
SumTo	Необязательный. Максимальная сумма счета.