> ## Documentation Index
> Fetch the complete documentation index at: https://docs.meridian.vip/llms.txt
> Use this file to discover all available pages before exploring further.
# Создание заявок на прием
> Создание заявок на прием платежей от клиентов через Meridian API
## Создание заявки
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` при создании заявки активирует механизм **Контрагентов**: один и тот же клиент всегда платит на одни и те же реквизиты.
### Как это работает
1. **Первая заявка** с новым `customerId`: система выбирает подходящий реквизит из пула VIP-доступных реквизитов и **закрепляет** его за этим клиентом.
2. **Все последующие заявки** с тем же `customerId` направляются строго на закреплённый реквизит. Клиент видит те же банковские реквизиты при каждой оплате — это повышает доверие и снижает риск отказа от платежа.
3. Привязка постоянная, пока трейдер или администратор не отвяжет клиента от реквизита.
***
## Пример запросач
```javascript Node.js theme={null}
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);
```
```python Python theme={null}
import hmac
import hashlib
import base64
import requests
import json
# Функция для расчета подписи
def calculate_signature(method, url, body, secret):
string_to_sign = method + url + (body or '')
signature = hmac.new(
secret.encode('utf-8'),
string_to_sign.encode('utf-8'),
hashlib.sha256
).digest()
return base64.b64encode(signature).decode('utf-8')
# Данные заявки
method = 'POST'
url = 'https://api.meridian.vip/api/v1/invoices'
body = json.dumps({
'internalId': 'order-12345',
'direction': 'in',
'amount': 1000, # 1000 RUB (в рублях, НЕ в копейках)
'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 ключ
api_key = 'luma_abc123...:luma_xyz789...'
key_id, secret = api_key.split(':')
signature = calculate_signature(method, url, body, secret)
# Отправка запроса
response = requests.post(
url,
headers={
'Content-Type': 'application/json',
'X-API-Key': api_key,
'X-Signature': signature
},
data=body
)
result = response.json()
print(result)
```
```php PHP theme={null}
'order-12345',
'direction' => 'in',
'amount' => 1000, // 1000 RUB (в рублях, НЕ в копейках)
'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 ключ
$apiKey = 'luma_abc123...:luma_xyz789...';
list($keyId, $secret) = explode(':', $apiKey);
$signature = calculateSignature($method, $url, $body, $secret);
// Отправка запроса
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $body);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Content-Type: application/json',
'X-API-Key: ' . $apiKey,
'X-Signature: ' . $signature
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
$result = json_decode($response, true);
print_r($result);
?>
```
***
## Пример ответа (H2H интеграция)
**HTTP Status: 200 OK**
При создании заявки **без** `redirectUrls` — стандартный H2H-ответ с реквизитами:
```json theme={null}
{
"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-страницу оплаты:
```json theme={null}
{
"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**
Эта ошибка возникает когда все трейдеры с подходящими реквизитами заняты
```json theme={null}
{
"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` если поле не было передано |
***