Перейти к основному содержимому

3. Backend API

3.1 Создание платежа​

Платёж инициируется методом create_payment_form для отображения платёжной формы Миксплат. В ответе метода возвращается payment_id, по которому в дальнейшем будет передаваться статус оплаты.

3.1.1 create_payment_form​

Создание платежа c использованием платёжной формы Миксплат. Используйте этот метод для переадресации плательщика на платёжную форму Миксплат, где плательщик вводит свои платёжные данные.

Направление запроса: ТСП → Миксплат
Тип запроса: POST-JSON (см. раздел 5.6)
URL запроса: https://api.mixplat.com/create_payment_form

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

api_versionint

Версия API. Текущая актуальная версия: 3.

Обязательный параметр

project_idint

ID проекта ТСП в Миксплат, для которого создаётся платёж. Значение параметра отображается в личном кабинете Миксплат в настройках проекта.

Обязательный параметр

signaturestring

Подпись запроса.

Обязательный параметр

Принцип формирования:
md5 (request_id+project_id+merchant_payment_id+API_KEY)

Символ "+" означает конкатенацию, request_id, project_id, merchant_payment_id — это строковые представления соответствующих параметров запроса, API_KEY — это секретный ключ сервиса для API запросов, узнать который можно в личном кабинете в настройках проекта. Если какой-либо из параметров не указан, то вместо его значения нужно использовать пустую строку.

Пример формирования:
md5(324223100057payment123c23a4398db8ef7b3ae1f4b07aeeb7c54f8e3c7c9)

Результат:
510c464ec7337858f6f662cbdeda9ac5

Пример реализации:

$api_key = '6yh9ik3f1734f29e3dc0118034277e67504rfjj9';
$project_id = 123456;
$request_id = 'test_request_id';
$merchant_payment_id = 'test_merchant_payment_id';
$signature = md5($request_id.$project_id.$merchant_payment_id.$api_key);
amountint

Сумма платежа в минорных единицах (копейках).
От 100 (1₽) до 100000000 (1млн₽) для payment_method = card
От 1000 (10₽) до 1500000 (15тыс₽) для payment_method = mobile
Для конкретных проектов могут действовать более строгие ограничения.

Обязательный параметр
descriptionstring|null

Описание платежа. Отображается на платёжной форме и в личном кабинете ТСП.

Необязательный параметр. По умолчанию "Оплата заказа". От 3 до 125 символов.
request_idstring|null

Уникальный идентификатор запроса, задаваемый ТСП, обеспечивающий идемпотентность вызовов (повторные запросы с тем же request_id не будут приводить к созданию нового платежа, а параметры ответа будут полностью повторять параметры ответа первоначального вызова с данным request_id).

Рекомендуется передавать этот параметр, чтобы защититься от дублирования платежей в результате сетевых проблем, задержек ответа и т. п.

В качестве request_id можно использовать идентификатор платежа в системе ТСП (если он уникален), или хеш от ключевых параметров запроса.

Проверка наличия другого запроса с данным request_id осуществляется за последние 30 дней.

Необязательный параметр. От 1 до 64 символов.
payment_methodstring|null

Платёжный метод (см. раздел 6.8), который будет использован для совершения оплаты.

Необязательный. По умолчанию не задан (все доступные методы).
merchant_payment_idstring|null

ID платежа в ТСП. Если передан, то это же значение параметра будет приходить в уведомлениях payment_status

Необязательный параметр. От 1 до 256 символов.
merchant_campaign_idstring|null

ID кампании в ТСП. Если передан, то это же значение параметра будет приходить в уведомлениях payment_status

Необязательный параметр. От 1 до 256 символов.
merchant_datastring|null

Произвольные данные ТСП, связанные с платежом. Если передан, то это же значение параметра будет приходить в уведомлениях payment_status

Необязательный параметр. От 1 до 256 символов.
merchant_fieldsjson-object|null

Массив дополнительных сведений о транзакции, которые ТСП может передать при создании платежа.

При уведомлении о статусе оплаты этот массив будет возвращен вместе с остальными параметрами в уведомлении payment_status

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

Пример:

{
    "Cookie": "HunjV5LHOvDIF",
    "client-category": "VIP",
    "Возраст": 33
}
Необязательный параметр.
user_emailstring|null

Email плательщика (если известен), для отправки email о совершённом платеже.

Необязательный параметр.
user_namestring|null

Имя плательщика (если известно), для отправки email о совершённом платеже.

Необязательный параметр.
user_phonestring|null

Номер телефона плательщика (если известен), только цифры, в международном формате, с кодом страны.

Необязательный параметр.
user_commentstring|null

Пользовательский комментарий к платежу (если есть).

Необязательный параметр.
user_account_idstring|null

Идентификатор пользователя в ТСП (если есть).

Необязательный параметр.
testint|null

Признак тестового платежа.

  • 1: Платёж тестовый
  • 0: Платёж реальный

Для тестовых платежей необходимо указывать специальные номера банковских карт/номера телефонов (раздел 5.5).

Необязательный параметр. По умолчанию 0 (Платёж реальный).
timeoutint|null

Время в секундах, отведенное на оплату.

После окончания времени на оплату платёж получит статус таймаут и оплата по данному payment_id будет невозможна. Для повторной оплаты необходимо создать новый платёж.

Необязательный параметр. По умолчанию 21600 (6 часов).
languagestring|null

Язык платёжной формы, сервисных сообщений (см. раздел 6.2).

Необязательный параметр. По умолчанию "RU" или "EN" в зависимости от IP пользователя.
currencystring|null

Валюта платежа (см. раздел 6.1).

Необязательный параметр. По умолчанию RUB.
itemsjson-object|null

Данные для чека. Описание структуры – в разделе 3.7

Пример:

[
    {
        "name": "Xiaomi MI",
        "quantity": 2,
        "sum": 3500000,
        "vat": "vat20"
    }
]
Необязательный параметр.
url_successstring|null

URL, на который будет перенаправлен Плательщик после успешной оплаты.

Необязательный параметр. Если не передан, используются настройки платёжной формы, заданные в ЛК.

url_failurestring|null

URL, на который будет перенаправлен Плательщик после неуспешной оплаты.

Необязательный параметр. Если не передан, используются настройки платёжной формы, заданные в ЛК.

recurrent_paymentint|null

Признак установочного платежа для последующих безакцептных списаний в режиме рекуррентов (раздел 3.5) или в режиме подписки (раздел 3.4)

  • 1: Платёж рекуррентный
  • 0: Платёж обычный.
Необязательный параметр. По умолчанию 0 (платёж обычный).
payment_schemestring|null

Схема проведения платежа по банковским картам (см. раздел 4.3). Возможные значения см. в разделе 6.11

Необязательный параметр. По умолчанию "single".
utm_mediumstring|null

UTM-метка, определяющая тип трафика. Если параметр передан, то это же значение параметра будет приходить в уведомлениях payment_status.

Необязательный параметр.
utm_sourcestring|null

UTM-метка, определяющая источник трафика. Если параметр передан, то это же значение параметра будет приходить в уведомлениях payment_status.

Необязательный параметр.
utm_campaignstring|null

UTM-метка, определяющая рекламную кампанию. Если параметр передан, то это же значение параметра будет приходить в уведомлениях payment_status.

Необязательный параметр.
utm_termstring|null

Произвольная пользовательская UTM-метка. Если параметр передан, то это же значение параметра будет приходить в уведомлениях payment_status.

Необязательный параметр.

Параметры ответа от Миксплат

resultstring

Результат выполнения запроса (см. раздел 6.3).

При успешном выполнении метода "result": "ok"

Значение result = ok является подтверждением получения платёжного запроса, и не относится к статусу самого платежа.

error_descriptionstring

Описание ошибки, возникшей при выполнении запроса.

Присутствует только в случае ошибки при выполнения метода (result != ok).

payment_idstring|null

ID созданного платежа в системе Миксплат.

Присутствует только в случае ошибки при выполнения метода (result = ok).

redirect_urlstring|null

URL, на который необходимо перенаправить Плательщика.

Присутствует только в случае ошибки при выполнения метода (result = ok).

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

Запрос от ТСП

POST https://api.mixplat.com/create_payment_form
{
    "api_version"          : 3,
    "project_id"           : 10001,
    "amount"               : 50000,
    "signature"            : "d9729feb74992cc3482b350163a1a010",
    "description"          : "Оплата по договору №571 от 19.07.2022",
    "payment_method"       : "card",
    "merchant_payment_id"  : "571",
    "merchant_data"        : "Договор №571",
    "merchant_fields"      :
    {
    "Cookie"                : "HunjV5LHOvDIF",
    "client-category"       : "VIP",
    "Возраст"               : 33
    },
    "user_email"           : "email@mail.ru",
    "user_name"            : "Дмитрий",
    "user_phone"           : "79037652277",
    "user_comment"         : "Договор №571 от 19.07.2022",
    "user_account_id"      : "124522751",
    "url_success"          : "https://site.ru/success.html",
    "url_failure"          : "https://site.ru/failure.html",
    "utm_source"           : "vkontakte"
}

Успешный ответ от Миксплат

{
    "result"       : "ok",
    "payment_id"   : "XXehOfcV7wM2z7YGFHs5vCYEeCrbD3mh",
    "redirect_url" : "https://pay.mixplat.com/p/XXehOfcV7wM2z7YGFHs5vCYEeCrbD3mh"
}

Ответ от Миксплат при возникновении ошибки

{
    "result"            : "error_project_not_found",
    "error_description" : "Project 1203 is not found"
}

3.2 Статусы платежей​

Статус платежа с уникальным идентификатором payment_id может быть передан на URL скрипта Обработчика ТСП, прописанного в настройках проекта в Личном кабинете (тип уведомления payment_status), либо запрошен со стороны ТСП в Миксплат методом get_payment_status. Получаемые данные о статусе платежа для определённого payment_id в обоих случаях будут идентичными.

3.2.1 payment_status​

Уведомление на URL Обработчика ТСП о статусе платежа.

Направление запроса: Миксплат → ТСП
Тип запроса: POST-JSON (см. раздел 5.7)
URL запроса: задаётся в настройках проекта в личном кабинете Миксплат

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

api_versionint

Версия API. Текущая актуальная версия: 3.

requeststring

Тип уведомления. В данном методе передаётся значение payment_status.

payment_idstring

ID платежа в системе Миксплат.

merchant_payment_idstring|null

ID платежа в ТСП.
Присутствует, если был передан при создании платежа.

payment_methodstring|null

Платёжный метод, который был использован для оплаты (см. раздел 6.8), или NULL, если он ещё не определён.

payment_method_groupstring|null

Группа платёжного метода, который был использован для оплаты (см. раздел 6.7), или NULL, если он ещё не определён.

statusstring

Статус платежа (см. раздел 6.5). Может быть промежуточным (pending) и финальным (success или failure). Параметр является основным способом определения успешности платежа.

status_extendedstring

Расширенный статус платежа (см. раздел 6.6). Состав расширенных статусов может быть изменён. Для определения успешности платежа используйте исключительно status.

amount_userint|null

Сумма, фактически оплаченная плательщиком, с учётом комиссии (если есть), в минорных единицах (копейках) или NULL, если платёж ещё не подтверждён.

amount_merchantint|null

Сумма к выплате ТСП, за вычетом комиссии (если есть), в минорных единицах (копейках) или NULL, если платёж ещё не подтверждён.

signaturestring

Принцип формирования:
md5 (payment_id+API_KEY)

Символ "+" означает конкатенацию, payment_id — это строковые представления соответствующих параметров запроса, API_KEY — это секретный ключ сервиса для API запросов, узнать который можно в личном кабинете в настройках проекта.

Пример формирования:
md5(707607041c23a4398db8ef7b3ae1f4b07aeeb7c54f8e3c7c9)

Результат:
047780e4f51dc6664d333536a6b4aab8

testint

Признак тестового платежа.

  • 1: Платёж тестовый
  • 0: Платёж реальный

Для тестовых платежей необходимо указывать специальные номера банковских карт/номера телефонов (см. раздел 5.5).

currencystring

Валюта платежа (см. раздел 6.1).

date_createdstring

Дата и время создания платежа (по UTC+03:00).
Формат: YYYY-MM-DD HH:MM:SS

date_processedstring|null

Дата и время обработки платежа (по UTC+03:00).
Формат: YYYY-MM-DD HH:MM:SS

project_idint

ID проекта ТСП в Миксплат, к которому относится платёж. Значение параметра отображается в личном кабинете Миксплат в настройках проекта.

recurrent_idstring|null

ID рекуррентной сессии. В дальнейшем вы можете использовать этот идентификатор и принимать повторные платежи без подтверждения со стороны плательщика (см. раздел 5.3).

Присутствует в случае, если режим рекуррентов был согласован для проекта, и если при создании платежа был передан параметр recurrent_payment = 1.

init_payment_idstring|null

Значение payment_id первого платежа по рекурренту/подписке.
Присутствует только для рекуррентных платежей.

merchant_init_payment_idstring|null

Значение merchant_payment_id из первого платежа по рекурренту/подписке.
Присутствует только для рекуррентных платежей.

merchant_campaign_idstring|null

ID кампании в ТСП.
Присутствует, если был передан при создании платежа.

merchant_datastring|null

Произвольные данные ТСП, связанные с платежом.
Присутствуют, если были переданы при создании платежа.

merchant_fieldsjson|null

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

Пример:

{
    "Cookie": "HunjV5LHOvDIF",
    "client-category": "VIP",
    "Возраст": 33
}
user_emailstring|null

Email плательщика.
Параметр присутствует, если был передан при создании платежа.

user_namestring|null

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

user_phonestring|null

Номер телефона плательщика.
Параметр присутствует, если был передан при создании платежа или если платёжный метод использует номер телефона.

user_commentstring|null

Пользовательский комментарий к платежу.
Параметр присутствует, если был передан при создании платежа

user_account_idstring|null

Идентификатор пользователя в ТСП.
Присутствует, если был передан при создании платежа

user_country_codestring|null

Двухсимвольный код страны плательщика по стандарту ISO 3166.
Пример: ru

user_countrystring|null

Страна плательщика. Могут быть несовпадения при подключенном VPN.
Пример: Россия

user_region_codestring|null

Код региона плательщика по стандарту ISO 3166.
Пример: RU-MOW

user_regionstring|null

Регион плательщика.
Пример: Москва

utm_mediumstring|null

UTM-метка, определяющая тип трафика.
Присутствует, если была передана при создании платежа.

utm_sourcestring|null

UTM-метка, определяющая источник трафика.
Присутствует, если была передана при создании платежа.

utm_campaignstring|null

UTM-метка, определяющая рекламную кампанию.
Присутствует, если была передана при создании платежа.

utm_termstring|null

Произвольная пользовательская UTM-метка.
Присутствует, если была передана при создании платежа.

cardjson|null

Дополнительная информация о платеже, специфичная для группы платёжных методов "card" (см. раздел 3.2.3.1).

Присутствует только для платежей с payment_method_group="card"
bankjson|null

Дополнительная информация о платеже, специфичная для группы платёжных методов "bank" (см. раздел 3.2.3.2).

Присутствует только для платежей с payment_method_group="bank"
mobilejson|null

Дополнительная информация о платеже, специфичная для группы платёжных методов "mobile" (см. раздел 3.2.3.3).

Присутствует только для платежей с payment_method_group="mobile"
walletjson|null

Дополнительная информация о платеже, специфичная для группы платёжных методов "wallet" (см. раздел 3.2.3.4).

Присутствует только для платежей с payment_method_group="wallet"

Параметры ответа от ТСП

resultstring

Результат выполнения запроса (см. раздел 6.4).
При успешном выполнении метода "result": "ok"

result = ok является подтверждением получения нотификации, и не относится к передаваемым данным
error_descriptionstring

Описание ошибки, возникшей при обработке уведомления.

Необязательный, может присутствовать в случае возникновения ошибки при выполнении запроса
messagestring

Текст сообщения, которое будет отправлено Плательщику (в sms или email в зависимости от настроек сервиса в ЛК).

Необязательный

Пример уведомления от Миксплат

POST <URL обработчика ТСП>

{
    "api_version"          : 3,
    "request"              : "payment_status",
    "payment_id"           : "XXehOfcV7wM2z7YGFHs5vCYEeCrbD3mh",
    "merchant_payment_id"  : "571",
    "payment_method"       : "yandex_pay",
    "payment_method_group" : "card",
    "status"               : "success",
    "status_extended"      : "success_success",
    "amount"               : 50000,
    "amount_user"          : 50000,
    "amount_merchant"      : 48750,
    "signature"            : "d9729feb74992cc3482b350163a1a010",
    "test"                 : 0,
    "currency"             : "RUB",
    "date_created"         : "2019-03-03 11:45:23",
    "date_processed"       : "2019-03-03 11:47:12",
    "project_id"           : 1203, 
    "merchant_data"        : "Договор №571",
    "merchant_fields"      :
    {
      "Cookie"                : "HunjV5LHOvDIF",
      "client-category"       : "VIP",
      "Возраст"               : 33
    },
    "user_email"           : "email@mail.ru",
    "user_name"            : "Дмитрий",
    "user_phone"           : "79031234567",
    "user_comment"         : "Договор №571 от 19.07.2022",
    "user_account_id"      : "124522751",
    "user_country_code"    : "ru",
    "user_country"         : "Россия",
    "user_region_code"     : "RU-KLU",
    "user_region"          : "Калужская обл.",
    "utm_source"           : "vkontakte",
    "card"                 :
    {
      "pan"                   : "408397******8222",
      "payment_system"        : "card_visa",        
      "issuer_country_code"   : "ru",
      "issuer_country"        : "Россия",
      "issuer"                : "ALFA-BANK"
    }
}

Успешный ответ от ТСП

{
    "result" : "ok"
}

Ответ от ТСП в случае возникновения ошибки, которая требует повтора нотификации

{
    "result"            : "error",
    "error_description" : "Internal error"
}

Ответ от ТСП в случае ошибки, которая не требует повтора нотификации

{
    "result"            : "ok",
    "error_description" : "Payment information is not found"
}
Примечание 1: result относится к успешности факта приёма нотификации, а не к передаваемым данным.
Примечание 2: payment_status также отправляется при оплате банковской картой по двухстадийной (double) схеме, когда платёж успешно авторизован (status = pending, status_extended = pending_authorized).

3.2.2 get_payment_status​

Получение информации о статусе оплаты по идентификатору платежа payment_id (или merchant_payment_id).

Направление запроса: ТСП → Миксплат
Тип запроса: POST-JSON (см. раздел 5.6)
URL запроса: https://api.mixplat.com/get_payment_status

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

api_versionint

Версия API. Текущая актуальная версия: 3.

payment_idstring

ID платежа в системе Миксплат.

Не указывается, если присутствует merchant_payment_id
merchant_payment_idstring

ID платежа в системе ТСП.

Не указывается, если присутствует payment_id
project_idstring

ID проекта ТСП в Миксплат, к которому относится платёж. Значение параметра отображается в личном кабинете Миксплат в настройках проекта.

Указывается, только если присутствует merchant_payment_id
signaturestring

Подпись запроса.
Принцип формирования:
md5 (payment_id+merchant_payment_id+API_KEY)

Символ "+" означает конкатенацию, payment_id, merchant_payment_id — это строковые представления соответствующих параметров запроса, API_KEY — это секретный ключ сервиса для API запросов, узнать который можно в личном кабинете в настройках проекта. Если какой-либо из параметров не указан, то вместо его значения нужно использовать пустую строку.

Пример формирования:
md5(707607041571c23a4398db8ef7b3ae1f4b07aeeb7c54f8e3c7c9)

Результат:
7e99a4988888d5c14b9faf2e14a95d43

Параметры ответа от Миксплат

Совпадают с нотификацией payment_status, за исключением параметров result и error_description, используемых только в get_payment_status:

resultstring

Результат выполнения запроса (см. раздел 6.3).
При успешном выполнении метода "result": "ok"

error_descriptionstring

Описание ошибки, возникшей при выполнении запроса.

Присутствует только в случае ошибки при выполнения метода (result != ok)
payment_idstring

ID платежа в системе Миксплат.

merchant_payment_idstring|null

ID платежа в ТСП.
Присутствует, если был передан при создании платежа.

payment_methodstring|null

Платёжный метод, который был использован для оплаты (см. раздел 6.8), или NULL, если он ещё не определён.

payment_method_groupstring|null

Группа платёжного метода, который был использован для оплаты (см. раздел 6.7), или NULL, если он ещё не определён.

statusstring

Статус платежа (см. раздел 6.5). Может быть промежуточным (pending) и финальным (success или failure). Параметр является основным способом определения успешности платежа.

status_extendedstring

Расширенный статус платежа (см. раздел 6.6). Состав расширенных статусов может быть изменён. Для определения успешности платежа используйте исключительно status.

amount_userint|null

Сумма, фактически оплаченная плательщиком, с учётом комиссии (если есть), в минорных единицах (копейках) или NULL, если платёж ещё не подтверждён.

amount_merchantint|null

Сумма к выплате ТСП, за вычетом комиссии (если есть), в минорных единицах (копейках) или NULL, если платёж ещё не подтверждён.

signaturestring

Принцип формирования:
md5 (payment_id+API_KEY)

Символ "+" означает конкатенацию, payment_id — это строковые представления соответствующих параметров запроса, API_KEY — это секретный ключ сервиса для API запросов, узнать который можно в личном кабинете в настройках проекта.

Пример формирования:
md5(707607041c23a4398db8ef7b3ae1f4b07aeeb7c54f8e3c7c9)

Результат:
047780e4f51dc6664d333536a6b4aab8

testint

Признак тестового платежа.

  • 1: Платёж тестовый
  • 0: Платёж реальный

Для тестовых платежей необходимо указывать специальные номера банковских карт/номера телефонов (см. раздел 5.5).

currencystring

Валюта платежа (см. раздел 6.1).

date_createdstring

Дата и время создания платежа (по UTC+03:00).
Формат: YYYY-MM-DD HH:MM:SS

date_processedstring|null

Дата и время обработки платежа (по UTC+03:00).
Формат: YYYY-MM-DD HH:MM:SS

project_idint

ID проекта ТСП в Миксплат, к которому относится платёж. Значение параметра отображается в личном кабинете Миксплат в настройках проекта.

recurrent_idstring|null

ID рекуррентной сессии. В дальнейшем вы можете использовать этот идентификатор и принимать повторные платежи без подтверждения со стороны плательщика (см. раздел 5.3).

Присутствует в случае, если режим рекуррентов был согласован для проекта, и если при создании платежа был передан параметр recurrent_payment = 1.

init_payment_idstring|null

Значение payment_id первого платежа по рекурренту/подписке.
Присутствует только для рекуррентных платежей.

merchant_init_payment_idstring|null

Значение merchant_payment_id из первого платежа по рекурренту/подписке.
Присутствует только для рекуррентных платежей.

merchant_campaign_idstring|null

ID кампании в ТСП.
Присутствует, если был передан при создании платежа.

merchant_datastring|null

Произвольные данные ТСП, связанные с платежом.
Присутствуют, если были переданы при создании платежа.

merchant_fieldsjson|null

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

Пример:

{
    "Cookie": "HunjV5LHOvDIF",
    "client-category": "VIP",
    "Возраст": 33
}
user_emailstring|null

Email плательщика.
Параметр присутствует, если был передан при создании платежа.

user_namestring|null

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

user_phonestring|null

Номер телефона плательщика.
Параметр присутствует, если был передан при создании платежа или если платёжный метод использует номер телефона.

user_commentstring|null

Пользовательский комментарий к платежу.
Параметр присутствует, если был передан при создании платежа

user_account_idstring|null

Идентификатор пользователя в ТСП.
Присутствует, если был передан при создании платежа

user_country_codestring|null

Двухсимвольный код страны плательщика по стандарту ISO 3166.
Пример: ru

user_countrystring|null

Страна плательщика. Могут быть несовпадения при подключенном VPN.
Пример: Россия

user_region_codestring|null

Код региона плательщика по стандарту ISO 3166.
Пример: RU-MOW

user_regionstring|null

Регион плательщика.
Пример: Москва

utm_mediumstring|null

UTM-метка, определяющая тип трафика.
Присутствует, если была передана при создании платежа.

utm_sourcestring|null

UTM-метка, определяющая источник трафика.
Присутствует, если была передана при создании платежа.

utm_campaignstring|null

UTM-метка, определяющая рекламную кампанию.
Присутствует, если была передана при создании платежа.

utm_termstring|null

Произвольная пользовательская UTM-метка.
Присутствует, если была передана при создании платежа.

cardjson|null

Дополнительная информация о платеже, специфичная для группы платёжных методов "card" (см. раздел 3.2.3.1).

Присутствует только для платежей с payment_method_group="card"
bankjson|null

Дополнительная информация о платеже, специфичная для группы платёжных методов "bank" (см. раздел 3.2.3.2).

Присутствует только для платежей с payment_method_group="bank"
mobilejson|null

Дополнительная информация о платеже, специфичная для группы платёжных методов "mobile" (см. раздел 3.2.3.3).

Присутствует только для платежей с payment_method_group="mobile"
walletjson|null

Дополнительная информация о платеже, специфичная для группы платёжных методов "wallet" (см. раздел 3.2.3.4).

Присутствует только для платежей с payment_method_group="wallet"

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

Запрос от ТСП

POST https://api.mixplat.com/get_payment_status
{
    "api_version" : 3,
    "payment_id"  : "XXehOfcV7wM2z7YGFHs5vCYEeCrbD3mh",
    "signature"   : "d9729feb74992cc3482b350163a1a010"
}

Успешный ответ от Миксплат

{
    "result"               : "ok",
    "payment_id"           : "XXehOfcV7wM2z7YGFHs5vCYEeCrbD4mh",
    "merchant_payment_id"  : "572",
    "payment_method"       : "bank",
    "payment_method_group" : "sbp",
    "status"               : "success",
    "status_extended"      : "success_success",
    "amount"               : 50000,
    "amount_user"          : 50000,
    "amount_merchant"      : 48750,
    "test"                 : 0,
    "currency"             : "RUB",
    "date_created"         : "2019-03-03 11:45:23",
    "date_processed"       : "2019-03-03 11:47:12",
    "project_id"           : 1203, 
    "merchcant_data"        : "Договор №571",
    "merchant_fields"      :
    {
      "Cookie"                : "HunjV5LHOvDIF",
      "client-category"       : "VIP",
      "Возраст"               : 33
    },
    "user_email"           : "email@mail.ru",
    "user_name"            : "Дмитрий",
    "user_phone"           : "79031234567",
    "user_comment"         : "Договор №571 от 19.07.2022",
    "user_account_id"      : "124522751",
    "user_country_code"    : "ru",
    "user_country"         : "Россия",
    "user_region_code"     : "RU-KLU",
    "user_region"          : "Калужская обл.",
    "utm_source"           : "vkontakte",
    "bank"                 :
    {
      "pan"                   : "408178**********2202",
      "issuer_country_code"   : "ru",
      "issuer_country"        : "Россия",
      "issuer"                : "ALFA-BANK"
    }
}

Ответ от Миксплат при возникновении ошибки

{
    "result"            : "error_payment_not_found",
    "error_description" : "Payment ID XXehOfcV7wM2z7YGFHs5vCYEeCrbD3mh is not found"
}

3.2.3 Опциональные JSON-поля​

В структуре данных о статусе платежа может передаваться JSON-объект с расширенной информацией о платеже, специфичной для конкретного платёжного метода. Название этих JSON-объектов совпадает с наименованием платёжного метода в параметре payment_method_group (см. раздел 6.7).

3.2.3.1 структура поля card​

payment_systemstring

Платёжная система карты плательщика (см. раздел 6.9)
Пример: card_mir

panstring

Номер карты плательщика. Показаны только первые 6 и последние 4 цифры, остальные заменены на символ *.
Пример: 580231******1234

issuer_country_codestring

Двухсимвольный код страны плательщика по стандарту ISO 3166, определенный по номеру карты.
Пример: ru

issuer_countrystring

Cтрана плательщика, определённая по номеру карты.
Пример: Россия

issuerstring|null

Банк-эмитент карты плательщика.

Задаётся в случае, если удалось распознать банк плательщика.

3.2.3.2 структура поля bank​

accountstring

Номер расчётного счёта плательщика.
Пример: 40817810807014012202

В зависимости от источника номер может быть частично закрыт символами *.
issuer_country_codestring

Двухсимвольный код страны банка по стандарту ISO 3166.
Пример: ru

issuer_countrystring

Cтрана банка.
Пример: Россия

issuerstring|null

Банк-эмитент карты плательщика.

Задаётся в случае, если удалось распознать банк плательщика.

3.2.3.3 структура поля mobile​

payment_systemstring|null

Символьное наименование оператора сотовой связи телефонного номера абонента. (см. раздел 6.9)
Пример: mobile_ru_mts

mccmncint

Код оператора сотовой связи по стандарту MCCMNC.
Пример: 25001

billing_typestring

Тип биллинга платежа (см. раздел 6.10)
Пример: mc

senderstring|null

Номер, на который было отправлено SMS-сообщение, инициировавшее платёж.

Задаётся только в случае, если платёж был инициирован отправкой SMS-сообщения на короткий номер.
text_rawstring|null

Полный текст сообщения.

Задаётся только в случае, если платёж был инициирован отправкой SMS-сообщения на короткий номер.
prefixstring|null

Ключевое слово, распознанное в тексте сообщения.

Задаётся только в случае, если платёж был инициирован отправкой SMS-сообщения на короткий номер.
text_after_prefixstring|null

Текст после ключевого слова.

Задаётся только в случае, если платёж был инициирован отправкой SMS-сообщения на короткий номер.

3.2.3.4 структура поля wallet​

accountstring

Идентификатор плательщика в платёжной системе.

issuer_country_codestring

Двухсимвольный код страны банка по стандарту ISO 3166.
Пример: ru

issuer_countrystring

Cтрана банка.
Пример: Россия

issuerstring|null

Наименование банка плательщика.

Задаётся в случае, если удалось распознать банк плательщика.

3.3 Возврат платежа​

3.3.1 refund_payment​

Возврат средств по ранее выполненному платежу. Возврат может быть произведён как на полную сумму произведённого пользователем платежа, так и на частичную. Статус платежа (определяется по payment_id) после процедуры возврата не изменяется, результат проведения возврата будет определён по refund_id. Для одного и того же платежа может быть произведено несколько возвратов на разные суммы, они будут отражены в реестрах как отдельные операции с отдельными refund_id.

Направление запроса: ТСП → Миксплат
Тип запроса: POST-JSON (см. раздел 5.6)
URL запроса: https://api.mixplat.com/refund_payment

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

api_versionint

Версия API. Текущая актуальная версия: 3.

payment_idstring

ID платежа, по которому будет осуществлён возврат.

amountint

Сумма возврата (в минорных единицах, копейках).

Необязательный, по умолчанию совпадает с суммой платежа с идентификатором payment_id
currencystring|null

Валюта платежа (см. раздел 6.1).

Необязательный, по умолчанию совпадает с валютой платежа с идентификатором payment_id
merchant_refund_idstring|null

ID возврата в ТСП.

Необязательный параметр. От 1 до 256 символов.
merchant_datastring|null

Произвольные данные ТСП, связанные с возвратом.

Необязательный параметр. От 1 до 256 символов.
signaturestring

Подпись запроса. Принцип формирования:
md5 (payment_id+API_KEY)

Символ "+" означает конкатенацию, payment_id — это строковые представления соответствующих параметров запроса, API_KEY — это секретный ключ сервиса для API запросов, узнать который можно в личном кабинете в настройках проекта. Если какой-либо из параметров не указан, то вместо его значения нужно использовать пустую строку.

Пример формирования:
md5(707607041c23a4398db8ef7b3ae1f4b07aeeb7c54f8e3c7c9)

Результат: 047780e4f51dc6664d333536a6b4aab8

Параметры ответа от Миксплат

resultstring

Результат выполнения запроса (см. раздел 6.3).

При успешном выполнении метода "result": "ok"

error_descriptionstring

Описание ошибки, возникшей при выполнении запроса.

Присутствует только в случае ошибки при выполнения метода (result != ok).

refund_idstring|null

ID созданного возврата.

Присутствует только в случае ошибки при выполнения метода (result = ok).

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

Запрос от ТСП

POST https://api.mixplat.com/refund_payment
{
    "api_version" : 3,
    "payment_id"  : "XXehOfcV7wM2z7YGFHs5vCYEeCrbD3mh",
    "signature"   : "d9729feb74992cc3482b350163a1a010"
}

Успешный ответ от Миксплат

{
    "result"    : "ok",
    "refund_id" : 19872
}

Ответ от Миксплат при возникновении ошибки

{
    "result"            : "error_payment_not_found",
    "error_description" : "Payment is not found"
}

3.3.2 refund_status​

Уведомление на URL Обработчика ТСП о статусе возврата. Уведомление о возврате платежа будет отправлено после получения подтверждения от банка-эмитента. Обратите внимание, что получение данного уведомления может занять несколько дней.

Направление запроса: Миксплат → ТСП
Тип запроса: POST-JSON (см. раздел 5.7)
URL запроса: задаётся в настройках проекта в личном кабинете Миксплат

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

api_versionint

Версия API. Текущая актуальная версия: 3.

requeststring

Тип уведомления. В данном методе передаётся значение refund_status

refund_idint

ID возврата в Миксплат.

payment_idstring

ID платежа в Миксплат, для которого был создан возврат.

merchant_payment_idstring|null

ID платежа в системе ТСП.

amountint

Сумма платежа в минорных единицах (копейках).

Сумма 123₽ будет соответствовать amount = 12300

merchant_refund_idstring|null

ID возврата в ТСП, или NULL, если он не был указан при создании платежа.

merchant_datastring|null

Произвольные данные ТСП, связанные с возвратом, или NULL, если они не были указаны при создании платежа.

statusstring

Статус возврата (см. раздел 6.12).

date_createdstring

Дата и время создания возврата (по UTC+03:00).
Формат: YYYY-MM-DD HH:MM:SS

date_completedstring|null

Дата и время осуществления возврата (по UTC+03:00), или NULL, если возврат ещё обрабатывается.Формат: YYYY-MM-DD HH:MM:SS

signaturestring

Принцип формирования:
md5 (refund_id+API_KEY)

Символ "+" означает конкатенацию, refund_id — это строковые представления соответствующих параметров запроса, API_KEY — это секретный ключ сервиса для API запросов, узнать который можно в личном кабинете в настройках проекта.

Пример формирования:
md5(342422424c23a4398db8ef7b3ae1f4b07aeeb7c54f8e3c7c9)

Результат:
e7a14db09973bbd5ada8752a39a0cf1e

Параметры ответа от ТСП

resultstring

Результат выполнения запроса (см. раздел 6.4).
При успешном выполнении метода "result": "ok"

error_descriptionstring

Описание ошибки, возникшей при обработке уведомления.

Необязательный, может присутствовать в случае возникновения ошибки при выполнении запроса

Пример уведомления и ответа

Уведомление от Миксплат

POST <URL обработчика ТСП>
{
    "api_version"        : 3,
    "request"            : "refund_status",
    "refund_id"          : 19872,
    "payment_id"         : "XXehOfcV7wM2z7YGFHs5vCYEeCrbD3mh",
    "merchant_payment_id" : "878712525",
    "amount"             : 10000,
    "status"             : "success",
    "date_created"       : "2019-04-02 12:43:00",
    "date_completed"     : "2019-04-02 13:15:00",
    "signature"          : "d9729feb74992cc3482b350163a1a010"
}

Успешный ответ от ТСП

{
    "result" : "ok"
}

Ответ от ТСП в случае возникновения ошибки

{
    "result"            : "error_refund_not_found",
    "error_description" : "Refund is not found"
}

3.3.3 get_refund_status​

Получение информации о статусе возврата по refund_id. Статус финализируется только после получения подтверждения от банка-эмитента. Обратите внимание, что получение финального статуса может занять несколько дней.

Направление запроса: ТСП → Миксплат
Тип запроса: POST-JSON (см. раздел 5.6)
URL запроса: https://api.mixplat.com/get_refund_status

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

api_versionint

Версия API. Текущая актуальная версия: 3.

refund_idint

ID возврата в Миксплат.

signaturestring

Принцип формирования:
md5 (refund_id+API_KEY)

Символ "+" означает конкатенацию, refund_id — это строковые представления соответствующих параметров запроса, API_KEY — это секретный ключ сервиса для API запросов, узнать который можно в личном кабинете в настройках проекта.

Пример формирования:
md5(342422424c23a4398db8ef7b3ae1f4b07aeeb7c54f8e3c7c9)

Результат:
e7a14db09973bbd5ada8752a39a0cf1e

Параметры ответа от Миксплат

resultstring

Результат выполнения запроса (см. раздел 6.4).
При успешном выполнении метода "result": "ok"

error_descriptionstring

Описание ошибки, возникшей при обработке уведомления.

Необязательный, может присутствовать в случае возникновения ошибки при выполнении запроса
payment_idstring

ID платежа в Миксплат, для которого был создан возврат.

merchant_payment_idstring|null

ID платежа в системе ТСП.

amountint

Сумма платежа в минорных единицах (копейках).

Сумма 123₽ будет соответствовать amount = 12300

merchant_refund_idstring|null

ID возврата в ТСП, или NULL, если он не был указан при создании платежа.

merchant_datastring|null

Произвольные данные ТСП, связанные с возвратом, или NULL, если они не были указаны при создании платежа.

statusstring

Статус возврата (см. раздел 6.12).

date_createdstring

Дата и время создания возврата (по UTC+03:00).
Формат: YYYY-MM-DD HH:MM:SS

date_completedstring|null

Дата и время осуществления возврата (по UTC+03:00), или NULL, если возврат ещё обрабатывается.Формат: YYYY-MM-DD HH:MM:SS

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

Запрос от ТСП

POST https://api.mixplat.com/get_refund_status
{
    "api_version" : 3,
    "refund_id"   : 19872,
    "signature"   : "d9729feb74992cc3482b350163a1a010"
}

Запрос от ТСП

POST https://api.mixplat.com/get_refund_status
{
    "api_version" : 3,
    "refund_id"   : 19872,
    "signature"   : "d9729feb74992cc3482b350163a1a010"
}

Ответ от Миксплат

POST <URL обработчика ТСП>
{
    "result"              : "ok",
    "payment_id"          : "XXehOfcV7wM2z7YGFHs5vCYEeCrbD3mh",
    "merchant_payment_id" : "878712525",
    "amount"              : 10000,
    "status"              : "success",
    "date_created"        : "2019-04-02 12:43:00",
    "date_completed"      : "2019-04-02 13:15:00",
    "signature"           : "d9729feb74992cc3482b350163a1a010"
}

Ответ от Миксплат при возникновении ошибки

{
    "result"            : "error_refund_not_found",
    "error_description" : "Refund is not found"
}

3.4 Подписки​

Подписка — повторные безакцептные списания средств с карты плательщика с заранее определённой периодичностью без дополнительных действий со стороны ТСП.

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

3.4.1 Профиль подписки​

Профиль подписки — это шаблон, на основе которого создаются подписки для конкретных пользователей.

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

В профиле подписки настраиваются:

  • Название профиля (для отображения в Личном Кабинете)
  • Валюта платежа
  • Сумма платежа
  • Доступные платёжные методы
  • Текст уведомлений при событиях (подтверждение, активация и т. п.)
  • Периодичность списания:
    • Ежедневная
    • Еженедельная
    • Ежемесячная
  • Количество бесплатных дней (период между подтверждением и активацией подписки)
  • Количество и период попыток списания

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

Для создания подписки нужно инициировать установочный платёж с помощью метода create_payment_form, передав дополнительный параметр recurrent_payment = 1. Подписка создаётся только в случае, если установочный платёж успешен. После проведения установочного платежа вы получите идентификатор подписки recurrent_id в уведомлении payment_status.

3.4.3 Платежи по подписке​

В соответствии с заданной периодичностью в профиле подписки, Миксплат инициирует очередные платежи с заданной периодичностью. При очередном списании ТСП получит уведомление payment_status c идентификатором подписки recurrent_id. Если очередной платёж был неуспешен, то в зависимости от настроек подписочного профиля попытки списаний остановятся или будут выполнены дополнительные попытки списания. Дата и время очередного платежа по подписке отсчитывается от даты установочного платежа.

3.4.4 stop_subscription​

Направление запроса: ТСП → Миксплат
Тип запроса: POST-JSON (см. раздел 5.6)
URL запроса: https://api.mixplat.com/stop_subscription

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

api_versionint

Версия API. Текущая актуальная версия: 3.

recurrent_idint

ID подписки

signaturestring

Принцип формирования:
md5 (recurrent_id+API_KEY)

Символ "+" означает конкатенацию, recurrent_id — это строковые представления соответствующих параметров запроса, API_KEY — это секретный ключ сервиса для API запросов, узнать который можно в личном кабинете в настройках проекта.

Пример формирования:
md5(1449272c23a4398db8ef7b3ae1f4b07aeeb7c54f8e3c7c9)

Результат:
f05b57071a180a05bb161231896bee43

Параметры ответа от Миксплат

resultstring

Результат выполнения запроса (см. раздел 6.3).

При успешном выполнении метода "result": "ok"

error_descriptionstring

Описание ошибки, возникшей при выполнении запроса.

Присутствует только в случае ошибки при выполнения метода (result != ok).

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

Запрос от ТСП

POST https://api.mixplat.com/stop_subscription
{
    "api_version" : 3,
    "recurrent_id"  : "434241",
    "signature"   : "d9729feb74992cc3482b350163a1a010"
}

Успешный ответ от Миксплат

{
    "result" : "ok",
}

Ответ от Миксплат при возникновении ошибки

{
    "result"  : "error_subscription_not_found",
    "error_description" : "Subscription is not found"
}

3.4.5 get_subscription_status​

Направление запроса: ТСП → Миксплат
Тип запроса: POST-JSON (см. раздел 5.6)
URL запроса: https://api.mixplat.com/get_subscription_status

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

api_versionint

Версия API. Текущая актуальная версия: 3.

recurrent_idint

ID подписки

signaturestring

Принцип формирования:
md5 (recurrent_id+API_KEY)

Символ "+" означает конкатенацию, recurrent_id — это строковые представления соответствующих параметров запроса, API_KEY — это секретный ключ сервиса для API запросов, узнать который можно в личном кабинете в настройках проекта.

Пример формирования:
md5(1449272c23a4398db8ef7b3ae1f4b07aeeb7c54f8e3c7c9)

Результат:
f05b57071a180a05bb161231896bee43

Параметры ответа от Миксплат

resultstring

Результат выполнения запроса (см. раздел 6.3).

При успешном выполнении метода "result": "ok"

Значение result = ok является подтверждением получения платёжного запроса, и не относится к статусу самого платежа.

error_descriptionstring

Описание ошибки, возникшей при выполнении запроса.

Присутствует только в случае ошибки при выполнения метода (result != ok).

subscription_statusstring

Статус подписки: confirmation (подтверждается), active (активна), suspended (приостановлена) и stopped (остановлена).

profile_idstring

ID профиля подписки в системе Миксплат.

periodstring

Период списаний по подписке: "1month", "1week", "1day" и т.д.

payment_methodstring|null

Платёжный метод, который был использован для оплаты (см. раздел 6.8), или NULL, если он ещё не определён.

payment_method_groupstring|null

Группа платёжного метода, который был использован для оплаты (см. раздел 6.7), или NULL, если он ещё не определён.

amountint

Сумма платежа в минорных единицах (копейках).

Сумма 123₽ будет соответствовать amount = 12300

amount_userint|null

Сумма, фактически оплаченная плательщиком, с учётом комиссии (если есть), в минорных единицах (копейках) или NULL, если платёж ещё не подтверждён.

amount_merchantint|null

Сумма к выплате ТСП, за вычетом комиссии (если есть), в минорных единицах (копейках) или NULL, если платёж ещё не подтверждён.

testint|null

Признак тестового платежа.

  • 1: Платёж тестовый
  • 0: Платёж реальный

Для тестовых платежей необходимо указывать специальные номера банковских карт/номера телефонов (раздел 5.5).

currencystring|null

Валюта платежа (см. раздел 6.1).

Необязательный параметр. По умолчанию RUB.
date_createdstring

Дата и время создания подписки (по UTC+03:00).
Формат: YYYY-MM-DD HH:MM:SS

date_processedstring|null

Дата и время обработки последнего платежа по подписке (по UTC+03:00).
Формат: YYYY-MM-DD HH:MM:SS

date_stoppedstring|null

Дата и время остановки подписки (по UTC+03:00) или NULL, если она активна.
Формат: YYYY-MM-DD HH:MM:SS

project_idint

ID проекта ТСП в Миксплат, к которому относится платёж. Значение параметра отображается в личном кабинете Миксплат в настройках проекта.

init_payment_idstring|null

Значение payment_id первого платежа по подписке.

merchant_init_payment_idstring|null

Значение merchant_payment_id из первого платежа по подписке.

merchant_campaign_idstring|null

ID кампании в ТСП.
Присутствует, если был передан при создании подписки.

merchant_datastring|null

Произвольные данные ТСП, связанные с платежом.
Присутствуют, если были переданы при создании подписки.

merchant_fieldsjson|null

Массив дополнительных сведений о транзакции.
Присутствует, если был передан при создании подписки.

user_emailstring|null

Email плательщика.
Параметр присутствует, если был передан при создании подписки.

user_namestring|null

Имя плательщика.
Параметр присутствует, если было передано при создании подписки.

user_phonestring|null

Номер телефона плательщика.
Параметр присутствует, если был передан при создании подписки или если платёжный метод использует номер телефона.

user_commentstring|null

Пользовательский комментарий к платежу.
Параметр присутствует, если был передан при создании подписки

user_account_idstring|null

Идентификатор пользователя в ТСП.
Присутствует, если был передан при создании подписки

user_country_codestring|null

Двухсимвольный код страны плательщика по стандарту ISO 3166.
Пример: ru

user_countrystring|null

Страна плательщика. Могут быть несовпадения при подключенном VPN.
Пример: Россия

user_region_codestring|null

Код региона плательщика по стандарту ISO 3166.
Пример: RU-MOW

user_regionstring|null

Регион плательщика.
Пример: Москва

utm_mediumstring|null

UTM-метка, определяющая тип трафика.
Присутствует, если была передана при создании подписки.

utm_sourcestring|null

UTM-метка, определяющая источник трафика.
Присутствует, если была передана при создании подписки.

utm_campaignstring|null

UTM-метка, определяющая рекламную кампанию.
Присутствует, если была передана при создании подписки.

utm_termstring|null

Произвольная пользовательская UTM-метка.
Присутствует, если была передана при создании подписки.

cardjson|null

Дополнительная информация, специфичная для группы платёжных методов "card" (см. раздел 3.2.3.1).

Присутствует только для платежей с payment_method_group="card"
bankjson|null

Дополнительная информация, специфичная для группы платёжных методов "bank" (см. раздел 3.2.3.2).

Присутствует только для платежей с payment_method_group="bank"
mobilejson|null

Дополнительная информация, специфичная для группы платёжных методов "mobile" (см. раздел 3.2.3.3).

Присутствует только для платежей с payment_method_group="mobile"
walletjson|null

Дополнительная информация о платеже, специфичная для группы платёжных методов "wallet" (см. раздел 3.2.3.4).

Присутствует только для платежей с payment_method_group="wallet"

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

Запрос от ТСП

POST https://api.mixplat.com/get_subscription_status
{
    "api_version" : 3,
    "recurrent_id"  : "434241",
    "signature"   : "d9729feb74992cc3482b350163a1a010"
}

Успешный ответ от Миксплат

{
    "result"               : "ok",
    "subscription_status"  : "active",
    "profile_id"           : "10",
    "period"               : "1month",
    "payment_method"       : "bank",
    "payment_method_group" : "sbp",
    "amount"               : 50000,
    "amount_user"          : 50000,
    "amount_merchant"      : 48750,
    "test"                 : 0,
    "currency"             : "RUB",
    "date_created"         : "2019-03-03 11:45:23",
    "date_processed"       : "2019-03-03 11:47:12",
    "project_id"           : 1203, 
    "merchcant_data"        : "Договор №571",
    "merchant_fields"      :
    {
      "Cookie"                : "HunjV5LHOvDIF",
      "client-category"       : "VIP",
      "Возраст"               : 33
    },
    "user_email"           : "email@mail.ru",
    "user_name"            : "Дмитрий",
    "user_phone"           : "79031234567",
    "user_comment"         : "Договор №571 от 19.07.2022",
    "user_account_id"      : "124522751",
    "user_country_code"    : "ru",
    "user_country"         : "Россия",
    "user_region_code"     : "RU-KLU",
    "user_region"          : "Калужская обл.",
    "utm_source"           : "vkontakte",
    "bank"                 :
    {
      "pan"                   : "408178**********2202",
      "issuer_country_code"   : "ru",
      "issuer_country"        : "Россия",
      "issuer"                : "ALFA-BANK"
    }
}

Ответ от Миксплат при возникновении ошибки

{
    "result"  : "error_subscription_not_found",
    "error_description" : "Subscription is not found"
}

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

Рекуррент — повторные безакцептные списания произвольных сумм с карты плательщика в произвольные моменты времени по запросу со стороны ТСП.

Возможность проведения рекуррентных платежей включается в настройках проекта и согласовывается отдельно через техническую поддержку. После успешного прохождения первого, установочного платежа от плательщика с помощью метода create_payment_form, в уведомлении payment_status, ТСП получит параметр recurrent_id, который является обязательным для проведения очередных рекуррентных платежей.

3.5.1 create_recurrent_payment​

Проведение очередного рекуррентного платежа на основе recurrent_id. Результатом вызова метода будет создание отдельного платежа с новым payment_id, но с тем же recurrent_id. Для определения в дальнейшем статуса этого платежа будут применяться методы payment_status и/или get_payment_status.

Направление запроса: ТСП → Миксплат
Тип запроса: POST-JSON (см. раздел 5.6)
URL запроса: https://api.mixplat.com/create_recurrent_payment

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

api_versionint

Версия API. Текущая актуальная версия: 3.

request_idstring|null

Уникальный идентификатор запроса, задаваемый ТСП, обеспечивающий идемпотентность вызовов (повторные запросы с тем же request_id не будут приводить к созданию нового платежа, а параметры ответа будут полностью повторять параметры ответа первоначального вызова с данным request_id).

Рекомендуется передавать этот параметр, чтобы защититься от дублирования платежей в результате сетевых проблем, задержек ответа и т. п.

В качестве request_id можно использовать идентификатор платежа в системе ТСП (если он уникален), или хеш от ключевых параметров запроса.

Проверка наличия другого запроса с данным request_id осуществляется за последние 30 дней.

Необязательный параметр. От 1 до 64 символов.
recurrent_idstring|null

ID привязанной карты, полученный ранее в уведомлении payment_status после инициации установочного платежа

Обязательный параметр

merchant_payment_idstring|null

ID платежа в ТСП.

Необязательный параметр. От 1 до 256 символов.
merchant_datastring|null

Произвольные данные ТСП, связанные с платежом.

Необязательный параметр. От 1 до 256 символов.
amountint

Сумма платежа в минорных единицах (копейках).
Валюта платежа та же, что была задана в первом, установочном платеже.
От 100 (1₽) до 100000000 (1млн₽).
Для конкретных проектов могут действовать более строгие ограничения.

Обязательный параметр
itemsjson-object|null

Данные для чека. Описание структуры – в разделе 3.7

Пример:

[
    {
        "name": "Xiaomi MI",
        "quantity": 2,
        "sum": 3500000,
        "vat": "vat20"
    }
]
Необязательный параметр.
signaturestring

Принцип формирования:
md5 (recurrent_id+API_KEY)

Символ "+" означает конкатенацию, recurrent_id — это строковые представления соответствующих параметров запроса, API_KEY — это секретный ключ сервиса для API запросов, узнать который можно в личном кабинете в настройках проекта.

Пример формирования:
md5(1449272c23a4398db8ef7b3ae1f4b07aeeb7c54f8e3c7c9)

Результат:
f05b57071a180a05bb161231896bee43

Параметры ответа от Миксплат

resultstring

Результат выполнения запроса (см. раздел 6.3).

При успешном выполнении метода "result": "ok"

Значение result = ok является подтверждением получения платёжного запроса, и не относится к статусу самого платежа.

error_descriptionstring

Описание ошибки, возникшей при выполнении запроса.

Присутствует только в случае ошибки при выполнения метода (result != ok).

payment_idstring|null

ID созданного платежа в системе Миксплат.

Присутствует только в случае ошибки при выполнения метода (result = ok).

Запрос от ТСП

POST https://api.mixplat.com/create_recurrent_payment
{
    "api_version"          : 3,
    "request_id"           : "324223",
    "recurrent_id"         : "Kslf8Jsk5JskqjcnFkod0ngH1ndiBdra",
    "merchant_payment_id"  : "571",
    "amount"               : 20000,
    "signature"            : "d9729feb74992cc3482b350163a1a010"
}

Успешный ответ от Миксплат

{
    "result"     : "ok",
    "payment_id" : "XXehOfcV7wM2z7YGFHs5vCYEeCrbD3mh"
}

Ответ от Миксплат при возникновении ошибки

{
    "result"  : "error_project_not_found",
    "error_description" : "Project 1203 is not found"
}

3.6 Двухэтапные платежи​

При создании платежа методами create_payment или create_payment_form с параметром payment_scheme=double не будет произведено автоматическое списание денежных средств, пока ТСП не подтвердит платёж методом confirm_payment.

3.6.1 confirm_payment​

Подтверждение платежа по банковским картам, созданного по двухэтапной схеме. Можно подтвердить изначально определённую сумму платежа, либо её часть через параметр amount в данном методе.

Направление запроса: ТСП → Миксплат
Тип запроса: POST-JSON (см. раздел 5.6)
URL запроса: https://api.mixplat.com/confirm_payment

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

api_versionint

Версия API. Текущая актуальная версия: 3.

payment_idstring

ID платежа в системе Миксплат.

amountint

Сумма платежа в минорных единицах (копейках).
Валюта платежа та же, что была задана в первом, установочном платеже.
От 100 (1₽) до 100000000 (1млн₽).
Для конкретных проектов могут действовать более строгие ограничения.

Небязательный параметр. Если не задан, сумма списания остаётся той же, которая была указана изначально в create_payment_form
signaturestring

Принцип формирования:
md5 (payment_id+API_KEY)

Символ "+" означает конкатенацию, payment_id — это строковые представления соответствующих параметров запроса, API_KEY — это секретный ключ сервиса для API запросов, узнать который можно в личном кабинете в настройках проекта.

Пример формирования:
md5(707607041c23a4398db8ef7b3ae1f4b07aeeb7c54f8e3c7c9)

Результат:
047780e4f51dc6664d333536a6b4aab8

Параметры ответа от Миксплат

resultstring

Результат выполнения запроса (см. раздел 6.3).

При успешном выполнении метода "result": "ok"

Значение result = ok является подтверждением получения платёжного запроса, и не относится к статусу самого платежа.

error_descriptionstring

Описание ошибки, возникшей при выполнении запроса.

Присутствует только в случае ошибки при выполнения метода (result != ok).

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

Запрос от ТСП

POST https://api.mixplat.com/confirm_payment
{
    "api_version" : 3,
    "payment_id"  : "XXehOfcV7wM2z7YGFHs5vCYEeCrbD3mh",
    "signature"   : "d9729feb74992cc3482b350163a1a010"
}

Успешный ответ от Миксплат

{
    "result" : "ok"
}

Ответ от Миксплат при возникновении ошибки

{
    "result"  : "error_payment_not_found",
    "error_description" : "Payment is not found"
}

3.6.2 cancel_payment​

Отмена платежа по банковским картам, созданного по двухэтапной схеме.

URL запроса: https://api.mixplat.com/cancel_payment

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

api_versionint

Версия API. Текущая актуальная версия: 3.

payment_idstring

ID платежа в системе Миксплат.

signaturestring

Принцип формирования:
md5 (payment_id+API_KEY)

Символ "+" означает конкатенацию, payment_id — это строковые представления соответствующих параметров запроса, API_KEY — это секретный ключ сервиса для API запросов, узнать который можно в личном кабинете в настройках проекта.

Пример формирования:
md5(707607041c23a4398db8ef7b3ae1f4b07aeeb7c54f8e3c7c9)

Результат:
047780e4f51dc6664d333536a6b4aab8

Параметры ответа от Миксплат

resultstring

Результат выполнения запроса (см. раздел 6.3).

При успешном выполнении метода "result": "ok"

Значение result = ok является подтверждением получения платёжного запроса, и не относится к статусу самого платежа.

error_descriptionstring

Описание ошибки, возникшей при выполнении запроса.

Присутствует только в случае ошибки при выполнения метода (result != ok).

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

Запрос от ТСП

POST https://api.mixplat.com/cancel_payment
{
    "api_version" : 3,
    "payment_id"  : "XXehOfcV7wM2z7YGFHs5vCYEeCrbD3mh",
    "signature"   : "d9729feb74992cc3482b350163a1a010"
}

Успешный ответ от Миксплат

{
    "result" : "ok"
}

Ответ от Миксплат при возникновении ошибки

{
    "result"  : "error_payment_not_found",
    "error_description" : "Payment is not found"
}

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

3.7.1 items​

Параметр items представляет собой JSON массив, элементы которого являются JSON объектами, описывающими товары/услуги, которые должны быть отражены в фискальном чеке. Поля такого объекта описаны в таблице:

namestring

Наименование позиции товара/услуги.

sumint

Стоимость позиции данных товаров/услуг (в минорных единицах).

quantityfloat|null

Количество товара/услуги. Дробное число с разделителем-точкой.

Необязательное поле, по умолчанию: 1

unitstring|int|null

Единица измерения количества. В случае ФФД 1.05 передается в виде строки (шт., кг, литр и т.д.).
В случае ФФД 1.2 передается числовое значение (см. ниже items.unit)

Необязательное поле для ФФД 1.05, по умолчанию: "шт." Обязательное поле для ФФД 1.2, по умолчанию 0

vatstring|null

НДС (см. ниже items.vat).

Необязательное поле, по умолчанию берётся из настроек компании.

methodstring|null

Способ взаиморасчёта (см. ниже items.method).

Необязательное поле, по умолчанию берётся из настроек компании.

objectstring|null

Тип товаров/услуг (см. ниже items.object).

Необязательное поле, по умолчанию берётся из настроек компании.

items.vat​

НДС на позицию чека.

noneБез НДС
vat0НДС 0%
vat5НДС 5%
vat7НДС 7%
vat10НДС 10%
vat105НДС 5/105
vat107НДС 7/107
vat110НДС 10/110
vat20НДС 20%
vat120НДС 20/120

items.method​

Признак способа расчёта по позиции чека.

full_paymentПолная оплата, в том числе с учетом аванса
full_prepaymentПолная предварительная оплата до момента передачи предмета расчета
prepaymentЧастичная предварительная оплата до момента передачи предмета расчета
advanceАванс
partial_paymentЧастичная оплата предмета расчета в момент его передачи с последующей оплатой в кредит
creditПередача предмета расчета без его оплаты в момент его передачи с последующей оплатой в кредит
credit_paymentОплата предмета расчета после его передачи с оплатой в кредит (оплата кредита).

items.object​

Признак предмета расчёта.

commodityРеализация товаров
exciseРеализация подакцизных товаров
jobВыполнение работ
serviceОказание услуг
paymentАванс, задаток, предоплата, кредит, пени, штраф, вознаграждение, бонус и т.д.
property_rightПередача имущественных прав
compositeПредмет расчета, состоящий из нескольких признаков
anotherПредмет расчета, не относящийся ни к одному из перечисленным предметов расчета

items.unit​

Единица измерения количества (для ФФД версии 1.2).

0Применяется для предметов расчета, которые могут быть реализованы поштучно или единицами
10Грамм
11Килограмм
12Тонна
20Сантиметр
21Дециметр
22Метр
30Квадратный сантиметр
31Квадратный дециметр
32Квадратный метр
40Миллилитр
41Литр
42Кубический метр
50Киловатт-час
51Гигакалория
70Сутки (день)
71Час
72Минута
73Секунда
80Килобайт
81Мегабайт
82Гигабайт
83Терабайт
255Применяется при использовании иных единиц измерения