# API единой платежной формы
Перед началом работы создайте платежную ссылку и API-ключ. Все запросы и ответы — в JSON, кодировка UTF-8.
Типовой сценарий:
- Ваша система создает счет → получает
paymentId. - Перенаправляет клиента на
https://secure-app.mandarin.io/payment/{paymentId}. - Клиент выбирает способ и платит или оформляет заявку.
- Mandarin присылает вебхук при каждом изменении счета.
- Ваша система сверяет итог запросом статуса и выдает заказ.
# Создание счета
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) |