Skip to main content

​
Обзор

Аппеляции (споры) позволяют мерчантам оспаривать платежные заявки при возникновении проблем с оплатой. При создании аппеляции средства автоматически замораживаются до разрешения спора.
Важно: После создания аппеляции заявка переходит в статус dispute, и все средства замораживаются.

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

Endpoint для создания спора по существующей заявке: 
POST https://api.meridian.vip/api/v1/invoices/:invoiceId/disputes

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

​
URL параметры

ПараметрТипОбязательныйОписание
invoiceIdstring✓Уникальный идентификатор заявки. Пример: cm3k8x7y80001z8j4k5m6n7o8

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

ПараметрТипОбязательныйОписание
reasonstring✓Причина спора. См. допустимые значения ниже
descriptionstring-Подробное описание проблемы (макс. 5000 символов)
disputeReasonDatastring-JSON-строка. Обязательно для reason="invalid_sum": {"amount": number}
attachmentfile-Файл-доказательство (скриншот, чек). Макс. 10 МБ. Форматы: JPG, PNG, PDF
Допустимые значения reason:
ЗначениеОписаниеОграничения
invalid_sumНеверная сумма платежаТребует disputeReasonData.amount (фактическая сумма)
has_paymentПлатеж был совершен, но не засчитан-
invalid_requisitesНекорректные реквизиты-
unknownНеясная причина спора-

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

METHOD="POST"
URL="https://api.meridian.vip/api/v1/invoices/cm3k8x7y80001z8j4k5m6n7o8/disputes"

# Для multipart подпись вычисляется от JSON-части
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)

# Отправляем multipart запрос (с файлом или без)
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"

# Без файла: просто уберите строку с attachment

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

{
    "id": "disp_abc123xyz789",
    "invoiceId": "cm3k8x7y80001z8j4k5m6n7o8",
    "reason": "invalid_sum",
    "description": "Клиент отправил 500 RUB вместо 1000 RUB",
    "disputeReasonData": {
        "amount": 500
    },
    "attachmentUrl": "https://lumapay-disputes.s3.amazonaws.com/disp_abc123xyz789/screenshot.jpg",
    "attachmentFilename": "screenshot.jpg",
    "status": "open",
    "resolution": null,
    "resolutionNotes": null,
    "createdAt": "2025-11-03T15:10:00+03:00",
    "resolvedAt": null,
    "autoResolveAt": "2025-11-03T16:10:00+03:00",
    "amount": "1000.0000",
    "currency": "RUB",
    "paymentMethod": "SBP",
    "paymentOption": "sberbank",
    "requisites": {
        "bankName": "sberbank",
        "phoneNumber": "79099966512",
        "fullName": "Ivan Ivanov"
    },
    "internalId": "order-12345",
    "merchantName": "MerchantName"
}

​
Поля ответа

​
Объект dispute

ПолеТипОписание
idstringУникальный идентификатор спора
invoiceIdstringID заявки, по которой создан спор
reasonstringПричина спора: invalid_sum, has_payment, invalid_requisites, unknown
descriptionstring | nullОписание проблемы
disputeReasonDataobject | nullДополнительные данные о причине спора. Для invalid_sum содержит {"amount": number} - фактически полученную сумму
attachmentUrlstring | nullPresigned URL файла-доказательства (S3) с 7-дневным сроком действия, если был загружен
attachmentFilenamestring | nullИмя загруженного файла
statusstringopen (ожидает рассмотрения) или closed (разрешен)
resolutionstring | nullРешение: merchant_win, trader_win или null (не разрешен)
resolutionNotesstring | nullКомментарий администратора
traderReportedAmountnumber | nullСумма, указанная трейдером (только для invalid_sum споров)
traderRespondedAtstring | nullВремя ответа трейдера (ISO 8601)
createdAtstringВремя создания в часовом поясе Москвы (UTC+3)
updatedAtstringВремя последнего обновления в часовом поясе Москвы (UTC+3)
resolvedAtstring | nullВремя разрешения в часовом поясе Москвы (UTC+3)
resolvedBystring | nullID администратора, разрешившего спор
autoResolveAtstring | nullВремя автоматического разрешения в часовом поясе Москвы (UTC+3)
reopenedByAdminIdstring | nullID администратора, переоткрывшего спор
reopenedAtstring | nullВремя переоткрытия спора
originalResolutionstring | nullИсходное решение до переоткрытия
reopenReasonstring | nullПричина переоткрытия спора
amountstringСумма заявки в валюте (из связанной заявки)
currencystringВалюта заявки (обычно RUB)
paymentMethodstring | nullМетод платежа заявки (SBP, TO_CARD)
paymentOptionstring | nullБанк для платежа (sberbank, tinkoff, и т.д.)
requisitesobject | nullОбъект с реквизитами для оплаты/получения платежа. Для входящих заявок содержит реквизиты трейдера, для исходящих - реквизиты получателя. Поля для СБП: bankName (string), fullName (string), phoneNumber (string). Для карт: cardNumber (string), fullName (string)
internalIdstring | nullУникальный идентификатор заявки в вашей системе (если был указан при создании). Используйте для сопоставления с вашими внутренними записями
merchantNamestring | nullОтображаемое имя мерчанта (ваша организация)

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

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

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

После создания спора вы можете проверить его статус через webhook уведомления или через GET endpoint: 
GET https://api.meridian.vip/api/v1/disputes/:disputeId
Пример запроса: 
const method = 'GET';
const disputeId = 'disp_abc123xyz789';
const url = `https://api.meridian.vip/api/v1/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",
  "invoiceId": "cm3k8x7y80001z8j4k5m6n7o8",
  "reason": "invalid_sum",
  "description": "Клиент отправил 500 RUB вместо 1000 RUB",
  "disputeReasonData": {
    "amount": 500
  },
  "attachmentUrl": "https://meridian-disputes.storage.com/disp_abc123xyz789/screenshot.jpg",
  "attachmentFilename": "screenshot.jpg",
  "status": "open",
  "resolution": null,
  "resolutionNotes": null,
  "createdAt": "2025-11-03T15:10:00+03:00",
  "resolvedAt": null,
  "autoResolveAt": "2025-11-03T16:10:00+03:00",
  "amount": "1000.0000",
  "currency": "RUB",
  "paymentMethod": "SBP",
  "paymentOption": "sberbank",
  "requisites": {
    "bankName": "sberbank",
    "phoneNumber": "79099966512",
    "fullName": "Ivan Ivanov"
  },
  "internalId": "order-12345",
  "merchantName": "MerchantName"
}