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

Получить статус заказа можно двумя способами: через автоматические уведомления-webhook (рекомендуется) или ручной опрос API.

Webhook-уведомления (рекомендуется)

Это рекомендуемый способ интеграции. Webhook'и автоматически уведомляют ваш сервер о смене статуса заказа — опрос API вручную не нужен.

При смене статуса заказа мы отправим POST-запрос на ваш webhook-URL с данными заказа.

Настройка webhook'ов

Передайте URL вашего webhook'а менеджеру
Убедитесь, что ваш сервер принимает POST-запросы по этому URL
Обрабатывайте входящие уведомления и отвечайте кодом HTTP 200

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

Ваш сервер получит POST-запрос со следующим телом:

{
  "id": "a1b2c3d4-e5f6-7g8h-i9j0-k1l2m3n4o5p6",
  "status": "COMPLETED",
  "purpose": "Оплата заказа №1234",
  "amount": "1000.5",
  "commission": "1.5",
  "received": "999.0",
  "currency": "RUB",
  "paymentType": "SBP",
  "shopId": "a1b2c3d4-e5f6-7g8h-i9j0-k1l2m3n4o5p6",
  "terminalId": "a1b2c3d4-e5f6-7g8h-i9j0-k1l2m3n4o5p6",
  "merchantId": "a1b2c3d4-e5f6-7g8h-i9j0-k1l2m3n4o5p6",
  "externalId": "order_1234",
  "externalUserId": "user_987",
  "paymentLink": "https://example.com/payment?id=...",
  "successUrl": "https://example.com/success",
  "payedAt": "2023-03-21T12:34:56Z",
  "updatedAt": "2023-03-21T12:34:56Z",
  "createdAt": "2023-03-21T12:34:56Z"
}

Проверка подписи (X-Signature)

Для дополнительной безопасности каждый webhook-запрос содержит заголовок X-Signature — это HMAC SHA512 хэш в HEX-формате от тела запроса. Подпись формируется с использованием вашего API-ключа в качестве секретного ключа.

Пример проверки подписи

import crypto from "crypto";

const apiKey = "your_API_key";

app.post("/webhook/payments", (req, res) => {
  const signature = req.headers["x-signature"];
  const body = JSON.stringify(req.body);

  // Проверка подписи
  const hmac = crypto.createHmac("sha512", apiKey);
  hmac.update(body);
  const calculatedSignature = hmac.digest("hex");

  if (calculatedSignature !== signature) {
    console.error("❌ Невалидная подпись webhook'а!");
    return res.status(403).send("Invalid signature");
  }

  console.log("✅ Подпись валидна");

  // Обработка webhook'а
  const data = req.body;
  if (data.status === "COMPLETED") {
    console.log(`✅ Заказ ${data.externalId} оплачен!`);
  }

  res.status(200).send("OK");
});

Ручная проверка статуса

Чтобы получить текущий статус заказа, отправьте GET-запрос с авторизацией на:

/v1/orders/:id

где :id — это UUID заказа в нашей системе.

Перед тем как начать

Как авторизовывать запросы

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

curl -X GET "https://api.panel.valutix.kz/v1/orders/a1b2c3d4-e5f6-7g8h-i9j0-k1l2m3n4o5p6" \
-H "X-Api-Token: YOUR_API_TOKEN"

Пример успешного ответа

{
  "id": "a1b2c3d4-e5f6-7g8h-i9j0-k1l2m3n4o5p6",
  "status": "PENDING",
  "purpose": "Оплата заказа №1234",
  "amount": "1000.5",
  "commission": "1.5",
  "received": "999.0",
  "currency": "RUB",
  "paymentType": "SBP",
  "shopId": "a1b2c3d4-e5f6-7g8h-i9j0-k1l2m3n4o5p6",
  "terminalId": "a1b2c3d4-e5f6-7g8h-i9j0-k1l2m3n4o5p6",
  "merchantId": "a1b2c3d4-e5f6-7g8h-i9j0-k1l2m3n4o5p6",
  "externalId": "sesemasese3252362632",
  "externalUserId": "user15236236",
  "paymentLink": "https://example.com/index.php?route=extension/trip/payments/create?id=a1b2c3d4-e5f6-7g8h-i9j0-k1l2m3n4o5p6&amount=1000&hash=2792ob1jhvyif81bhcvfy8iwbhck",
  "successUrl": "https://example.com",
  "payedAt": "2023-03-21T12:34:56Z",
  "updatedAt": "2023-03-21T12:34:56Z",
  "createdAt": "2023-03-21T12:34:56Z"
}

Возможные значения статусов

Статус	Описание
CREATED	Заказ создан
PENDING	Ожидает оплаты
COMPLETED	Платёж успешно завершён
FAILED	Ошибка оплаты
CANCELED	Заказ отменён системой
EXPIRED	Срок действия заказа истёк

Некоторые поля в ответе могут быть null в зависимости от стадии обработки заказа. Всегда сверяйтесь с актуальной Swagger-документацией.