Mandarin

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

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

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

Инструкция как настроить модуль. (opens new window)

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

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

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

Для данного типа выплат нужны полные номера карт получателей!

Для использования необходимо:

  1. Зарегистрировать личный кабинет в Mandarin. После регистрации у вашей компании появится личный кабинет. В нем возможно получать информацию о статусе платежей, редактировать профиль и реквизиты компании, подключать новые проекты и сервисы, обращаться в Службу поддержки (opens new window) Mandarin, а также к персональному менеджеру.
  2. Предоставить документы и пройти согласование у банка-партнера.
  3. Открыть расчетный счет для выплат в банке, в котором пройдено согласование.
  4. Пополнить счет для массовых выплат.
  5. Создать в разделе Модули личного кабинета готовый модуль для массовых выплат Mandarin.
  6. Скачать пустой шаблон реестра из настроек модуля для массовых выплат. Количество полей в шаблоне зависит от настроек вашей компании.
  7. Заполнить шаблон реестра данными, и загрузить его в систему.
  8. После загрузки проверить, совпадают ли количество транзакций и сумма, а также номера карт. Если все верно, то можно нажимать "Начать выплаты".
  9. Ознакомиться с результатами выполнения выплат в интерфейсе, или сохранить в файл.

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

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

Набор полей для выплаты по реестру на банковские карты

Параметр Обязателен Описание и возможные значения
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)

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

Каждый запрос должен быть аутентифицирован с помощью X-Api-Key, созданного в Личном Кабинете в настройках платёжной ссылки (Раздел "Интеграция" - создать новый API ключ). Ключ добавляется в заголовок в формате Authorization: X-Api-Key: YOUR_API_KEY_VALUE

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

Метод используется для создания счёта (инвойса), по которому клиент может произвести оплату через стандартную платёжную страницу 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 --location 'https://secure-app.mandarin.io/api/v1/public/invoices/' \
--header 'X-Api-Key: Nwii9xFAfHjAWkk6PPOFUmpheFe123' \
--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 передается идентификатор счета, полученный при его создании.

Запрос:

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

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

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

{
    "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

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