Mandarin

# Интеграция единой платежной формы

# Точки входа

Боевое (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"
}

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

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

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

← Тестирование платежных продуктов →