Mandarin

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

# Точки входа

Боевое (production) окружение для авторизации: https://accounts.mandarinbank.com/ (opens new window)
Боевое (production) окружение для запросов: https://api.psp.io/ (opens new window)

# Аутентификация запросов

Каждый запрос должен быть аутентифицирован с помощью токена (access_token), полученного в соответствии с протоколом OAuth 2.0 для приложений. Токен действует в течение 36 000 секунд (10 часов). Если срок действия истек, токен нужно запросить еще раз.

Обратитесь в Службу поддержки (opens new window), чтобы узнать ваш client_id и client_secret, чтобы получить access_token.

Запрос на получение токена

Включает в себя обязательные form-data параметры, которые передаются в теле запроса (параметры application.client_id и application.client_secret неизменны для приложения и хранятся на стороне клиента).

Параметр Описание Пример
grant_type Грант авторизации (всегда равен client_credentials). client_credentials
client_id Идентификатор клиента (равен значению application.client_id, предоставленному Mandarin). VvPtlhcyldKtkuoUWY42 pErdrj4er2AwFoBWrn8n
client_secret Секретный ключ-пароль клиента (равен значению application.client_secret, предоставленному Mandarin). uQfOIMsltZYL8x3XMqUGP5 iFM59PyFnKlN0UmD3Ihre2 Ry3AGazUAv5jPdUI4dBJqV 0Of6b9GFvWvzGahYnq2aVV xkxn9n4qWF57FP0C01Kp6l EtajhfYv3UZ2f4pAZ7
scope Запрашиваемые скоупы (области доступа):
например, secure_app_client_payment_invoices.write - создание и редактирование счетов.
Запрашивать можно любой список скоупов (разделитель - пробел), при этом в ответе вернется тот список запрошенных скоупов, который может быть предоставлен для данного приложения.
 secure_app_client_payment_invoices.write

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

curl --location --request POST 'https://accounts.mandarinbank.com/oauth/token/' \
--form 'grant_type=client_credentials' \
--form 'client_id=VvPtlhcyldKtkuoUWY42pErdrj4er2AwFoBWrn8n' \
--form 'client_secret=uQfOIMsltZYL8x3XMqUGP5iFM59PyFnKlN0UmD3Ihre2Ry3AGazUAv5jPdUI4dBJqV0Of6b9GFvWvzGahYnq2aVVxkxn9n4qWF57FP0C01Kp6lEtajhfYv3UZ2f4pAZ7' \
--form 'scope=secure_app_client_payment_invoices.write'

Ответ:

Параметр Описание Пример
access_token Токен (ключ доступа). VnuxZiW14mXBedDeZO7d W7GBmzPxMn
expires_in Срок действия токена (в секундах). Всегда равен 36 000 секунд (10 часов). 36000
token_type Тип токена (всегда равен Bearer). Bearer
scope Разрешенные скоупы (области доступа):
например, secure_app_client_payment_invoices.write - создание и редактирование счетов.
Запрашивать можно любой список скоупов (разделитель - пробел), при этом в ответе вернется тот список запрошенных скоупов, который может быть предоставлен для данного приложения.
 secure_app_client_payment_invoices.write
{
    "access_token": "VnuxZiW14mXBedDeZO7dW7GBmzPxMn",
    "expires_in": 36000,
    "token_type": "Bearer",
    "scope": "scope=secure_app_client_payment_invoices.write"
}

Использование токена

Указывается в headers каждого запроса, в поле Authorization, после зарезервированного слова Bearer.

Authorization:Bearer VnuxZiW14mXBedDeZO7dW7GBmzPxMn

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

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

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

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

Для вызова метода используется Bearer-токен:
Authorization: Bearer {token}

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

Параметр Обязательность Тип Описание
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 'Authorization: Bearer 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

← API для кредитора →