NAV Navbar
Merchant API v2.1.1

Подготовка к интеграции

Регистрация и создание магазина через pikassa.io

​ Для подготовки к интеграции необходимо:

  1. Зарегистрировать личный кабинет Pikassa по кнопке Подключиться на странице pikassa.io;
  2. В личном кабинете создать магазин в разделе Магазины, перейти в настройки магазина и заполнить раздел Общие настройки;
  3. Перейти в раздел настроек магазина Технические настройки и сгенерировать новый секретный ключ (secretPhrase) для формирования подписи;
  4. Если требуется передача уведомлений об изменении статусов счета в одну из ваших систем (Callback), заполнить поле ResultURL адресом для получения уведомлений;
  5. Активировать созданный магазин и получить API Key, связавшись с персональным менеджером.

HTTP-заголовки

Взаимодействие с сервисом происходит посредством передачи HTTP-запросов.

Запросы могут включать следующие заголовки:

Алгоритм формирования ЭЦП

ЭЦП формируется следующим образом:

  1. К сформированному телу запроса (body) добавляется secretPhrase магазина (операция конкатенации)
  2. Вычисляется контрольная сумма по алгоритму md5, кодировка UTF-8
  3. Контрольная сумма переводится в base64

Примеры реализации алгоритма формирования x-sign

Пример на языке C#

Пример на языке PHP

Схема проведения запроса

  1. Магазин отправляет в Pikassa запрос на создание счета;
  2. Pikassa обрабатывает запрос и, если счет создан корректно, возвращает данные, содержащие ссылку для перехода на оплату;
  3. Плательщик переходит по ссылке выбирает способ оплаты и вводит платежные данные;
  4. Pikassa отправляет запрос на списание денежных средств эквайеру;
  5. Pikassa получает ответ об успешной/неуспешной оплате счета от эквайера; происходит переадресация плательщика на страницу магазина
    1. В случае успешной оплаты счета плательщик перенаправляется на страницу, указанную при создании счета в параметре successUrl;
    2. В случае неуспешной оплаты происходит перенаправление на страницу, указанную при создании счета в параметре failUrl;
  6. Pikassa отправляет магазину уведомление об успешной/неуспешной оплате счета; Магазин возвращает ответ-подтверждение о проведенной операции.

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

Метод позволяет создать счет на оплату и отправить его плательщику.

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

curl https://pikassa.io/merchant-api/api/v2/invoices \
  -X POST \
  -H 'x-api-key: <Ключ доступа>' \
  -H 'x-sign: <ЭЦП>' \
  -H 'content-Type: application/json; charset=utf-8' \
  -d '{
    "externalId": "3c5301df-d806-4fb0-9f96-f44d5d2d3827",
    "amount": 105.05,
    "currency": "RUB",
    "description": "Оплата заказа №12080",
    "customerPhone": "+74994550185",
    "customerEmail": "support@pikassa.io",
    "customData": {
        "key1": "value1",
        "key2": 5
    },
    "successUrl": "https://empty.com/successUrl",
    "failUrl": "https://empty.com/failUrl",
    "deliveryMethod": "URL",
    "expirationDate": "2021-03-14 11:08:24.909150+03:00",
    "ofdData": null,
    "preAuth": false,
    "createToken": false
}'
Описание параметров запроса на создание счета
Параметр Обязательный Валидация Описание
externalId Да Уникальный, непустая строка, максимум 100 символов Уникальный внутренний идентификатор счета в системе магазина
amount Да Десятичное число с двумя знаками после запятой. Минимум - 0.01, максимум - 999999999999999.99 Сумма счета, разделитель дробной части - "." (точка)
currency Нет RUB, EUR, USD. По умолчанию RUB Валюта, в которой будет оплачен счет
description Да Непустая строка, максимум 1000 символов Описание счета
customerPhone Нет Номер телефона в международном формате (+7xxxxxxxxxx) Номер телефона плательщика. Обязательный для способа доставки SMS
customerEmail Нет Адрес электронной почты Адрес электронной почты плательщика. Обязательный для способа доставки EMAIL
customData Нет Различная служебная информация, поле будет возвращено в уведомлении об оплате счета. Поле любого типа, поддерживаемого форматом json
successUrl Нет URL URL-адрес страницы магазина, на которую будет переправлен плательщик в случае успешно оплаченного счета, максимум 100 символов
failUrl Нет URL URL-адрес страницы магазина, на которую будет переправлен плательщик в случае неуспешно оплаченного счета, максимум 100 символов
deliveryMethod Нет EMAIL, SMS или URL (по умолчанию) Метод доставки счета клиенту.
Метод EMAIL — доставка счета в письме по адресу электронной почты
SMS — доставка счета в SMS-сообщении
URL — получение ссылки на оплату в ответе на запрос на создание счета
expirationDate Нет Дата в формате yyyy-MM-dd HH:mm:ss.fffZZZ, должна быть больше текущей даты Дата и время действия счета. Если в запросе указать данный параметр, то произвести оплату по данному счету можно будет только до момента наступления указанных даты и времени. Если по истечении заданного времени и даты оплата не была совершена, счет переходит в состояние 6 (InoiceCancelled), и при попытке его оплатить пользователь будет перенаправлен на страницу ошибки. Пример: 2022-04-28 17:42:30.220+03:00
ofdData Нет Данные для фискализации. В зависимости от настроек магазина отправляются тому или иному провайдеру фискальных данных. (см. Отправка данных в соответствии с ФЗ-54)
preAuth Нет boolean, по умолчанию false Признак холдирования. Значение = true сообщает о необходимости захолдировать сумму, равную сумме счета, на банковском счету плательщика (при двухстадийном платеже)
createToken Нет boolean, по умолчанию false Признак создания платежного токена. Значение = true сообщает о необходимости создания платежного токена для дальнейшего осуществления списания средств с банковской карты, совершаемого без подтверждения клиентом. (используется при создании подписки). Для возможности создания платежных токенов необходимо связаться с менеджером и включить эту возможность для магазина.

Пример успешного ответа на запрос на создание счета

{
    "success": true,
    "data": {
        "uuid": "1fd64b0c-a8e7-4dc1-a799-f0cfa3ebad3a",
        "externalId": "3c5301df-d806-4fb0-9f96-f44d5d2d3827",
        "paymentLink": "https://pikassa.io/portal2/pay/i/cd422358-56dd-4039-9559-c1fb766dbbbd"
    }
}
Описание параметров успешного ответа при создании счета
Параметр Обязательный Валидация Описание
success Да Всегда true Признак успешности выполнения команды
data Да Объект Данные счета
Описание параметров объекта data
Параметр Обязательный Валидация Описание
uuid Да Непустая строка Идентификатор счета в Pikassa
externalId Да Уникальный, непустая строка Уникальный внутренний идентификатор счета в системе магазина
paymentLink Да Непустая строка Платежная ссылка для перенаправления

Пример ответа с ошибкой на запрос на создание счета

{
    "success": false,
    "error": {
        "code": "1",
        "message": "Ошибка создания счета"
    }
}
Описание параметров ответа с ошибкой создания счета
Параметр Обязательный Валидация Описание
success Да Всегда false Признак успешности выполнения команды
error Да Объект Данные об ошибке
Описание параметров объекта error
Параметр Обязательный Валидация Описание
code Да Непустая строка Код ошибки (см. Описание кодов ошибок)
message Да Непустая строка Описание ошибки

Авторизация захолдированного счета

Метод позволяет списать захолдированную сумму с карты плательщика. Используется при двухстадийном платеже.

Пример запроса на авторизацию счета

curl https://pikassa.io/merchant-api/api/v2/invoices/<uuid>/auth \
  -X PUT \
  -H 'x-api-key: <Ключ доступа>' \
  -H 'x-sign: <ЭЦП>' \
  -H 'content-Type: application/json; charset=utf-8' \
  -d '{
    "requestId": "1df6b40c-e8a7-fcd1-a799-a0cfa3edab3a",
    "amount": 123.12
}'

uuid - идентификатор счета, полученный в успешном ответе при создании захолдированного счета.

Описание параметров запроса на авторизацию счета
Параметр Обязательный Валидация Описание
requestId Да Уникальный, непустая строка Идентификатор запроса
amount Да Десятичное число с двумя знаками после запятой Итоговая сумма для списания средств по захолдированному счету. Не может превышать сумму, указанную при создании счета

Пример успешного ответа на запрос на авторизацию счета

{
    "success": true,
    "data": {
        "uuid": "1fd64b0c-a8e7-4dc1-a799-f0cfa3ebad3a",
        "requestId": "d1f6b55c-e8a1-add7-a719-a1cfd3eda3ad"
    }
}
Описание параметров успешного ответа на запрос на авторизацию счета
Параметр Обязательный Валидация Описание
success Да Всегда true Признак успешности выполнения команды
data Да Объект Данные платежа
Описание параметров объекта data
Параметр Обязательный Валидация Описание
uuid Да Непустая строка Идентификатор счета
requestId Да Уникальный, непустая строка Идентификатор запроса

Пример ответа с ошибкой на запрос на авторизацию счета

{
    "success": false,
    "error": {
        "code": "2",
        "message": "Ошибка авторизации платежа"
    }
}
Описание параметров ответа с ошибкой на запрос на авторизацию счета
Параметр Обязательный Валидация Описание
success Да Всегда false Признак успешности выполнения команды
error Да Объект Данные об ошибке
Описание параметров объекта error
Параметр Обязательный Валидация Описание
code Да Непустая строка Код ошибки (см. Описание кодов ошибок)
message Да Непустая строка Описание ошибки

Отмена счета

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

Также метод используется при двухстадийном платеже и позволяет разблокировать ранее захолдированную сумму на карте плательщика.

Пример запроса на отмену счета

curl https://pikassa.io/merchant-api/api/v2/invoices/<uuid>/cancel \
  -X PUT \
  -H 'x-api-key: <Ключ доступа>' \
  -H 'x-sign: <ЭЦП>' \
  -H 'content-Type: application/json; charset=utf-8' \
  -d '{
    "requestId": "1df6b40c-e8a7-fcd1-a799-a0cfa3edab3a",
    "reason": "Отменен"
}'

uuid - идентификатор счета, полученный в успешном ответе при создании счета.

Описание параметров запроса на отмену счета
Параметр Обязательный Валидация Описание
requestId Да Уникальный, непустая строка Идентификатор запроса
reason Да Непустая строка Данные о причине отмены счета

Пример успешного ответа на запрос на отмену счета

{
    "success": true,
    "data": {
        "uuid": "1fd64b0c-a8e7-4dc1-a799-f0cfa3ebad3a",
        "requestId": "d1f6b55c-e8a1-add7-a719-a1cfd3eda3ad"
    }
}
Описание параметров успешного ответа на запрос на отмену счета
Параметр Обязательный Валидация Описание
success Да Всегда true Признак успешности выполнения команды
data Да Объект Данные отменяемого счета
Описание параметров объекта data
Параметр Обязательный Валидация Описание
uuid Да Непустая строка Идентификатор отменяемого счета
requestId Да Уникальный, непустая строка Идентификатор запроса

Пример ответа с ошибкой на запрос на отмену счета

{
    "success": false,
    "error": {
        "code": "3",
        "message": "error"
    }
}
Описание параметров ответа с ошибкой на запрос на отмену счета
Параметр Обязательный Валидация Описание
success Да Всегда false Признак успешности выполнения команды
error Да Объект Данные об ошибке
Описание параметров объекта error
Параметр Обязательный Валидация Описание
code Да Непустая строка Код ошибки (см. Описание кодов ошибок)
message Да Непустая строка Описание ошибки

Возврат

Используется для возврата денежных средств. Срок возврата зависит от банка, выпустившего карту плательщика.

Пример запроса на возврат

curl https://pikassa.io/merchant-api/api/v2/invoices/<uuid>/refund \
  -X PUT \
  -H 'x-api-key: <Ключ доступа>' \
  -H 'x-sign: <ЭЦП>' \
  -H 'content-Type: application/json; charset=utf-8' \
  -d '{
    "requestId": "1df6b40c-e8a7-fcd1-a799-a0cfa3edab3a",
    "amount": 123.12,
    "reason": "Возврат по счету №22530"
}'

uuid - идентификатор счета, полученный в успешном ответе при создании счета.

Описание параметров запроса на возврат
Параметр Обязательный Валидация Описание
requestId Да Уникальный. Непустая строка Идентификатор запроса
amount Да Десятичное число с двумя знаками после запятой Сумма возврата. Не может превышать сумму amount, указанную при создании счета.
reason Да Непустая строка Данные о причине возврата

Пример успешного ответа на запрос на возврат

{
    "success": true,
    "data": {
        "uuid": "1fd64b0c-a8e7-4dc1-a799-f0cfa3ebad3a",
        "requestId": "d1f6b55c-e8a1-add7-a719-a1cfd3eda3ad"
    }
}
Описание параметров успешного ответа на запрос на возврат
Параметр Обязательный Валидация Описание
success Да Всегда true Признак успешности выполнения команды
data Да Объект Данные счета
Описание параметров объекта data
Параметр Обязательный Валидация Описание
uuid Да Непустая строка Идентификатор счета, по которому выполняется возврат
requestId Да Уникальный. Непустая строка Идентификатор запроса

Пример ответа с ошибкой на запрос на возврат

{
    "success": false,
    "error": {
        "code": "6",
        "message": "error"
    }
}
Описание параметров ответа с ошибкой на запрос на возврат
Параметр Обязательный Валидация Описание
success Да Всегда false Признак успешности выполнения команды
error Да Объект Данные об ошибке
Описание параметров объекта error
Параметр Обязательный Валидация Описание
code Да Непустая строка Код ошибки (см. Описание кодов ошибок)
message Да Непустая строка Описание ошибки

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

Метод позволяет запросить данные счета: статус счета, итоговая сумма счета, метод оплаты и др.

curl https://pikassa.io/merchant-api/api/v2/invoices/<uuid> \
  -X GET \
  -H 'x-api-key: <Ключ доступа>' \
  -H 'content-Type: application/json; charset=utf-8' \

uuid - идентификатор счета, полученный в успешном ответе при создании счета.

Пример запроса на получение данных

Описание параметров запроса на получение данных
Параметр Обязательный Валидация Описание
uuid Да Непустая строка Идентификатор счета

Пример успешного ответа на запрос на получение данных

{
    "externalId": "3c5301df-d806-4fb0-9f96-f44d5d2d3827",
    "uuid": "1fd64b0c-a8e7-4dc1-a799-f0cfa3ebad3a",
    "amount": 105.05,
    "finalAmount": 123.12,
    "currency": "RUB",
    "description": "Счет на оплату заказа №12080",
    "customerPhone": "+74994550185",
    "customerEmail": "support@pikassa.io",
    "customData": {
        "key1": "value1",
        "key2": 5
    },
    "successUrl": "http://empty.com/successUrl",
    "failUrl": "http://empty.com/failUrl",
    "deliveryMethod": "URL",
    "subscriptionUuid": "945c06b4-b791-4f2c-89b1-a45f78cb1568",
    "expirationDate": "2021-03-14 11:08:24.0909150+03:00",
    "ofdData": null,
    "preAuth": false,
    "status": {
        "name": "InvoicePaid",
        "time": "2020-03-14 11:08:24.0909150+03:00",
        "message": "message"
    },
    "payments": [
        {
            "paymentMethod": "BankCard",
            "details": {
                "account": "411111******1111",
                "paymentToken": "837c06b4-b791-4f2c-89b1-a45f78cb1568"
            }
        }
    ]
}
Описание параметров успешного ответа на запрос на получение данных
Параметр Обязательный Валидация Описание
externalId Да Уникальный, непустая строка Уникальный внутренний идентификатор счета в системе магазина
uuid Да Уникальный, непустая строка Идентификатор счета
amount Да Десятичное число с двумя знаками после запятой Сумма счета, разделитель дробной части - "." (точка)
finalAmount Да Десятичное число с двумя знаками после запятой Сумма счета с учетом возвратов и частичной авторизации
currency Да, по умолчанию RUB RUB, EUR, USD Валюта, в которой будет оплачен счет
description Да Непустая строка Описание счета
customerPhone Нет (Да для deliveryMethod = SMS) Номер телефона в международном формате (+7xxxxxxxxxx) Номер телефона плательщика
customerEmail Нет (Да для deliveryMethod = EMAIL) Адрес электронной почты Адрес электронной почты плательщика
customData Нет Объект json Дополнительные данные счета
successUrl Нет URL Адрес для перенаправления плательщика в случае успешной оплаты
failUrl Нет URL Адрес для перенаправления плательщика в случае неуспешной оплаты
deliveryMethod Да EMAIL, SMS или URL Метод доставки счета
subscriptionUuid Нет Непустая строка Идентификатор подписки, в случае если счет был создан по подписке
expirationDate Нет Дата в формате yyyy-MM-dd HH:mm:ss.fffZZZ, должна быть больше текущей даты Дата, по истечении которой счет нужно отменить, например: 2021-03-14 11:08:24.0909150+00:00
ofdData Нет Объект json Данные для формирования фискального чека (описание в разделе "Отправка данных в соответствии с ФЗ-54")
preAuth Да boolean Признак холдирования. Значение = true сообщает о необходимости захолдировать сумму, равную сумме счета, на банковском счету плательщика
status Да Объект Данные о статусе заказа (см. Перечень возможных значений статусов счета)
payments Нет Объект Данные о платежах по счету
Описание параметров объекта status
Параметр Обязательный Валидация Описание
name Да Непустая строка Название статуса
time Да Дата в формате yyyy-MM-dd HH:mm:ss.fffZZZ Дата перехода в статус
message Да Непустая строка Описание причины перехода в статус
Описание параметров объекта payments
Параметр Обязательный Валидация Описание
paymentMethod Да Непустая строка Метод оплаты, выбранный плательщиком в процессе оплаты (см. Перечень возможных значений методов оплаты)
details Нет Объект Дополнительные данные платежа
Описание параметров объекта details
Параметр Обязательный Валидация Описание
account Нет Непустая строка Данные об аккаунте плательщика
paymentToken Нет Непустая строка Идентификатор платежного токена

Пример ответа с ошибкой на запрос на получение данных

{
    "success": false,
    "error": {
        "code": "5",
        "message": "error"
    }
}
Описание параметров ответа с ошибкой на запрос на получение данных
Параметр Обязательный Валидация Описание
success Да Всегда false Признак успешности выполнения команды
error Да Объект Данные об ошибке
Описание параметров объекта error
Параметр Обязательный Валидация Описание
code Да Непустая строка Код ошибки (см. Описание кодов ошибок)
message Да Непустая строка Описание ошибки

Оплата счета

Метод позволяет передать детали платежа для осуществления оплаты.

Пример запроса оплаты счета

curl https://pikassa.io/merchant-api/api/v2/invoices/<uuid>/pay \
  -X PUT \
  -H 'x-api-key: <Ключ доступа>' \
  -H 'content-Type: application/json; charset=utf-8' \
  -d '{
    "requestId": "1df6b40c-e8a7-fcd1-a799-a0cfa3edab3a",
    "paymentMethod": "BankCard",
    "details": {
        "key1": "value1",
        "key2": "value2"
        }
    }
}'

uuid - идентификатор счета, полученный в успешном ответе при создании счета.

Описание параметров запроса оплаты счета
Параметр Обязательный Валидация Описание
requestId Да Уникальный. Непустая строка Идентификатор запроса
paymentMethod Да Непустая строка Метод оплаты, выбранный плательщиком в процессе оплаты (см. Перечень возможных значений методов оплаты)
details Да Объект Детали платежа
Описание параметров details для способа оплаты BankCard
Параметр Обязательный Валидация Описание
pan Да Непустая строка Номер банковской карты
cardHolder Нет Непустая строка Имя и фамилия владельца банковской карты латинскими буквами
cvc Да Непустая строка CVC банковской карты
expYear Да Непустая строка Год окончания срока действия банковской карты
expMonth Да Непустая строка Месяц окончания срока действия банковской карты

Пример успешного ответа на запрос оплаты счета, если не требуется перенаправление пользователя

{
    "success": true,
    "data": {
        "uuid": "1fd64b0c-a8e7-4dc1-a799-f0cfa3ebad3a",
        "requestId": "d1f6b55c-e8a1-add7-a719-a1cfd3eda3ad"
    }
}
Описание параметров успешного ответа на запрос оплаты счета
Параметр Обязательный Валидация Описание
success Да Всегда true Признак успешности выполнения команды
data Да Объект Данные счета
Описание параметров объекта data
Параметр Обязательный Валидация Описание
uuid Да Непустая строка Идентификатор счета, для которого выполняется оплата счета
requestId Да Уникальный. Непустая строка Идентификатор запроса

Пример успешного ответа на запрос оплаты счета, если требуется перенаправление пользователя

{
    "success": true,
    "data": {
        "uuid": "1fd64b0c-a8e7-4dc1-a799-f0cfa3ebad3a",
        "requestId": "d1f6b55c-e8a1-add7-a719-a1cfd3eda3ad",
        "redirect": {
            "url": "http://example.com",
            "method": "POST",
            "params": [
                {
                    "name": "name1",
                    "value": "value1"
                }
            ]
        }
    }
}

Перенаправление может потребоваться в случае необходимости ввода кода 3DS.

Описание параметров успешного ответа на запрос оплаты счета
Параметр Обязательный Валидация Описание
success Да Всегда true Признак успешности выполнения команды
data Да Объект Данные счета
Описание параметров объекта data
Параметр Обязательный Валидация Описание
uuid Да Непустая строка Идентификатор счета, для которого выполняется оплата по счету
requestId Да Уникальный. Непустая строка Идентификатор запроса
redirect Да Объект Данные для перенаправления пользователя
Описание параметров объекта redirect
Параметр Обязательный Валидация Описание
url Да URL Адрес для перенаправления плательщика
method Да Непустая строка http метод
params Нет Объект Дополнительные данные

Пример ответа с ошибкой на запрос оплаты счета

{
    "success": false,
    "error": {
        "code": "5",
        "message": "error"
    }
}
Описание параметров ответа с ошибкой на запрос оплаты счета
Параметр Обязательный Валидация Описание
success Да Всегда false Признак успешности выполнения команды
error Да Объект Данные об ошибке
Описание параметров объекта error
Параметр Обязательный Валидация Описание
code Да Непустая строка Код ошибки (см. Описание кодов ошибок)
message Да Непустая строка Описание ошибки

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

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

Алгоритм работы с подпиской

  1. Магазин отправляет в Pikassa запрос на создание счета, где указывает параметр createToken=true для создания платежного токена. Предварительно данную возможность необходимо согласовать с менеджером;
  2. Логика оплаты счета описана в "Схеме проведения запроса";
  3. В случае если счет был успешно оплачен, то Pikassa отправляет магазину уведомление об успешной оплате, которое содержит идентификатор платежного токена; Магазин возвращает ответ-подтверждение о проведенной операции.
  4. Магазин отправляет в Pikassa запрос на создание подписки, где указывает идентификатор платежного токена первого счета и данные подписки;
  5. Pikassa обрабатывает запрос и если подписка создана корректно, возвращает ответ, содержащий идентификатор подписки;
  6. В случае если наступил момент следующей оплаты счета Pikassa создает счет и проводит его аналогично первому платежу, но списание средств осуществляется уже без подтверждения клиентом;
  7. Pikassa отправляет магазину уведомление об успешной/неуспешной оплате счета, которое содержит идентификатор подписки, на основе которой создан счет; Магазин возвращает ответ-подтверждение о проведенной операции.

Пример запроса на создание подписки

curl https://pikassa.io/merchant-api/api/v2/subscriptions \
  -X POST \
  -H 'x-api-key: <Ключ доступа>' \
  -H 'x-sign: <ЭЦП>' \
  -H 'content-Type: application/json; charset=utf-8' \
  -d '{
    "requestId": "1df6b40c-e8a7-fcd1-a799-a0cfa3edab3a",
    "paymentToken": "d1f6b55c-e8a1-add7-a719-a1cfd3eda3ad",
    "customerEmail": "support@pikassa.io",
    "name": "Подписка на сервис",
    "amount": 444.44,
    "startDate": "2020-07-01 00:00:00.000000+03:00",
    "interval": "MONTH",
    "period": 1,
    "maxPeriods": 12,
    "currency": "RUB"
}'

paymentToken - идентификатор платежного токена, полученный в нотификации (callback), после оплаты счета.

Описание параметров запроса на создание подписки
Параметр Обязательный Валидация Описание
requestId Да Уникальный, непустая строка, максимум 100 символов Идентификатор запроса
paymentToken Да Непустая строка, максимум 100 символов Идентификатор платежного токена
customerEmail Да Адрес электронной почты, максимум 100 символов Email плательщика
name Да Непустая строка, максимум 100 символов Название подписки
amount Да Десятичное число с двумя знаками после запятой Сумма периодического списания
startDate Да Дата в формате yyyy-MM-dd HH:mm:ss.fffZZZ Дата и время первого периодического списания
interval Да DAY, WEEK, MONTH Интервал
period Да Целое число Период. В комбинации с интервалом, 1 MONTH - раз в месяц, 2 WEEK - 1 раз в 2 недели.
maxPeriods Нет Целое число Максимальное количество платежей в подписке
currency Нет RUB, EUR, USD Валюта, в которой будет оформлена подписка (по умолчанию RUB)

Пример успешного ответа на запрос на создание подписки

{
    "success": true,
    "data": {
        "uuid": "1fd64b0c-a8e7-4dc1-a799-f0cfa3ebad3a",
        "requestId": "d1f6b55c-e8a1-add7-a719-a1cfd3eda3ad"
    }
}
Описание параметров успешного ответа на запрос на создания подписки
Параметр Обязательный Валидация Описание
success Да Всегда true Признак успешности выполнения команды
data Да Объект Данные платежа
Описание параметров объекта data
Параметр Обязательный Валидация Описание
uuid Да Непустая строка Идентификатор подписки
requestId Да Уникальный, непустая строка Идентификатор запроса

Пример ответа с ошибкой на запрос на создание подписки

{
    "success": false,
    "error": {
        "code": "7",
        "message": "Ошибка создания подписки"
    }
}
Описание параметров ответа с ошибкой на запрос на создание подписки
Параметр Обязательный Валидация Описание
success Да Всегда false Признак успешности выполнения команды
error Да Объект Данные об ошибке
Описание параметров объекта error
Параметр Обязательный Валидация Описание
code Да Непустая строка Код ошибки (см. Описание кодов ошибок)
message Да Непустая строка Описание ошибки

Google Pay

Google Pay — это способ оплаты заказов, позволяющий в один клик совершать платежи без ввода банковских реквизитов. GPay доступен с любых устройств, имеющих Google аккаунт. Pikassa принимает платежи через Google Pay двумя методами:

Требования к сайту магазина для прямой интеграции с Google Pay API

  1. При реализации подключения руководствоваться документацией.
  2. Необходимо соблюсти требования по брендированию при размещении кнопки GPay на форме оплаты.
  3. Убедиться, что товары или услуги не входят в перечень запрещенных.
  4. Сверить реализацию с контрольным списком.
  5. Пройти процедуру проверки.

Сценарий оплаты

  1. Клиент в интернет-магазине оформляет заказ и для оплаты выбирает способ GPay.
  2. Магазин отправляет запрос на создание счета в Pikassa;
  3. Pikassa обрабатывает запрос и, если счет создан корректно, возвращает его уникальный идентификатор uuid.
  4. Магазин отправляет запрос на оплату в Google Pay API.
  5. Система Google Pay по полученным платежным данным формирует токен.
  6. Магазин в ответ на запрос получает сформированный токен.
  7. Магазин формирует запрос на передачу деталей платежа в систему Pikassa, где в адресе запроса указывает uuid полученный при создании счета, а в параметре details - токен полученный от Google Pay API.
  8. Pikassa обрабатывает запрос и отправляет магазину уведомление об успешной/неуспешной оплате счета; Магазин возвращает ответ-подтверждение о проведенной операции.

Примеры запросов в Google Pay API

//Проверка на доступность GPay для данного устройства
const readyToPayRequest = {
    "apiVersion": 2,
    "apiVersionMinor": 0,
    "allowedPaymentMethods": [
        {
            "type": "CARD",
            "parameters": {
                "allowedAuthMethods": ["PAN_ONLY", "CRYPTOGRAM_3DS"],
                "allowedCardNetworks": ["MASTERCARD", "VISA"]
            }
        }
    ]
}
//Запрос на оплату в Google Pay API
const paymentDataRequest = {
    "apiVersion": 2,
    "apiVersionMinor": 0,
    "allowedPaymentMethods": [
        {
            "type": "CARD",
            "parameters": {
                "allowedAuthMethods": ["PAN_ONLY", "CRYPTOGRAM_3DS"],
                "allowedCardNetworks": ["MASTERCARD", "VISA"]
            },
            "tokenizationSpecification": {
                "type": "PAYMENT_GATEWAY",
                "parameters": {
                    "gateway": "pikassa",
                    "gatewayMerchantId": "1fd64b0c-a8e7-4dc1-a799-f0cfa3ebad3a"
                }
            }
        }
    ],
    "transactionInfo": {
        "countryCode": "RU",
        "currencyCode": "RUB",
        "totalPriceStatus": "FINAL",
        "totalPrice": "123.12"
    }
}

В примере продемонстрированы 2 запроса:

Описание параметров
Параметр Обязательный Валидация Описание
apiVersion Да Целое число Основной номер версии API - 2.
apiVersionMinor Да Целое число Дополнительный номер версии API - 0.
allowedPaymentMethods Да Объект Поддерживаемые поля для аутентификации транзакций по карте
transactionInfo Да Объект Данные о транзакции
Объект allowedPaymentMethods
Параметр Обязательный Валидация Описание
type Да Непустая строка Идентификатор поддерживаемого способа оплаты - CARD
parameters Да Объект Параметры указанного способа оплаты
tokenizationSpecification Да, для запроса paymentDataRequest Объект Настройка аккаунта или поставщика механизма расшифровки для получения платежной информации
Объект allowedPaymentMethods.parameters
Параметр Обязательный Валидация Описание
allowedCardNetworks Да Непустая строка Список доступных платежных систем
* MasterCard
* VISA
allowedCardAuthMethods Да Непустая строка Методы аутентификации:
* PAN_ONLY - метод аутентификации для платежных карт, данные которых хранятся в аккаунте Google.
* CRYPTOGRAM_3DS - метод аутентификации для карт, данные которых хранятся в виде токенов для устройств Android.
Объект allowedPaymentMethods.tokenizationSpecification
Параметр Обязательный Валидация Описание
type Да Непустая строка Тип токенизации для способа оплаты - PAYMENT_GATEWAY
parameters Да Объект Параметры, связанные с типом токенизации выбранного способа оплаты
Объект allowedPaymentMethods.tokenizationSpecification.parameters
Параметр Обязательный Валидация Описание
gateway Да Непустая строка Поставщик платежных услуг - pikassa
gatewayMerchantId Да Непустая строка Идентификатор магазина в системе pikassa - API Key магазина
Объект transactionInfo
Параметр Обязательный Валидация Описание
countryCode Да, для стран ЕЭЗ Непустая строка Код страны, где обрабатывается транзакция, в соответствии со стандартом ISO 3166-1 alpha-2 - RU
currencyCode Да Непустая строка Алфавитный код валюты в соответствии со стандартом ISO 4217 - RUB
totalPriceStatus Да Непустая строка Статус итоговой цены
totalPrice Да, для стран ЕЭЗ Непустая строка Общая сумма транзакции с возможностью округления до двух знаков после запятой

Перечень возможных значений статусов счета

Название Описание
InvoiceCreated Счет создан
InvoicePaymentCreated Платеж по счету создан
InvoicePaid Счет оплачен
InvoiceFailed Ошибка при оплате счета
InvoiceRefunded Выполнен возврат
InvoicePreAuthorized Средства захолдированы
InvoiceCancelled Счет отменен
InvoicePartlyRefunded Выполнен частичный возврат

Перечень возможных значений методов оплаты

Название Описание
BankCard Оплата банковской картой
WMR Оплата через Webmoney
YandexMoney Оплата через YandexMoney
Mobile Оплата с использованием номера мобильного телефона

Оповещение об изменении статуса счета

Оповещение об изменении статуса (Callback) происходит путем отправки POST-запроса по адресу, указанному в настройках магазина (раздел Технические настройки , параметр Result url)

Если на оповещение получен невалидный ответ/валидный ответ с ошибкой, или же ответ не получен, система отправляет повторное оповещение позднее. Оповещение отправляется повторно конечное число раз.

Пример оповещения от Pikassa

{
    "externalId": "3c5301df-d806-4fb0-9f96-f44d5d2d3827",
    "uuid": "1fd64b0c-a8e7-4dc1-a799-f0cfa3ebad3a",
    "amount": 105.05,
    "finalAmount": 123.12,
    "currency": "RUB",
    "description": "Счет на оплату заказа №12080",
    "customerPhone": "+74994550185",
    "customerEmail": "support@pikassa.io",
    "customData": {
        "key1": "value1",
        "key2": 5
    },
    "successUrl": "http://empty.com/successUrl",
    "failUrl": "http://empty.com/failUrl",
    "deliveryMethod": "URL",
    "subscriptionUuid": "945c06b4-b791-4f2c-89b1-a45f78cb1568",
    "expirationDate": "2021-03-14 11:08:24.909150+03:00",
    "ofdData": null,
    "preAuth": false,
    "status": {
        "name": "InvoicePaid",
        "time": "2019 -03-14 11:08:24.0909150+03:00",
        "message": "message"
    },
    "payments": [
        {
            "paymentMethod": "BankCard",
            "details": {
                "account": "411111******1111",
                "paymentToken": "837c06b4-b791-4f2c-89b1-a45f78cb1568"
            }
        }
    ]
}
Описание параметров оповещения от Pikassa
Параметр Обязательный Валидация Описание
externalId Да Уникальный, непустая строка Уникальный внутренний идентификатор счета в системе магазина
uuid Да Уникальный, непустая строка Идентификатор счета
amount Да Десятичное число с двумя знаками после запятой Сумма счета, разделитель дробной части - "." (точка)
finalAmount Да Десятичное число с двумя знаками после запятой Сумма счета с учетом возвратов и частичной авторизации, разделитель дробной части - "." (точка)
currency Да RUB, EUR, USD Валюта счета
description Да Непустая строка Описание счета
customerPhone Нет Номер телефона в международном формате (+7xxxxxxxxxx) Номер телефона плательщика. Обязателен для deliveryMethod = SMS
customerEmail Нет Адрес электронной почты Адрес электронной почты плательщика. Обязателен для deliveryMethod = EMAIL
customData Нет Объект json Дополнительные данные счета
successUrl Нет URL Адрес для перенаправления плательщика в случае успешной оплаты
failUrl Нет URL Адрес для перенаправления плательщика в случае неуспешной оплаты
deliveryMethod Да EMAIL, SMS или URL Метод доставки счета
subscriptionUuid Нет Непустая строка Идентификатор подписки, в случае если счет был создан по подписке
expirationDate Нет Дата в формате yyyy-MM-dd HH:mm:ss.fffZZZ, должна быть больше текущей даты Дата, по истечении которой счет будет отменен (переведен в статус Cancelled), если не произошла оплата. Например: 2021-03-14 11:08:24.0909150+03:00
ofdData Нет Объект json Данные для формирования фискального чека (см. файл-приложение Отправка данных в налоговую.pdf
preAuth Да boolean Признак холдирования платежа по счету. true - счет создан с холдированием средств, false - счет создан без холдирования средств
status Да Объект Данные о статусе счета (см. Перечень возможных значений статусов счета)
payments Да Объект Данные о платежах по счету
Описание параметров объекта status
Параметр Обязательный Валидация Описание
name Да Непустая строка Название статуса
time Да Дата в формате yyyy-MM-dd HH:mm:ss.fffZZZ Дата перехода в статус, например: 2021-03-14 11:08:24.0909150+03:00
message Да Непустая строка Описание причины перехода в статус
Описание параметров объекта payments
Параметр Обязательный Валидация Описание
paymentMethod Да Непустая строка Метод оплаты, выбранный плательщиком в процессе оплаты (см. Перечень возможных значений статусов счета)
details Нет Объект Дополнительные данные платежа
Описание параметров объекта details
Параметр Обязательный Валидация Описание
account Нет Непустая строка Данные об аккаунте плательщика
paymentToken Нет Непустая строка Идентификатор платежного токена

Пример ожидаемого успешного ответа от системы мерчанта на оповещение от Pikassa

{
    "success": true,
    "uuid": "1fd64b0c-a8e7-4dc1-a799-f0cfa3ebad3a"
}

Пример ожидаемого ответа с ошибкой от системы мерчанта на оповещение от Pikassa

{
    "success": false,
    "uuid": "1fd64b0c-a8e7-4dc1-a799-f0cfa3ebad3a"
}
Описание параметров ожидаемых ответов от системы мерчанта на оповещение от Pikassa
Параметр Обязательный Валидация Описание
success Да true/ false Признак успешности выполнения команды
uuid Да Непустая строка Идентификатор счета

Описание кодов ошибок

Код ошибки Описание ошибки
1 Ошибка создания счета
2 Ошибка авторизации платежа
3 Ошибка отмены платежа
5 Ошибка при получении данных
6 Ошибка выполнения возврата
-1 Системная ошибка

Тестирование

Тестовые карты для проведения платежей и осуществления выплат (для тестовых магазинов Pikassa)

Номер карты (PAN) Авторизационные данные Тип операции Результат
4111111111111111 expiration date = 12/24; сvc/cvv2 = 123; 3ds = 123456 Платеж Успешно
Любой expiration date больше текущей даты; любые сvc/cvv2/3ds Платеж Отклонен
4111111111111111 Выплата Успешно
5555555555555599 Выплата Ожидание
4222222222222222 Выплата Отклонена (Недостаточно средств)

Отправка данных в соответствии с ФЗ-54

Для отправки фискальных данных используется протокол, совместимый с протоколом АТОЛ; поддерживаемый провайдер данных — АТОЛ. Для подключения возможности передавать фискальные данные необходимо сообщить данные аккаунта АТОЛ менеджеру Pikassa. Важно: Параметры, которые не должны быть указаны в JSON схеме: timestamp, external_id, service.

Схема и пример данных ОФД

Схема запроса JSON , пример 1 и пример 2.

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

Структура параметров запроса

receipt

1.client

1.1. email

1.2.phone

2.company

2.1. email

2.2. sno

2.3. inn

2.4. payment_address

  1. agent_info

    3.1. type

    3.2. paying_agent

    3.2.1.operation

    3.2.2.phones

    3.3. receive_payments_operator

    3.3.1.phones

    3.4. money_transfer_operator

    3.4.1.phones

    3.4.2.name

    3.4.3.address

    3.4.4.inn

  2. supplier_info

    4.1. phones

  3. items

    5.1. name

    5.2. price

    5.3. quantity

    5.4. sum

    5.5. measurement_unit

    5.6. payment_method

    5.7. payment_object

    5.8. vat

    5.8.1.type

    5.8.2.sum

    5.9. agent_info

    5.9.1.type

    5.9.2.paying_agent

    5.9.2.1.operation

    5.9.2.2.phones

    5.9.3.receive_payments_operator

    5.9.3.1.phones

    5.9.4.money_transfer_operator

    5.9.4.1.name

    5.9.4.2.address

    5.9.4.3.inn

    5.10. supplier_info

    5.10.1.phones

    5.10.2.name

    5.10.3.inn

    5.11. user_data

  4. payments

    6.1.type

    6.2.sum

  5. vats

    7.1.type

    7.2.sum

  6. total

  7. additional_check_props

  8. cashier

  9. additional_user_props

    11.1.name

    11.2.value

Описание полей параметров запроса
Название поля Тип поля Обязательные поля Ограничения Тег ФФД
receipt object Да Чек -
client object Да Атрибуты клиента. -
company object Да Атрибуты компании. -
agent_info object Нет Атрибуты агента.
items array of objects Да Атрибуты позиций. Ограничение по количеству от 1 до 100. -
payments array of objects Да Оплаты. Ограничение по количеству от 1 до 10. -
vats array of objects Нет Атрибуты налогов на чек. Ограничение по количеству от 1 до 6. Необходимо передать либо сумму налога на позицию, либо сумму налога на чек. Если будет переданы и сумма налога на позицию и сумма налога на чек, сервис учтет только сумму налога на чек.
total number Да Итоговая сумма чека в рублях с заданным в CMS округлением: целая часть не более 8 знаков; дробная часть не более 2 знаков. Сумму чека можно округлить, но не более, чем на 99 копеек. При регистрации в ККТ происходит расчёт фактической суммы: суммирование значений sum позиций.
cashier string Нет ФИО кассира. Максимальная длина строки – 64 символа. 1021 Кассир
additional_check_props object Нет Дополнительный реквизит пользователя. 1084 Дополнительный реквизит пользователя.
Описание подпараметра client
Название поля Тип поля Обязательные поля Ограничения Тег ФФД
client object Да Атрибуты клиента -
email string В запросе обязательно должно быть заполнено хотя бы одно из полей: email или phone. Если заполнены оба поля, ОФД отправит электронный чек только на email. Электронная почта покупателя. Максимальная длина строки – 64 символа. В запросе обязательно должно быть заполнено хотя бы одно из полей: email или phone 1008 Телефон или электронный адрес покупателя
phone string В запросе обязательно должно быть заполнено хотя бы одно из полей: email или phone. Если заполнены оба поля, ОФД отправит электронный чек только на email. Телефон покупателя 1008 Телефон или электронный адрес покупателя
Описание подпараметра company
Название поля Тип поля Обязательные поля Ограничения Тег ФФД
company object Да Атрибуты компании. -
email string Да Электронная почта отправителя чека. Максимальная длина строки – 64 символа 1117 Адрес электронной почты отправителя чека
sno enum (string) Поле необязательно, если у организации один тип налогообложения Система налогообложения. Перечисление со значениями: «osn» – общая СН; «usn_income» – упрощенная СН (доходы); «usn_income_outcome» – упрощенная СН (доходы минус расходы); «envd» – единый налог на вмененный доход; «esn» – единый сельскохозяйственный налог; «patent» – патентная СН Применяемая система налогообложения 1055 Применяемая система налогообложения
inn string Да ИНН организации. Используется для предотвращения ошибочных регистраций чеков на ККТ зарегистрированных с другим ИНН (сравнивается со значением в ФН). Допустимое количество символов 10 или 12. 1018 ИНН пользователя
payment_address string Да Место расчетов. Максимальная длина строки – 256 символов. 1187 Место расчетов
Описание подпараметра agent_info
Название поля Тип поля Обязательные поля Ограничения Тег ФФД
agent_info object Нет Атрибуты агента -
type enum (string) Нет Если передан объект «agent_info», в нём обязательно должно быть передано поле «type». Признак агента (ограничен агентами, введенными в ККТ при фискализации). 1057 Признак агента
paying_agent object Нет Атрибуты платежного агента. -
operation string Нет Наименование операции. Максимальная длина строки – 24 символа. 1044 Операция платежного агента
phones array of strings Нет Телефоны платежного агента. Максимальная длина одной строки массива – 19 символов 1073 Телефон платежного агента
receive_payments_operator object Нет Атрибуты оператора по приему платежей. -
phones array of strings Нет Телефоны оператора по приему платежей. Максимальная длина одной строки массива – 19 символов. 1074 Телефон оператора по приему платежей
money_transfer_operator object Нет Атрибуты оператора перевода. -
phones array of strings Нет Телефоны оператора перевода. Максимальная длина одной строки массива – 19 символов. 1075 Телефон оператора перевода
name string Нет Наименование оператора перевода. Максимальная длина строки – 64 символа 1026 Наименование оператора перевода
address string Нет Адрес оператора перевода. Максимальная длина строки – 256 символов 1005 Адрес оператора перевода
inn string Нет ИНН оператора перевода. Максимальная длина строки – 12 символов. 1016 ИНН оператора перевода

Возможные значения type

«bank_paying_agent» — банковский платежный агент. Оказание услуг покупателю (клиенту) пользователем, являющимся банковским платежным агентом.

«bank_paying_subagent» — банковский платежный субагент. Оказание услуг покупателю (клиенту) пользователем, являющимся банковским платежным субагентом.

«paying_agent» — платежный агент. Оказание услуг покупателю (клиенту) пользователем, являющимся платежным агентом.

«paying_subagent» — платежный субагент. Оказание услуг покупателю (клиенту) пользователем, являющимся платежным субагентом.

«attorney» — поверенный. Осуществление расчета с покупателем (клиентом) пользователем, являющимся поверенным.

«commission_agent» — комиссионер. Осуществление расчета с покупателем (клиентом) пользователем, являющимся комиссионером.

«another» — другой тип агента. Осуществление расчета с покупателем (клиентом) пользователем, являющимся агентом и не являющимся банковским платежным агентом (субагентом), платежным агентом (субагентом), поверенным, комиссионером.

Описание подпараметра supplier_info
Название поля Тип поля Обязательные поля Ограничения Тег ФФД
supplier_info object Нет. Поле обязательно, если передан «agent_info» Атрибуты поставщика. -
phones array of strings Нет Телефоны поставщика. Максимальная длина одной строки массива – 19 символов. 1171 Телефон поставщика
Описание подпараметра items
Название поля Тип поля Обязательные поля Ограничения Тег ФФД
items array of objects Да Атрибуты позиций. Ограничение по количеству от 1 до 100. -
name string Да Наименование товара. Максимальная длина строки – 128 символов. Если поле payment_object имеет значение "nonoperating_gain" для данного предмета расчета, то поле "name" должно принимать значение от 1 до 25. Если поле "payment_object" имеет значение "insurance_premium" для данного предмета расчета, то поле "items"->"name" должно принимать значение от 26 до 31. Описание значений поля “name” согласно ФФД приведено в Приложении 1. 1030 Наименование предмета расчета
price number Да Цена в рублях: целая часть не более 8 знаков; дробная часть не более 2 знаков. Максимальное значение цены – 42 949 672.95. При этом произведение цены и количество/веса (price*quantity) позиции должно быть не больше максимального значения цены позиции 1079 Цена за единицу предмета расчета с учетом скидок и наценок
quantity number Да Количество/вес: целая часть не более 5 знаков; дробная часть не более 3 знаков. Максимальное значение – 99 999.999 1023 Количество предмета расчета
sum number Да Сумма в рублях: целая часть не более 8 знаков; дробная часть не более 2 знаков. 1043 Стоимость предмета расчета с учетом скидок и наценок
measurement_unit string Нет Единица измерения товара, работы, услуги, платежа, 1197 Единица измерения предмета расчета
payment_method enum (string) Нет Если признак не передан, по умолчанию используется значение «full_prepayment». Признак способа расчёта 1214 Признак способа расчета
payment_object enum (string) Нет. Если признак не передан, по умолчанию используется значение «commodity» Признак предмета расчёта. Возможные значения указаны ниже. 1212 Признак предмета расчета
vat object Да Атрибуты налога на позицию. Необходимо передать либо сумму налога на позицию, либо сумму налога на чек. Если будут переданы и сумма налога на позицию и сумма налога на чек, сервис учтет только сумму налога на чек -
type enum (string) Да Устанавливает номер налога в ККТ 1199 Ставка НДС
sum number Нет Сумма налога позиции в рублях: целая часть не более 8 знаков; дробная часть не более 2 знаков 1200 Сумма НДС за предмет расчета
agent_info object Нет Атрибуты агента. Если объект не передан, по умолчанию флаг агента не устанавливается. -
type enum (string) Нет. Если передан объект «agent_info», в нём обязательно должно быть передано поле «type» Признак агента по предмету расчёта ( ограничен агентами, введенными в ККТ при фискализации) 1222 Признак агента по предмету расчета
paying_agent object Нет Атрибуты платежного агента -
operation string Нет Наименование операции. Максимальная длина строки – 24 символа. 1044 Операция платежного агента
phones array of strings Нет Телефоны платежного агента 1073 Телефон платежного агента
receive_payments_ operator object Нет Атрибуты оператора по приему платежей -
phones array of strings Нет Телефоны оператора по приему платежей 1074 Телефон оператора по приему платежей
money_transfer_ operator object Нет Атрибуты оператора перевода -
phones array of strings Нет Телефоны оператора перевода 1075 Телефон оператора перевода
name string Нет Наименование оператора перевода 1026 Наименование оператора перевода
address string Нет Адрес оператора перевода 1005 Адрес оператора перевода
inn string Нет ИНН оператора перевода 1016 ИНН оператора перевода
supplier_info object Нет. Поле обязательно, если передан «agent_info» Атрибуты поставщика -
phones array of strings Нет Телефоны поставщика 1171 Телефон поставщика
name string Нет Наименование поставщика 1225 Наименование поставщика
inn string Нет ИНН поставщика 1226 ИНН поставщика
user_data string Нет Дополнительный реквизит предмета расчета. Максимальная длина строки – 64 символа. 1191 Дополнительный реквизит предмета расчета

Возможные значения payment_method:

«full_prepayment» — предоплата 100%. Полная предварительная оплата до момента передачи предмета расчета.

«prepayment» — предоплата. Частичная предварительная оплата до момента передачи предмета расчета.

«advance» — аванс.

«full_payment» — полный расчет. Полная оплата, в том числе с учетом аванса (предварительной оплаты) в момент передачи предмета расчета.

«partial_payment» — частичный расчет и кредит. Частичная оплата предмета расчета в момент его передачи с последующей оплатой в кредит.

«credit» — передача в кредит. Передача предмета расчета без его оплаты в момент его передачи с последующей оплатой в кредит.

«credit_payment» — оплата кредита. Оплата предмета расчета после его передачи с оплатой в кредит (оплата кредита).

Возможные значения type:

«bank_paying_agent» — банковский платежный агент. Оказание услуг покупателю (клиенту) пользователем, являющимся банковским платежным агентом.

«bank_paying_subagent» — банковский платежный субагент. Оказание услуг покупателю (клиенту) пользователем, являющимся банковским платежным субагентом.

«paying_agent» — платежный агент. Оказание услуг покупателю (клиенту) пользователем, являющимся платежным агентом.

«paying_subagent» — платежный субагент. Оказание услуг покупателю (клиенту) пользователем, являющимся платежным субагентом.

«attorney» — поверенный. Осуществление расчета с покупателем (клиентом) пользователем, являющимся поверенным.

«commission_agent» — комиссионер. Осуществление расчета с покупателем (клиентом) пользователем, являющимся комиссионером.

«another» — другой тип агента. Осуществление расчета с покупателем (клиентом) пользователем, являющимся агентом и не являющимся банковским платежным агентом (субагентом), платежным агентом (субагентом), поверенным, комиссионером.

Возможные значения payment_object:

«commodity» — товар.

«excise» — подакцизный товар.

«job» — работа.

«service» — услуга.

«gambling_bet» — ставка азартной игры.

«gambling_prize» — выигрыш азартной игры.

«lottery» — лотерейный билет.

«lottery_prize» — выигрыш лотереи.

«intellectual_activity» — предоставление результатов интеллектуальной деятельности.

«payment» — платеж.

«agent_commission» — агентское вознаграждение.

«composite» — составной предмет расчета.

«another» — иной предмет расчета.

«property_right» — имущественное право. О передаче имущественных прав.

«non-operating_gain» — внереализационный доход.

«insurance_premium» — страховые взносы.

«sales_tax» — торговый сбор.

«resort_fee» — курортный сбор.

Описание подпараметра payments
Название поля Тип поля Обязательные поля Ограничения Тег ФФД
payments array of objects Да Оплаты. Ограничение по количеству от 1 до 10. -
type enum (number) Да Вид оплаты. Возможные значения: «1» – электронный; «2» – предварительная оплата (аванс); «3» – постоплата (кредит); «4» – иная форма оплаты (встречное предоставление); «5» – «9» – расширенные виды оплаты. Для каждого фискального типа оплаты можно указать расширенный вид оплаты. 1081 Сумма по чеку электронными;
sum number Да Сумма к оплате в рублях: целая часть не более 8 знаков; дробная часть не более 2 знаков. 1215 Сумма по чеку предоплатой (зачет аванса и (или) предыдущих платежей); 1216 Сумма по чеку постоплатой (кредит); 1217 Сумма по чеку встречным представлением.
Описание подпараметра vats
Название поля Тип поля Обязательные поля Ограничения Тег ФФД
vats array of objects Нет Атрибуты налогов на чек. Ограничение по количеству от 1 до 6. Необходимо передать либо сумму налога на позицию, либо сумму налога на чек. Если будет переданы и сумма налога на позицию и сумма налога на чек, сервис учтет только сумму налога на чек.
type enum (string) Нет Если передан объект «vats», в нём обязательно должно быть переданы поля «type» и «sum». Устанавливает номер налога в ККТ. 1105 Сумма расчета по чеку без НДС; 1104 Сумма расчета по чеку с НДС по ставке 0%; 1103 Сумма НДС чека по ставке 10%; 1102 Сумма НДС чека по ставке 18%; 1107 Сумма НДС чека по расч. ставке 10/110; 1106 Сумма НДС чека по расч. ставке 18/118.
sum number Сумма налога позиции в рублях: целая часть не более 8 знаков; дробная часть не более 2 знаков 1081 Сумма по чеку электронными;

Возможные значения type:

«none» – без НДС;

«vat0» – НДС по ставке 0%;

«vat10» – НДС чека по ставке 10%;

«vat18» – НДС чека по ставке 18%;

«vat110» – НДС чека по расчетной ставке 10/110;

«vat118» – НДС чека по расчетной ставке 18/118;

«vat20» – НДС чека по ставке 20%;

«vat120» – НДС чека по расчетной ставке 20/120.

С 01.02.2019 00:00 при отправке ставки vat18 или vat118 в чеках приход и расход сервис возвращает ошибку IncomingValidationException с текстом «Передана некорректная ставка налога. С 01.02.2019 ставки НДС 18 и 18/118 не могут использоваться в чеках sell (приход) и buy (расход)».

Описание подпараметра additional_user_props
Название поля Тип поля Обязательные поля Ограничения Тег ФФД
additional_user_ props object Нет Дополнительный реквизит пользователя 1084 Дополнительный реквизит пользователя
name string Нет Если передан объект « additional_user_props », в нём обязательно должно быть передано поле «name» Наименование дополнительного реквизита пользователя. Максимальная длина строки – 64 символа 1085 Наименование дополнительного реквизита пользователя
value string Нет Если передан объект « additional_user_props », в нём обязательно должно быть передано поле «name» Значение дополнительного реквизита пользователя. Максимальная длина строки – 256 символов. 1086 Значение дополнительного реквизита пользователя

С последней версией протокола АТОЛ можно ознакомиться на официальном сайте АТОЛ.