Трансграничные платежи

Создание платежа

POST https://api.meridian.vip/api/v1/transgran/payments

Обязательные параметры

Параметр	Тип	Описание
`amount`	`number`	Сумма платежа в рублях (не в копейках). Пример: `1000` = 1000 RUB
`currency`	`string`	Код валюты. Только `"RUB"`
`bank`	`number`	Предпочтительный банк клиента. Система подберет реквизиты с учетом этого предпочтения. Оплата может быть произведена с любого банка. См. Коды банков
`internalId`	`string`	Уникальный идентификатор заказа в вашей системе для идемпотентности
`customerEmail`	`string`	Email клиента (требуется для Трансгран)
`notificationUrl`	`string`	URL для webhook уведомлений по этому платежу
`notificationToken`	`string`	Секретный токен для подписи webhook уведомлений , минимальная длина 32 символа

Коды банков

Код	Банк
`1`	VTB
`2`	Sberbank
`3`	Gazprombank
`4`	T-Bank
`5`	Solidarnost

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

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/transgran/payments';
const body = JSON.stringify({
  amount: 1000,
  currency: 'RUB',
  bank: 2, // Sberbank
  internalId: 'order-12345',
  customerEmail: '[email protected]',
  notificationUrl: 'https://your-site.com/webhooks/transgran',
  notificationToken: 'your-webhook-secret-token'
});

const apiKey = 'meridian_abc123...:meridian_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);

Пример ответа (успех)

HTTP Status: 200 OK

{
  "id": "cm3k8x7y80001z8j4k5m6n7o8",
  "status": "new",
  "bankName": "sberbank",
  "amount": "1000",
  "currency": "RUB",
  "expireAt": "2025-11-03T15:10:00.000Z",
  "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",
  "clientEmail": "[email protected]"
}

Поля ответа

Поле	Тип	Описание
`id`	`string`	Уникальный идентификатор платежа в системе Meridian
`status`	`string`	Статус: `new`, `paid`, `expired`, `canceled`
`bankName`	`string`	Запрошенный банк из параметра `bank` (sberbank, vtb, tbank, gazprombank, solidarnost). Не является банком назначения — см. `dealRequisites`
`amount`	`string`	Сумма платежа
`currency`	`string`	Валюта (`RUB`)
`expireAt`	`string`	Время истечения блокировки реквизита. ISO 8601
`dealRequisites`	`string`	JSON-строка с реквизитами для оплаты. Это фактический банк назначения. См. Структура dealRequisites
`dealRate`	`string`	Курс сделки
`createdAt`	`string`	Время создания платежа. ISO 8601
`updatedAt`	`string`	Время последнего обновления. ISO 8601
`internalId`	`string`	Ваш идентификатор заказа
`merchantName`	`string`	Название мерчанта
`clientEmail`	`string`	Email клиента

Структура dealRequisites

Поле dealRequisites содержит JSON-строку с реквизитами, куда клиент должен отправить платеж.

Важно: Поле bankName в ответе — это запрошенный российский банк. Фактический банк назначения находится в dealRequisites.bankName и является одним из узбекских банков-партнеров.

Поля объекта

Поле	Тип	Описание
`bankName`	`string`	Банк назначения: `poytaxt_bank`, `garant_bank` или `asia_alliance`
`cardNumber`	`string`	Номер карты
`phoneNumber`	`string`	Номер телефона
`fullName`	`string`	ФИО получателя

Пример парсинга

const payment = await response.json();
const requisites = JSON.parse(payment.dealRequisites);

// bankName в ответе = "sberbank" (запрошенный банк)
// requisites.bankName = "garant_bank" (фактический банк назначения)

console.log('Банк назначения:', requisites.bankName);  // "garant_bank"
console.log('Номер карты:', requisites.cardNumber);     // "1234 5678 8765 4321"
console.log('Получатель:', requisites.fullName);        // "Ivan Ivanov"

Ошибки создания платежа

При создании платежа могут возникнуть следующие ошибки:

HTTP код	Сообщение	Описание
`400`	`Сумма X RUB выходит за пределы лимитов мерчанта`	Сумма платежа выходит за установленные лимиты мерчанта. Обратитесь к администратору для уточнения лимитов
`400`	`amount must be a positive number`	Сумма должна быть положительным числом
`400`	`currency must be RUB`	Валюта должна быть RUB
`400`	`bank must be 1, 2, 3, 4, or 5`	Неверный код банка
`400`	`internalId is required`	Не указан идентификатор заказа
`400`	`customerEmail must be a valid email`	Неверный формат email
`400`	`notificationUrl must be a valid URL`	Неверный URL для webhook
`400`	`Transgran service not configured`	Сервис временно недоступен
`400`	`No requisites in response`	Нет доступных реквизитов для выбранного банка. Попробуйте другой банк
`403`	`API key authentication required`	Требуется API-ключ аутентификации

Пример ответа с ошибкой

HTTP Status: 400 Bad Request

{
  "error": "Сумма 50000 RUB выходит за пределы лимитов мерчанта"
}

Проверка статуса

Endpoint для проверки статуса платежа:

GET https://api.meridian.vip/api/v1/transgran/payments/:id

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

const method = 'GET';
const paymentId = 'cm3k8x7y80001z8j4k5m6n7o8';
const url = `https://api.meridian.vip/api/v1/transgran/payments/${paymentId}`;

const signature = calculateSignature(method, url, '', secret);

const response = await fetch(url, {
  method,
  headers: {
    'X-API-Key': apiKey,
    'X-Signature': signature
  }
});

const payment = await response.json();
console.log('Status:', payment.status);

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

{
  "id": "cm3k8x7y80001z8j4k5m6n7o8",
  "status": "paid",
  "bankName": "sberbank",
  "amount": "1000",
  "currency": "RUB",
  "expireAt": "2025-11-03T15:10:00.000Z",
  "dealRequisites": "{\"bankName\":\"garant_bank\",\"cardNumber\":\"**** 1234\",\"fullName\":\"Ivan Ivanov\"}",
  "dealRate": "95.50",
  "createdAt": "2025-11-03T15:00:00.000Z",
  "updatedAt": "2025-11-03T15:05:00.000Z",
  "internalId": "order-12345",
  "merchantName": "MerchantName",
  "clientEmail": "[email protected]"
}

Webhook-уведомления

При изменении статуса платежа или разрешении апелляции система отправляет webhook на указанный notificationUrl.

HTTP запрос

POST {notificationUrl}
Content-Type: application/json
X-Webhook-Signature: {hmac_sha256_signature}
X-Webhook-Event: {event_type}
X-Webhook-Delivery-Id: {unique_delivery_id}

Формат тела webhook

{
  "id": "cm3k8x7y80001z8j4k5m6n7o8",
  "status": "paid",
  "bankName": "sberbank",
  "amount": "1000",
  "currency": "RUB",
  "expireAt": "2025-11-03T15:10:00.000Z",
  "dealRequisites": "{\"bankName\":\"garant_bank\",\"cardNumber\":\"**** 1234\",\"fullName\":\"Ivan Ivanov\"}",
  "dealRate": "95.50",
  "createdAt": "2025-11-03T15:00:00.000Z",
  "updatedAt": "2025-11-03T15:05:00.000Z",
  "internalId": "order-12345",
  "merchantName": "MerchantName",
  "clientEmail": "[email protected]"
}

Поля webhook

Поле	Тип	Описание
`id`	`string`	ID платежа в Meridian
`status`	`string`	Новый статус платежа
`bankName`	`string`	Запрошенный российский банк (не банк назначения)
`amount`	`string`	Сумма платежа
`currency`	`string`	Валюта
`expireAt`	`string`	Время истечения. ISO 8601
`dealRequisites`	`string`	JSON-строка с реквизитами. См. Структура dealRequisites
`dealRate`	`string`	Курс сделки
`createdAt`	`string`	Время создания платежа
`updatedAt`	`string`	Время последнего обновления
`internalId`	`string`	Ваш идентификатор заказа
`merchantName`	`string`	Название мерчанта
`clientEmail`	`string`	Email клиента

Верификация подписи

Webhook подписывается HMAC-SHA256. Используйте ваш notificationToken для верификации:

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  hmac.update(payload);
  const expectedSignature = hmac.digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature, 'hex'),
    Buffer.from(expectedSignature, 'hex')
  );
}

Создание апелляции

Если автоматическая привязка платежа не сработала (клиент оплатил, но статус не изменился), создайте апелляцию для ручной проверки.

Когда создавать апелляцию: Клиент утверждает, что оплатил, но платеж остается в статусе new или expired.

Важно: После создания апелляции платеж переходит в статус dispute, и все средства замораживаются.

Endpoint

POST https://api.meridian.vip/api/v1/transgran/payments/:id/disputes

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

URL параметры

Параметр	Тип	Обязательный	Описание
`id`	`string`	Да	Уникальный идентификатор платежа. Пример: `cm3k8x7y80001z8j4k5m6n7o8`

Тело запроса (multipart/form-data)

Параметр	Тип	Обязательный	Описание
`reason`	`string`	Да	Причина спора. См. допустимые значения ниже
`description`	`string`	Нет	Подробное описание проблемы (макс. 5000 символов)
`disputeReasonData`	`string`	Нет	JSON-строка. Обязательно для `reason="invalid_sum"`: `{"amount": number}`
`attachment`	`file`	Нет	Файл-доказательство (скриншот, чек). Макс. 10 МБ. Форматы: JPG, PNG, PDF

Допустимые значения reason:

Значение	Описание	Ограничения
`invalid_sum`	Неверная сумма платежа	Требует `disputeReasonData.amount` (фактическая сумма)
`has_payment`	Платеж был совершен, но не засчитан	-
`invalid_requisites`	Некорректные реквизиты	-
`unknown`	Неясная причина спора	-

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

METHOD="POST"
PAYMENT_ID="cm3k8x7y80001z8j4k5m6n7o8"
URL="https://api.meridian.vip/api/v1/transgran/payments/${PAYMENT_ID}/disputes"

JSON_DATA='{"reason":"invalid_sum","description":"Клиент отправил 500 RUB","disputeReasonData":{"amount":500}}'
SIGNATURE=$(echo -n "${METHOD}${URL}${JSON_DATA}" | openssl dgst -sha256 -hmac "$API_SECRET" -binary | base64)

curl -X POST "${URL}" \
  -H "X-API-Key: ${API_KEY}" \
  -H "X-Signature: ${SIGNATURE}" \
  -F "reason=invalid_sum" \
  -F "description=Клиент отправил 500 RUB вместо 1000 RUB" \
  -F 'disputeReasonData={"amount":500}' \
  -F "attachment=@/path/to/screenshot.jpg"

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

HTTP Status: 201 Created

{
  "id": "disp_abc123xyz789",
  "paymentId": "cm3k8x7y80001z8j4k5m6n7o8",
  "reason": "invalid_sum",
  "description": "Клиент отправил 500 RUB вместо 1000 RUB",
  "disputeReasonData": {
    "amount": 500
  },
  "attachmentUrl": "https://meridian-disputes.s3.amazonaws.com/disp_abc123xyz789/screenshot.jpg",
  "attachmentFilename": "screenshot.jpg",
  "status": "open",
  "resolution": null,
  "resolutionNotes": null,
  "createdAt": "2025-11-03T15:10:00.000Z",
  "resolvedAt": null,
  "autoResolveAt": "2025-11-03T16:10:00.000Z",
  "amount": "1000",
  "currency": "RUB",
  "bankName": "sberbank",
  "dealRequisites": "{\"bankName\":\"garant_bank\",\"cardNumber\":\"**** 1234\",\"fullName\":\"Ivan Ivanov\"}",
  "internalId": "order-12345",
  "merchantName": "MerchantName",
  "clientEmail": "[email protected]"
}

Поля ответа апелляции

Поле	Тип	Описание
`id`	`string`	Уникальный идентификатор апелляции
`paymentId`	`string`	ID платежа, по которому создана апелляция
`reason`	`string`	Причина спора: `invalid_sum`, `has_payment`, `invalid_requisites`, `unknown`
`description`	`string \| null`	Описание проблемы
`disputeReasonData`	`object \| null`	Дополнительные данные. Для `invalid_sum` содержит `{"amount": number}`
`attachmentUrl`	`string \| null`	URL файла-доказательства (7 дней)
`attachmentFilename`	`string \| null`	Имя загруженного файла
`status`	`string`	`open` (ожидает рассмотрения) или `closed` (разрешен)
`resolution`	`string \| null`	Решение: `merchant_win`, `trader_win` или `null`
`resolutionNotes`	`string \| null`	Комментарий администратора
`createdAt`	`string`	Время создания. ISO 8601
`resolvedAt`	`string \| null`	Время разрешения. ISO 8601
`autoResolveAt`	`string \| null`	Время автоматического разрешения. ISO 8601
`amount`	`string`	Сумма платежа
`currency`	`string`	Валюта (`RUB`)
`bankName`	`string`	Запрошенный российский банк (не банк назначения)
`dealRequisites`	`string`	JSON-строка с реквизитами. См. Структура dealRequisites
`internalId`	`string \| null`	Ваш идентификатор заказа
`merchantName`	`string \| null`	Название мерчанта
`clientEmail`	`string \| null`	Email клиента

Автоматическое разрешение

Важно: Если апелляция не будет разрешена в течение 60 минут, система автоматически разрешит её в пользу мерчанта (merchant_win).

Проверка статуса апелляции

GET https://api.meridian.vip/api/v1/transgran/disputes/:id

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

const method = 'GET';
const disputeId = 'disp_abc123xyz789';
const url = `https://api.meridian.vip/api/v1/transgran/disputes/${disputeId}`;

const signature = calculateSignature(method, url, '', secret);

const response = await fetch(url, {
  method,
  headers: {
    'X-API-Key': apiKey,
    'X-Signature': signature
  }
});

const dispute = await response.json();
console.log('Status:', dispute.status);
console.log('Resolution:', dispute.resolution);

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

{
  "id": "disp_abc123xyz789",
  "paymentId": "cm3k8x7y80001z8j4k5m6n7o8",
  "reason": "invalid_sum",
  "description": "Клиент отправил 500 RUB вместо 1000 RUB",
  "disputeReasonData": {
    "amount": 500
  },
  "attachmentUrl": "https://meridian-disputes.s3.amazonaws.com/disp_abc123xyz789/screenshot.jpg",
  "attachmentFilename": "screenshot.jpg",
  "status": "closed",
  "resolution": "merchant_win",
  "resolutionNotes": "Платеж подтвержден на сумму 500 RUB",
  "createdAt": "2025-11-03T15:10:00.000Z",
  "resolvedAt": "2025-11-03T15:30:00.000Z",
  "autoResolveAt": "2025-11-03T16:10:00.000Z",
  "amount": "1000",
  "currency": "RUB",
  "bankName": "sberbank",
  "dealRequisites": "{\"bankName\":\"garant_bank\",\"cardNumber\":\"**** 1234\",\"fullName\":\"Ivan Ivanov\"}",
  "internalId": "order-12345",
  "merchantName": "MerchantName",
  "clientEmail": "[email protected]"
}

Начало работы

API

​Создание платежа

​Обязательные параметры

​Коды банков

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

​Пример ответа (успех)

​Поля ответа

​Структура dealRequisites

​Поля объекта

​Пример парсинга

​Ошибки создания платежа

​Пример ответа с ошибкой

​Проверка статуса

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

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

​Webhook-уведомления

​HTTP запрос

​Формат тела webhook

​Поля webhook

​Верификация подписи

​Создание апелляции

​Endpoint

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

​URL параметры

​Тело запроса (multipart/form-data)

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

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

​Поля ответа апелляции

​Автоматическое разрешение

​Проверка статуса апелляции

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

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

Создание платежа

Обязательные параметры

Коды банков

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

Пример ответа (успех)

Поля ответа

Структура dealRequisites

Поля объекта

Пример парсинга

Ошибки создания платежа

Пример ответа с ошибкой

Проверка статуса

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

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

Webhook-уведомления

HTTP запрос

Формат тела webhook

Поля webhook

Верификация подписи

Создание апелляции

Endpoint

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

URL параметры

Тело запроса (multipart/form-data)

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

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

Поля ответа апелляции

Автоматическое разрешение

Проверка статуса апелляции

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

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