Mandarin

# Быстрый старт

Быстрый старт подходит любому онлайн-бизнесу, которому нужно начать принимать платежи и делать выплаты в кратчайшие сроки. Все инструменты настраиваются в личном кабинете — без разработки и без подключения к API.

# Форма для выплат

Форма для выплат — готовый инструмент в личном кабинете Mandarin для одиночных и разовых выплат на банковские карты без интеграции по API.

Подходит, если вам нужно:

  • переводить деньги на карты сотрудникам, подрядчикам или клиентам;
  • работать с любого устройства (компьютер, смартфон, планшет);
  • задавать лимиты и контролировать операции в режиме реального времени.

Для начала работы:

  1. Зарегистрируйте личный кабинет (opens new window) Mandarin.
  2. Предоставьте документы и пройдите согласование у банка-партнера.
  3. Откройте расчетный счет для выплат и пополните его.
  4. Создайте форму для выплат в разделе Выплаты → По форме личного кабинета.
  5. Настройте лимиты и параметры формы.

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

Подробная инструкция по настройке формы для выплат (opens new window)

# Выплаты по реестру

Выплаты по реестру — способ массовой отправки денег на карты по заранее подготовленному файлу (реестру). Интеграция по API не требуется: вы загружаете файл в личный кабинет, система проверяет данные и запускает выплаты.

Подходит, если вам нужно:

  • выплатить вознаграждения или премии большому числу получателей за один раз;
  • использовать привычный формат Excel/CSV вместо программирования;
  • контролировать итоговую сумму и количество операций перед запуском.

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

Для выплат по реестру нужны полные номера карт получателей.

Для начала работы:

  1. Зарегистрируйте личный кабинет (opens new window) Mandarin.
  2. Предоставьте документы и пройдите согласование у банка-партнера.
  3. Откройте расчетный счет для выплат в согласованном банке.
  4. Пополните счет для массовых выплат.
  5. Создайте форму для массовых выплат в разделе Выплаты → По форме личного кабинета.

Как провести выплату:

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

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

Перед боевыми выплатами рекомендуем провести тестовые операции.

# Поля реестра для выплат на банковские карты

Параметр Обязателен Описание
order_id Да Номер заказа в вашей системе. Должен быть уникальным среди успешных операций.
amount Да Сумма выплаты.
card_number Да Полный номер карты получателя.
email Да, если поле есть в шаблоне Email получателя. Формат: user@example.com.
phone Да, если поле есть в шаблоне Телефон получателя в формате РФ: +79001234567.

Если в настройках формы указано, что поля email и phone заполняются по умолчанию, в шаблоне реестра они отсутствуют.

Формат ячеек и выравнивание в файле на обработку реестра не влияют.

# Единая платежная форма

# Точки входа

Боевое (production) окружение для запросов: https://secure-app.mandarin.io/api/v1/public/invoices/ (opens new window)

# Авторизация

Запросы аутентифицируются API-ключом (X-Api-Key). Ключ создается в личном кабинете в настройках платежной ссылки (раздел «Интеграция»). Подробнее — в разделе Аутентификация запросов.

В примерах ниже используется шаблон --header 'Authorization: X-Api-Key: '.

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

Метод используется для создания счета (инвойса), по которому клиент может произвести оплату через стандартную платежную страницу Mandarin. После успешного создания счета API возвращает paymentId, по которому формируется ссылка на оплату.

Метод: POST https://secure-app.mandarin.io/api/v1/public/invoices/

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

Параметр Обязательность Тип Описание
payment_options_id Да string ID платежной ссылки из личного кабинета Mandarin. Определяет проект и настройки оплаты.
order Нет object Данные заказа
order.id Нет string Внутренний идентификатор заказа
order.email Нет string Email клиента. Если не указан, будет запрошен на странице оплаты
order.phone Нет string Телефон клиента. Если не указан, будет запрошен на странице оплаты
urls Нет object URL для перенаправления
urls.success_redirect Нет string URL для перенаправления после успешной оплаты
urls.fail_redirect Нет string URL для перенаправления при неудачной оплате
urls.conditions Нет string Ссылка на оферту или условия продажи
cart Да object Данные корзины
cart.fiscal_receipt_is_required Да boolean Признак необходимости формирования фискального чека
cart.total_price Да number Общая сумма заказа в рублях. Должна совпадать с суммой всех позиций
cart.items Да array Список товаров или услуг
cart.items[].quantity Да integer Количество единиц товара
cart.items[].price Да number Цена за единицу (в рублях)
cart.items[].total_price Да number Общая стоимость позиции
cart.items[].vat Да string Ставка НДС (Vat0, Vat10, Vat20)
cart.items[].description Да string Название или описание товара/услуги
cart.items[].calculation_method Да string Метод расчета (PREPAY_FULL, FULL_PAYMENT и т. д.)
cart.items[].payment_subject Да string Предмет оплаты (SERVICE, COMMODITY, WORK и т. д.)
payment_method_options Нет object Настройки методов оплаты
payment_method_options.credit.terms Нет array Сроки рассрочки (в месяцах)
payment_method_types Нет array Разрешенные методы оплаты (rus_card, int_card, credit)

# Что такое payment_options_id и где его взять

payment_options_id — это ID платежной ссылки, созданной в вашем личном кабинете Mandarin. Он определяет, в рамках какого проекта и с какими настройками будет создан счет.

Как получить payment_options_id:

  1. Перейдите в раздел «Счета / Ссылки» в личном кабинете Mandarin
  2. Найдите нужную ссылку, которую хотите использовать для выставления счетов через API
  3. Откройте ее настройки — в URL вы увидите параметр id, например:
    https://secure-app.mandarin.io/dashboard/invoices/links/2d28e8bf-0d60-45ca-b8b4-172820086117
  4. Значение 2d28e8bf-0d60-45ca-b8b4-172820086117 — это и есть ваш payment_options_id

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

curl --request POST \
  --url https://secure-app.mandarin.io/api/v1/public/invoices/ \
--header 'Authorization: X-Api-Key: {{api_key}}' \
--header 'Content-Type: application/json' \
--data '{
"payment_options_id": "2d28e8bf-0d60-45ca-b8b4-172820086117",
"order": {
 "id": "NewOrder_000000000001",
 "email": "ya@ya.ru",
 "phone": "79163025599"
},
"urls": {
 "success_redirect": "https://google.com",
 "fail_redirect": "https://ya.ru",
 "conditions": "https://string"
},
"cart": {
 "fiscal_receipt_is_required": true,
 "total_price": 20000.00,
 "items": [
   {
     "quantity": 2,
     "price": 10000.00,
     "vat": "Vat20",
     "description": "Доставка",
     "total_price": 20000.00,
     "calculation_method": "PREPAY_FULL",
     "payment_subject": "SERVICE"
   }
 ]
},
"payment_method_options": {
 "credit": {
   "terms": ["3", "6", "12", "18", "24"]
 }
},
"payment_method_types": ["rus_card", "credit", "int_card"]
}'

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

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

# Проверка статуса счета

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

Для получения статусов в автоматическом режиме — необходимо перейти в настройки ссылки в Личном кабинете, для которой была создана интеграция, и активировать параметр Отправлять колбэки (Webhook) и указать URL, на который вы хотите получать информацию об изменении статусов счета.

Для проверки статуса счета вручную используется API запрос, в котором в paymentId передается идентификатор счета, полученный при его создании.

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

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

Пример ответа:

В обоих случаях структура получаемого ответа одинакова и выглядит следующим образом

{
    "invoice_id": "74576aa7-ba80-4ce0-80db-cd5603095746",
    "created_at": "2026-05-13T10:15:00+00:00",
    "order_id": "123456",
    "amount": "1000.00",
    "currency": "RUB",
    "invoice_status": "processing",
    "total_paid": "5000.00",
    "remaining_amount": "1000.00",
    "payment_breakdown": [
        {
            "method": "card",
            "method_type": "cash",
            "amount": "5000.00",
            "timestamp": "2026-05-13T10:15:00+00:00",
            "status": "success",
            "id": "f4107e90f98447978036383f6754325e",
            "additional_id": "23290726",
            "settlement_amount": "5000.00",
            "payment_method_metadata": {
                "loan_term": 12
            }
        }
    ],
    "customer": {
        "email": "test@mandarin.io",
        "phone": "79999999999"
    }
}

При автоматическом режиме в случае неудачной доставки (код ответа не 2xx), система будет повторять попытки удваивая интервал между попытками в течение 24 часов (вторая попытка через минуту).
Всего будет до 10 повторных попыток отправки.

Описание значений:

Значение Описание
invoice_id идентификатор счета, paymentId
order_id номер заказа
amount общая сумма счета
currency валюта
invoice_status статусы счета: processing, paid, partially_paid (в процессе, оплачен, частично оплачен)
total_paid всего оплачено уже
remaining_amount остаток к оплате
payment_breakdown массив попыток оплаты
payment_breakdown.method метод оплаты детально (card - для оплат картой РФ, card2 - для зарубежных оплат, sbp - СБП оплата, credit - кредит/рассрочка, bnpl - дольки)
payment_breakdown.method_type абстракция верхнего уровня - cash объединяет оплаты из РФ и зарубежные
payment_breakdown.amount сумма оплаты
payment_breakdown.status cтатус операции: processing, approved, success, failed
payment_breakdown.id id заявки или операции в API: application_id, order.id, secure_data.id
payment_breakdown.additional_id id заявки или платежа в платежном шлюзе: offer_id, gw_id, tx.id
payment_breakdown.settlement_amount сумма к перечислению на счет компании без учета комиссии(Decimal или null)
payment_breakdown.payment_method_metadata только для кредитов/рассрочек указание срока, на который была оформлена заявка
customer массив данных клиента
customer.email e-mail клиента
customer.phone телефон клиента

# Дальнейшие действия

После получения paymentId необходимо перенаправить пользователя на страницу оплаты:
https://secure-app.mandarin.io/payment/{paymentId}
Пример:

https://secure-app.mandarin.io/payment/8762f870-1790-4aaf-a8a3-994c548836fd

# Дольки

Дольки — это коммерческая рассрочка без банков и МФО, которая помогает бизнесу не терять клиентов, если им неудобно оплачивать покупку сразу или банковская рассрочка недоступна.

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

Подробнее (opens new window)

← Готовые интеграции →