Создание заявки
Endpoint для создания заявки на прием платежа:
POST https://api.meridian.vip/api/v1/invoices
Обязательные параметры
| Параметр | Тип | Описание |
|---|
internalId | string | Уникальный идентификатор заявки в вашей системе для защиты от дубликатов. |
direction | string | Направление платежа. Для приема используйте "in". Допустимые значения: "in" (входящий), "out" (исходящий) |
amount | number | Сумма платежа. Примеры: 1000 = 1000 RUB |
currency | string | Код валюты ISO 4217. Пока доступно: "RUB", "AZN" |
startDeal | boolean | Всегда ‘“true“‘ |
notificationUrl | string | URL для webhook уведомлений о смене статуса заявки. Требования: валидный HTTPS URL. Пример: "https://your-site.com/webhooks/meridian" |
notificationToken | string | Секретный токен для HMAC-SHA256 подписи webhook. Требования: 32-255 символов |
Опциональные параметры
| Параметр | Тип | Описание |
|---|
paymentMethod | string | Метод платежа: "SBP" (Система быстрых платежей, рекомендуется), "TO_CARD" (перевод на карту), “MOBILE” (мобильная коммерция) |
paymentOption | string | Банк для платежа (зависит от доступности реквизитов): "sberbank", "tinkoff", "alfa", "vtb", "raiffeisen" |
successUrl | string | URL для редиректа после успешной оплаты. При наличии successUrl, cancelUrl и errorUrl в ответе вернётся paymentUrl — ссылка на hosted-страницу оплаты. Должен использовать HTTPS (кроме localhost) |
cancelUrl | string | URL для редиректа при отмене клиентом. Должен использовать HTTPS (кроме localhost) |
errorUrl | string | URL для редиректа при ошибке или истечении срока. Должен использовать HTTPS (кроме localhost) |
customerId | string | Идентификатор клиента (плательщика) в вашей системе |
Контрагенты
Передача поля customerId при создании заявки активирует механизм Контрагентов: один и тот же клиент всегда платит на одни и те же реквизиты.
Как это работает
- Первая заявка с новым
customerId: система выбирает подходящий реквизит из пула VIP-доступных реквизитов и закрепляет его за этим клиентом.
- Все последующие заявки с тем же
customerId направляются строго на закреплённый реквизит. Клиент видит те же банковские реквизиты при каждой оплате — это повышает доверие и снижает риск отказа от платежа.
- Привязка постоянная, пока трейдер или администратор не отвяжет клиента от реквизита.
Пример запросач
const crypto = require('crypto');
// Функция для расчета подписи
function calculateSignature(method, url, body, secret) {
const stringToSign = method + url + (body || '');
const hmac = crypto.createHmac('sha256', secret);
hmac.update(stringToSign);
return hmac.digest('base64');
}
// Данные заявки
const method = 'POST';
const url = 'https://api.meridian.vip/api/v1/invoices';
const body = JSON.stringify({
internalId: 'order-12345',
direction: 'in',
amount: 1000,
currency: 'RUB',
startDeal: true,
paymentMethod: 'SBP',
paymentOption: 'sberbank',
notificationUrl: 'https://your-site.com/webhooks/meridian',
notificationToken: 'your-secret-webhook-token-min-32-chars',
customerId: 'user-7842' // опционально: VIP-привязка к одному реквизиту
});
// Ваш API ключ
const apiKey = 'luma_abc123...:luma_xyz789...';
const [keyId, secret] = apiKey.split(':');
const signature = calculateSignature(method, url, body, secret);
// Отправка запроса
const response = await fetch(url, {
method,
headers: {
'Content-Type': 'application/json',
'X-API-Key': apiKey,
'X-Signature': signature
},
body
});
const result = await response.json();
console.log(result);
Пример ответа (H2H интеграция)
HTTP Status: 200 OK
При создании заявки без redirectUrls — стандартный H2H-ответ с реквизитами:
{
"id": "cm3k8x7y80001z8j4k5m6n7o8",
"direction": "in",
"status": "new",
"paymentMethod": "SBP",
"paymentOption": "sberbank",
"amount": "1000",
"currency": "RUB",
"expireAt": "2025-11-03T15:10:00.000Z",
"requisiteId": "req_abc123xyz789",
"dealRequisites": "{\"bankName\":\"Sberbank\",\"cardNumber\":\"**** 1234\",\"fullName\":\"Ivan Ivanov\"}",
"dealRate": "95.50",
"createdAt": "2025-11-03T15:00:00.000Z",
"updatedAt": "2025-11-03T15:00:00.000Z",
"internalId": "order-12345",
"merchantName": "MerchantName",
"isVip": true,
"customerId": "user-7842"
}
Поля isVip и customerId присутствуют в ответе всегда, даже для обычных не-VIP заявок. В этом случае isVip: false и customerId: null.
Пример ответа (Redirect интеграция)
HTTP Status: 201 Created
При создании заявки с redirectUrls — ответ содержит paymentUrl для редиректа клиента на hosted-страницу оплаты:
{
"id": "cm3k8x7y80001z8j4k5m6n7o8",
"direction": "in",
"status": "new",
"amount": "1000",
"currency": "RUB",
"dealRate": "95.50",
"createdAt": "2025-11-03T15:00:00.000Z",
"updatedAt": "2025-11-03T15:00:00.000Z",
"internalId": "order-12345",
"merchantName": "MerchantName",
"paymentUrl": "https://luma-gate.com/pay/V1StGXR8_Z5jdHi6B-myT9a2xHplkR4w"
}
Примеры ошибок
Ошибка: Нет доступных реквизитов
HTTP Status: 503 Service Unavailable
Эта ошибка возникает когда все трейдеры с подходящими реквизитами заняты
{
"error": "Нет доступных реквизитов"
}
Поля ответа
| Поле | Тип | Описание |
|---|
id | string | Уникальный идентификатор заявки в системе Meridian. Используйте для проверки статуса через GET /api/v1/invoices/:id |
direction | string | Направление платежа: "in" (входящий) или "out" (исходящий) |
status | string | Текущий статус заявки. Для direction="in": "new" (создана, ожидает трейдера), "paid" (оплачена, средства распределены), "expired" (истек срок 10 мин), "canceled" (отменена), "dispute" (открыт спор). Следите за: new → processing → paid |
amount | string | Сумма заявки в указанной валюте (строка для точности) |
currency | string | Код валюты: "RUB", "USD", "EUR", "USDT" |
paymentMethod | string | Метод платежа: "SBP" или "TO_CARD" |
paymentOption | string | Выбранный банк для платежа (например, "sberbank", "tinkoff") |
requisiteId | string | ID назначенного реквизита (только если startDeal=true) |
dealRequisites | string | JSON-строка с реквизитами для оплаты (номер карты, счет, имя получателя). Важно: Передайте эту информацию клиенту для совершения платежа |
dealRate | string | Курс обмена USDT/RUB на момент создания заявки |
expireAt | string | Время истечения заявки ISO 8601. Для IN: истекает через 10 минут. После истечения средства автоматически размораживаются |
createdAt | string | Время создания заявки в формате ISO 8601 |
updatedAt | string | Время последнего обновления заявки в формате ISO 8601 |
internalId | string | Уникальный идентификатор заявки в вашей системе (тот же, что был передан при создании). Используйте для сопоставления с вашими внутренними записями |
merchantName | string | Отображаемое имя мерчанта (ваша организация) |
paymentUrl | string | URL hosted-страницы оплаты. Присутствует только при создании заявки с redirectUrls. Перенаправьте клиента на этот URL для оплаты |
isVip | boolean | Всегда присутствует. true, если заявка обработана через механизм VIP-привязки клиентов (был передан customerId и маршрутизация не PSP). false для всех остальных заявок |
customerId | string | null | Всегда присутствует. Содержит идентификатор клиента, переданный при создании заявки, либо null если поле не было передано |