# API единой платежной формы

Перед началом работы создайте платежную ссылку и API-ключ. Все запросы и ответы — в JSON, кодировка UTF-8.

Типовой сценарий:

  1. Ваша система создает счет → получает paymentId.
  2. Перенаправляет клиента на https://secure-app.mandarin.io/payment/{paymentId}.
  3. Клиент выбирает способ и платит или оформляет заявку.
  4. Mandarin присылает вебхук при каждом изменении счета.
  5. Ваша система сверяет итог запросом статуса и выдает заказ.

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

POST https://secure-app.mandarin.io/api/v1/public/invoices/

Все параметры, кроме payment_options_id, необязательны: то, что не передано, берется из настроек платежной ссылки.

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

Параметр Тип Обязателен Описание
payment_options_id string (UUID) Да ID платежной ссылки. Определяет компанию, оформление и настройки счета
order object Нет Данные заказа и клиента
order.id string Нет Номер заказа в вашей системе. Если блок order передан без id, номер сгенерируется автоматически (UUID). Возвращается в статусе счета как order_id
order.email string Нет Email клиента. Если не передан, клиент укажет его на странице
order.phone string Нет Телефон клиента: +79001234567 или 79001234567. Если не передан, клиент укажет его на странице
cart object Нет Корзина. Если не передана, используется корзина платежной ссылки
cart.items array Да, если передан cart Позиции корзины, минимум одна
cart.items[].description string Да Название товара или услуги — отображается клиенту и попадает в чек
cart.items[].total_price number Да Стоимость позиции в рублях, разделитель — точка
cart.items[].vat string Да Ставка НДС, см. значения
cart.items[].quantity integer Нет Количество, по умолчанию 1
cart.items[].price number Нет Цена за единицу. Если передана, должно выполняться price × quantity = total_price
cart.items[].calculation_method string Нет Способ расчета для чека, см. значения
cart.items[].payment_subject string Нет Предмет расчета для чека, например SERVICE, COMMODITY
cart.total_price number Нет Итоговая сумма для проверки: если передана, должна совпадать с суммой total_price всех позиций
cart.fiscal_receipt_is_required boolean Нет Формировать чек по 54-ФЗ. По умолчанию false
payment_method_types array of string Нет Способы оплаты для этого счета: rus_card, int_card, credit, sber, dolki. Если не передан — все способы, включенные на ссылке. Пустой массив не допускается
payment_method_options object Нет Настройки способов оплаты
payment_method_options.credit.terms array of string Нет Сроки кредита и рассрочки в месяцах, например ["6", "12", "24"]. См. Рассрочка и кредит
urls object Нет Адреса для переходов. Должны быть корректными URL
urls.success_redirect string Нет Куда вернуть клиента после успешной оплаты
urls.fail_redirect string Нет Куда вернуть клиента при неуспешной оплате
urls.conditions string Нет Ссылка на вашу оферту или условия продажи
custom_values array Нет Дополнительные поля, которые отображаются клиенту на странице счета
custom_values[].name string Да Название поля, например «Номер договора». Вместо name можно передать key
custom_values[].value string Да Значение поля
assistance_is_required boolean Нет Клиенту нужна помощь с оформлением рассрочки. По умолчанию false. См. Рассрочка и кредит

# Ставки НДС

None (без НДС), Vat0, Vat5, Vat7, Vat10, Vat20, Vat22.

# Способ расчета

Значение Описание
PREPAY_FULL Полная предварительная оплата до передачи предмета расчета
PREPAY_PARTIAL Частичная предварительная оплата до передачи предмета расчета
AVANS Аванс
FULL_PAY Полная оплата, в том числе с учетом аванса, в момент передачи предмета расчета
PARTIAL_SETTLEMENT_AND_CREDIT Частичная оплата в момент передачи с последующей оплатой в кредит
TRANSFER_ON_CREDIT Передача без оплаты с последующей оплатой в кредит
CREDIT_PAYMENT Оплата кредита после передачи предмета расчета

# Пример запроса

curl --request POST \
  --url https://secure-app.mandarin.io/api/v1/public/invoices/ \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: {{api_key}}' \
  --data-raw '{
    "payment_options_id": "2d28e8bf-0d60-45ca-b8b4-172820086117",
    "order": {
      "id": "ORDER-000123",
      "email": "client@example.com",
      "phone": "+79001234567"
    },
    "cart": {
      "fiscal_receipt_is_required": true,
      "total_price": 120000.00,
      "items": [
        {
          "description": "Курс «Аналитик данных»",
          "quantity": 1,
          "price": 120000.00,
          "total_price": 120000.00,
          "vat": "None",
          "calculation_method": "FULL_PAY",
          "payment_subject": "SERVICE"
        }
      ]
    },
    "payment_method_types": ["rus_card", "credit", "dolki"],
    "payment_method_options": {
      "credit": { "terms": ["6", "12", "24"] }
    },
    "urls": {
      "success_redirect": "https://example.com/order/123/success",
      "fail_redirect": "https://example.com/order/123/fail",
      "conditions": "https://example.com/oferta"
    },
    "custom_values": [
      { "name": "Номер договора", "value": "Д-2026-0042" }
    ]
  }'

# Ответ

Счет создан (201 Created)

{
  "success": true,
  "paymentId": "8762f870-1790-4aaf-a8a3-994c548836fd",
  "message": "Invoice created successfully"
}

paymentId — ID счета. Сохраните его: по нему запрашивается статус, он же приходит в вебхуке как invoice_id.

Ошибка в параметрах (400 Bad Request) — в теле указано поле с ошибкой:

{
  "payment_method_types": ["Unknown payment method types: dolki"]
}
Ошибка Причина
Unknown payment method types: ... Способ не настроен на платежной ссылке
If provided, must contain at least one method Передан пустой payment_method_types
Provided total_price does not match sum of items total_price cart.total_price не равен сумме позиций
Total price does not match price * quantity В позиции price × quantity ≠ total_price
Access denied or invalid client_id Ссылка принадлежит другой компании
No active payment settings found for client_id У компании не настроены счета в ЛК

Ошибка авторизации (401 Unauthorized) — неверный или неактивный API-ключ, либо на ссылке выключена интеграция.

# Перенаправление клиента

https://secure-app.mandarin.io/payment/{paymentId}

Ссылку можно открыть в браузере, отправить в мессенджер или по SMS. Чтобы сразу открыть нужный способ, добавьте его в конец адреса — см. Способы оплаты.

# Статус счета

GET https://secure-app.mandarin.io/api/v1/public/invoices/{invoice_id}/check-state/

Возвращает текущий статус счета и все операции по нему. Тот же объект приходит в вебхуке.

curl --request GET \
  --url https://secure-app.mandarin.io/api/v1/public/invoices/8762f870-1790-4aaf-a8a3-994c548836fd/check-state/ \
  --header 'X-API-Key: {{api_key}}'

Ответ (200 OK) — счет на 120 000 ₽: первая попытка оплатить картой не прошла, затем клиент оформил рассрочку:

{
  "invoice_id": "8762f870-1790-4aaf-a8a3-994c548836fd",
  "created_at": "2026-11-10T10:15:00+00:00",
  "order_id": "ORDER-000123",
  "amount": "120000.00",
  "currency": "RUB",
  "invoice_status": "paid",
  "total_paid": "120000.00",
  "remaining_amount": "0.00",
  "payment_breakdown": [
    {
      "method": "card",
      "method_type": "cash",
      "amount": "0.00",
      "timestamp": "2026-11-10T10:16:12+00:00",
      "status": "failed",
      "id": "f4107e90f98447978036383f6754325e",
      "additional_id": "23290726",
      "settlement_amount": null
    },
    {
      "method": "credit",
      "method_type": "credit",
      "amount": "120000.00",
      "timestamp": "2026-11-10T10:21:40+00:00",
      "status": "success",
      "id": "A1B2C3D4-E5F6-47A8-9B0C-1D2E3F4A5B6C",
      "additional_id": "884201",
      "settlement_amount": "106800.00",
      "payment_method_metadata": {
        "loan_term": 12
      }
    }
  ],
  "customer": {
    "email": "client@example.com",
    "phone": "+79001234567"
  }
}

Счет не найден (404 Not Found) — неверный ID или счет создан по другой ссылке, а запрос сделан ее ключом.

# Поля ответа

Поле Описание
invoice_id ID счета (paymentId)
created_at Дата создания счета, ISO 8601
order_id Номер заказа
amount Сумма счета
currency Валюта, RUB
invoice_status Статус счета, см. Статусы
total_paid Сколько оплачено всеми операциями
remaining_amount Сколько осталось оплатить
payment_breakdown Все операции по счету в порядке создания, включая неуспешные
payment_breakdown[].method Способ: card, card2, credit, sber, dolki
payment_breakdown[].method_type Тип: cash — карты и СБП, credit — кредит и рассрочка, bnpl — Сбер и Дольки
payment_breakdown[].amount Оплачено этой операцией. У Долек растет по мере оплаты частей
payment_breakdown[].timestamp Время создания операции
payment_breakdown[].status Статус операции, см. Статусы
payment_breakdown[].id ID операции. Что это за ID для каждого способа — на страницах способов оплаты
payment_breakdown[].additional_id Дополнительный ID: для карт — ID в процессинге, для кредита — ID предложения банка
payment_breakdown[].settlement_amount Сумма к перечислению вам за вычетом комиссии. Карты — после расчета комиссии, до этого null. Кредит — по выбранному предложению. Дольки — amount минус 7%. Сбер — null
payment_breakdown[].payment_method_metadata.loan_term Только для кредита: срок в месяцах
customer.email, customer.phone Контакты клиента

# Статусы

# Статусы счета

Статус Значение
pending Счет создан, оплат пока нет
partially_paid Оплачена часть суммы: например, первая часть по Долькам или часть картой
paid Счет оплачен полностью. Только этот статус означает, что заказ можно выдавать
cancelled Счет закрыт без оплаты. Сейчас так закрываются счета, в которых включен только кредит, если банки окончательно отказали

# Статусы операции

Статус Значение
processing Идет оплата, рассмотрение заявки или подписание; у Долек — выплата частей по графику
success Оплата прошла, кредит подписан или Дольки погашены полностью
failed Отказ банка или платежной системы, клиент отменил, заявка отклонена

Как статусы меняются для каждого способа — на страницах карт, рассрочки, Сбера и Долек.

ОБРАТИТЕ ВНИМАНИЕ!

Решение о выдаче заказа принимайте по invoice_status счета, а не по статусу отдельной операции. Один счет может закрываться несколькими операциями, а неуспешные попытки остаются в payment_breakdown.

# Список транзакций

GET https://secure-app.mandarin.io/api/v1/public/invoice-transactions/

Сквозной список операций по счетам платежной ссылки — для сверки и выгрузки в учетную систему. Возвращаются операции только по счетам той ссылки, к которой привязан API-ключ.

# Параметры

Параметр Описание
invoice_id Операции одного счета
type, type__in Способ: card, sbp, credit, sber, dolki. Несколько — через запятую: type__in=card,credit
method_type, method_type__in Тип: cash, credit, bnpl
status, status__in Статус операции, например success, failed
date_from, date_to Период по дате создания операции, ISO 8601
customer_email, customer_phone Контакты клиента, точное совпадение
limit_to Размер страницы, по умолчанию 10
cursor Курсор следующей или предыдущей страницы из ответа
curl --request GET \
  --url 'https://secure-app.mandarin.io/api/v1/public/invoice-transactions/?type__in=credit,dolki&date_from=2026-11-01T00:00:00Z&limit_to=50' \
  --header 'X-API-Key: {{api_key}}'

Ответ (200 OK)

{
  "cursor": {
    "count": 1,
    "prev": null,
    "total": 1,
    "next": null
  },
  "transactions": [
    {
      "method": "dolki",
      "method_type": "bnpl",
      "amount": "30000.00",
      "timestamp": "2026-11-05T08:02:11+00:00",
      "status": "processing",
      "id": "7c1e4b0a-3d2f-4e5a-9b8c-0f1e2d3c4b5a",
      "additional_id": "51234",
      "settlement_amount": "27900.00",
      "invoice_id": "0b6f3a1e-8c2d-4f7a-9e1b-2c3d4e5f6a7b",
      "payment_link_id": "2d28e8bf-0d60-45ca-b8b4-172820086117",
      "order_id": "ORDER-000119",
      "customer": {
        "email": "client@example.com",
        "phone": "+79001234567"
      }
    }
  ]
}

Поля операции — как в payment_breakdown, плюс контекст счета: invoice_id, payment_link_id, order_id, customer. Для кредита добавляется metadata.credit_term — срок в месяцах. Для Сбера — metadata.order_amount: сумма заявки, пока она в обработке и amount равен 0.

# Вебхуки

Если на платежной ссылке включены колбэки, Mandarin отправляет POST на указанный URL. Тело — JSON, такой же, как ответ статуса счета.

# Когда отправляется

  • при создании счета (invoice_status: pending);
  • при каждом изменении статуса счета;
  • при каждом изменении оплаченной суммы — например, после оплаты очередной части по Долькам;
  • когда операция завершилась успешно или неуспешно — даже если статус счета не изменился (например, клиенту отказали в кредите, и он пошел платить картой).

Повторы одного события возможны. Обрабатывайте вебхуки идемпотентно: ориентируйтесь на invoice_id, invoice_status и total_paid, а не на сам факт уведомления.

# Ответ на вебхук

Ответьте любым кодом 2xx в течение 10 секунд. Если ответ другой или его нет, Mandarin повторит отправку: через 1 минуту, затем с удвоением интервала (2, 4, 8 минут и т. д.), всего до 10 повторов.

БЕЗОПАСНОСТЬ

Вебхук не подписывается. Перед выдачей заказа подтвердите статус запросом check-state с вашим API-ключом.

# Возвраты

Способ Как вернуть
Карты В личном кабинете или через API отмены платежа, см. Банковские карты
Кредит и рассрочка Через сопровождение Mandarin по заявлению клиента, см. Рассрочка и кредит
СБП, Сбер, Дольки Обратитесь к вашему менеджеру или в Службу поддержки (opens new window)