Завершение платежного ордера

Описание

Endpoint используется для финализации платежного ордера и обработки платежа.

При успешном завершении:

• Статус ордера изменяется на завершённый

• Баланс пользователя пополняется согласно сумме платежа

• Операция логируется в систему

Вы можете использовать данный endpoint для обработки вебхуков и колбеков от платежных шлюзов.

---

Endpoint

POST https://api.mmoweb.biz/v2/payment/order/complete

Content-Type: application/json

---

Параметры

Все параметры передаются в JSON теле запроса.

Параметр	Тип	Обязателен	Формат	Описание
payment_system	string	Да	cstm:[a-z]{4,20}	Идентификатор платежной системы (например: cstm:yandex, cstm:paypal)
order_id	string	Да	Order:[A-Za-z0-9]{8,11}	Уникальный идентификатор ордера, выданный при создании
payment_id	string	Нет	Строчное значение	ID платежа в платежной системе (используется для отслеживания)

Форматы параметров:

• payment_system: начинается с cstm:, за которым следуют 4-20 строчных букв (пример: cstm:stripe, cstm:cryptobox)

• order_id: начинается с Order:, за которым следуют 8-11 буквенно-цифровых символов (пример: Order:abc12345)

---

Примеры

Базовое завершение платежа

cURL

curl -X POST "https://api.mmoweb.biz/v2/payment/order/complete" \
  -H "Authorization: Bearer APPLICATION_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_system": "cstm:yandex",
    "order_id": "Order:abc12345",
    "payment_id": "yandex_payment_123456"
  }'

JavaScript

const token = 'APPLICATION_TOKEN_HERE';

const payload = {
  payment_system: 'cstm:yandex',
  order_id: 'Order:abc12345',
  payment_id: 'yandex_payment_123456'
};

fetch('https://api.mmoweb.biz/v2/payment/order/complete', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(payload)
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));

PHP

<?php
$token = 'APPLICATION_TOKEN_HERE';
$url = 'https://api.mmoweb.biz/v2/payment/order/complete';

$payload = [
  'payment_system' => 'cstm:yandex',
  'order_id' => 'Order:abc12345',
  'payment_id' => 'yandex_payment_123456'
];

$ch = curl_init($url);
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_POSTFIELDS => json_encode($payload),
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer ' . $token,
    'Content-Type: application/json'
  ]
]);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

$data = json_decode($response, true);

echo "HTTP Status: " . $httpCode . "\n";
echo json_encode($data, JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE);
?>

Завершение платежа без payment_id

cURL

curl -X POST "https://api.mmoweb.biz/v2/payment/order/complete" \
  -H "Authorization: Bearer APPLICATION_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_system": "cstm:paypal",
    "order_id": "Order:xyz98765"
  }'

JavaScript

const token = 'APPLICATION_TOKEN_HERE';

const payload = {
  payment_system: 'cstm:paypal',
  order_id: 'Order:xyz98765'
};

fetch('https://api.mmoweb.biz/v2/payment/order/complete', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(payload)
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));

PHP

<?php
$token = 'APPLICATION_TOKEN_HERE';
$url = 'https://api.mmoweb.biz/v2/payment/order/complete';

$payload = [
  'payment_system' => 'cstm:paypal',
  'order_id' => 'Order:xyz98765'
];

$ch = curl_init($url);
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_POSTFIELDS => json_encode($payload),
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer ' . $token,
    'Content-Type: application/json'
  ]
]);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

$data = json_decode($response, true);

echo "HTTP Status: " . $httpCode . "\n";
echo json_encode($data, JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE);
?>

---

Ответы

Успешное завершение (200 OK)

{
  "success": true,
  "code": "PAYMENT_PROCESSED",
  "message": "Payment processed successfully",
  "order": {
    "id": 12345,
    "mid": 789,
    "sid": 2,
    "pid": 1,
    "team": 1,
    "order_id": "Order:abc12345",
    "payment_system": "cstm:yandex",
    "amount": "500.00",
    "currency": "RUB",
    "status": 1,
    "date_create": "2026-08-05 10:30:00",
    "date_complete": "2026-08-05 10:32:15",
    "payment_id": "yandex_payment_123456",
    "custom_data": null
  }
}

Ошибка валидации параметров (400 Bad Request)

{
  "success": false,
  "code": "VALIDATION_ERROR",
  "message": {
    "payment_system": "payment_system field must match the regex pattern cstm:[a-z]{4,20}",
    "order_id": "order_id field must match the regex pattern Order:[A-Za-z0-9]{8,11}"
  }
}

Ордер не найден (404 Not Found)

{
  "success": false,
  "code": "ORDER_NOT_FOUND",
  "message": "Order not found"
}

Когда встречается: ордер не существует, не принадлежит текущему проекту/команде или платежная система не совпадает

Ордер уже завершен (409 Conflict)

{
  "success": false,
  "code": "ORDER_ALREADY_COMPLETED",
  "message": "Order has already been completed"
}

Ошибка обновления статуса (500 Internal Server Error)

{
  "success": false,
  "code": "ORDER_UPDATE_FAILED",
  "message": "Failed to update order status"
}

Ошибка при обработке платежа (зависит от конкретной ошибки)

{
  "success": false,
  "code": "PAYMENT_PROCESSING_ERROR",
  "message": "An error occurred while processing the payment"
}

---

Коды ошибок

Код	HTTP Status	Описание	Что делать
VALIDATION_ERROR	400	Один или несколько параметров не соответствуют формату	Проверьте формат payment_system и order_id согласно спецификации
ORDER_NOT_FOUND	404	Ордер не существует, не принадлежит проекту или платежная система не совпадает	Убедитесь что используете правильный order_id и payment_system
ORDER_ALREADY_COMPLETED	409	Этот ордер уже был завершен	Дублированная обработка вебхука; это нормально — повторно завершение не требуется
ORDER_UPDATE_FAILED	500	Ошибка при обновлении статуса в БД	Повторите попытку позже; если ошибка повторяется, свяжитесь с поддержкой
PAYMENT_PROCESSING_ERROR	Переменный	Ошибка при обработке платежа в системе	Проверьте логи; платеж может быть обработан, но сообщение не отправлено

---

Поток обработки платежа

1. Получение вебхука — платежная система отправляет колбек на ваш сервер

2. Вызов API — ваш сервер вызывает этот endpoint с данными платежа

3. Валидация — проверяется формат параметров и существование ордера

4. Обновление статуса — статус ордера изменяется на завершённый

5. Обработка платежа — платеж обрабатывается (зачисление на баланс и т.д.)

6. Логирование — операция записывается в логи для аудита

7. Ответ — возвращается результат обработки

---

Важные особенности

Идемпотентность

Если ордер уже завершен, endpoint вернет ошибку ORDER_ALREADY_COMPLETED (409). Это нормальное поведение и означает, что платеж уже был обработан. Не пересылайте запрос повторно.

Совпадение платежной системы

Параметр payment_system в запросе должен совпадать с платежной системой, которая была указана при создании ордера. Если системы не совпадают, ордер не будет найден.

Payment ID (опционально)

Параметр payment_id не обязателен, но рекомендуется передавать ID платежа из платежной системы для отслеживания и согласования.

Время обработки

После завершения ордера баланс пользователя пополняется немедленно. Убедитесь, что платеж действительно прошел в платежной системе перед вызовом этого endpoint'а.

---

Рекомендации

Безопасность:

• Проверяйте подпись вебхука от платежной системы перед вызовом API

• Убедитесь что payment_system соответствует вашей конфигурации

• Используйте HTTPS для всех запросов

Надёжность:

• Реализуйте retry logic с экспоненциальной задержкой при ошибках 5xx

• Сохраняйте полные логи всех вебхуков для отладки

• Обрабатывайте ответ ORDER_ALREADY_COMPLETED как успех (платеж уже обработан)

Интеграция:

• Тестируйте с тестовыми платежами перед запуском в production

• Проверяйте что все параметры имеют правильный формат

• Убедитесь что токен приложения имеет необходимые разрешения