API Документація

Документація зовнішнього API для інтеграції з платформою Karbovanets.

Автентифікація

Всі API ендпоінти вимагають автентифікації одним із наступних методів:

API Ключ (Рекомендовано для інтеграцій)

X-API-Key: krb_aBcDeFgHiJkLmNoPqRsTuVwXyZ123456789012345678

Bearer Token

Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...

Коди помилок

Інформація про користувача

Відповідь

{
  "data": {
    "type": "users",
    "id": "GApnxJlkaIVC92d4o44n6",
    "attributes": {
      "email": "[email protected]",
      "balance": {
        "value": "1500.00000000",
        "precision": 8
      },
      "language": "uk",
      "created_at": "2024-01-15 10:30:00",
      "updated_at": "2024-03-18 14:20:00"
    }
  }
}

Мова інтерфейсу користувача

Тіло запиту

{
  "data": {
    "type": "language",
    "attributes": {
      "code": "uk"
    }
  }
}

Відповідь

204 No Content у разі успіху. 422 Unprocessable Entity — якщо код мови невідомий або мова не активна.

API Ключі

Відповідь (201 Created)

{
  "data": {
    "type": "api_keys",
    "id": "xK9mNpQrStUvWxYz12345",
    "attributes": {
      "key": "krb_aBcDeFgHiJkLmNoPqRsTuVwXyZ123456789012345678",
      "callback_signing_key": "aBcD1234eFgH5678iJkL9012mNoP3456qRsT7890uVwX1234yZ56",
      "created_at": "2024-03-18T10:00:00Z"
    }
  }
}

Поля відповіді

Обрані валюти

Параметри запиту

Замовлення

Параметри запиту

Статуси замовлень

Тіло запиту

{
  "data": {
    "type": "create_order_request",
    "attributes": {
      "payout_type": 1,
      "to_amount": "1000",
      "to_currency": "P24UAH",
      "custom_fields": {
        "unq_identifier_37": "4149123456789012"
      },
      "callback_url": "https://your-site.com/webhook/order"
    }
  }
}

Поля запиту

Варіанти payout_type

Депозити

Статуси депозитів

Тіло запиту

{
  "data": {
    "type": "create_deposit_request",
    "attributes": {
      "amount": 500.00
    }
  }
}

Виплати (API-source)

Тіло запиту

{
  "data": {
    "type": "create_payout_request",
    "attributes": {
      "to_currency": "P24UAH",
      "to_amount": "1500.00",
      "fields": {
        "card": "4242424242424242",
        "fio": "Ivanov Ivan",
        "iban": "UA00..."
      },
      "callback_url": "https://exchanger.example.com/webhook/auto-withdraws-integrations/karbovanets_uah/abc123",
      "external_id": "abc123"
    }
  }
}

Поля запиту

Теги полів

Ключі в fields — це теги custom-полів. Сервіс зіставляє тег із конкретним custom-полем валюти й валідатором (тип, мін/макс довжина тощо). Якщо тег не пов'язаний з жодним полем валюти — він ігнорується; якщо обов'язкове поле відсутнє — повертається 422 з тегом у field.

Приблизні назви — будуть уточнені.

Відповідь (201 Created)

{
  "data": {
    "type": "orders",
    "id": "<order_uid>",
    "attributes": { "status": "PAID", "hash": "...", "...": "..." }
  }
}

Помилки

Зворотний вебхук

Після створення виплати система оновлює статус ордера у фоні. Тільки на термінальних статусах (COMPLETED, ERROR, CANCELLED, DELETED) ми відправляємо POST на ваш callback_url. Тіло запиту підписане HMAC-SHA512 від base64(utf8_encode(raw_body)) із вашим callback_signing_key (отриманим при створенні API-ключа). Підпис у заголовку PAYLOAD-WITH-SIGNATURE.

POST {callback_url}
Content-Type: application/json
PAYLOAD-WITH-SIGNATURE: <hmac-sha512>

{
  "status": 3,
  "card_number": "4242...",
  "amount_to_pay": "1500.00",
  "amount_paid": "1500.00",
  "payment_id": 12345,
  "operator_email": null
}

Ретраї доставки

Будь-яка відповідь, яка не 2xx (включно з 4xx: 401, 403, 404, 429 тощо), а також помилки рівня з'єднання (DNS, timeout) — вважаються транзитними. Ми ретраїмо доставку до 3 разів із backoff-ом: 60s → 300s → 300s. Це дає час полагодити whitelist, ротацію токена чи короткий релізний даунтайм на вашому боці без втрати вебхука. Якщо після усіх спроб 2xx не отримано — спроба фіксується в логах; рекомендуємо як fallback час від часу звіряти статус ордера через ваші внутрішні монiторинги.

Вебхуки

При створенні замовлення з callback_url, система надішле POST запит на ваш URL при зміні статусу замовлення.

Тіло вебхука

{
  "order_id": "coY8sOZ6sej4RKvOUvIgq",
  "hash": "abc123def456",
  "status": "PAID",
  "amount": "100.00000000",
  "to_amount": "4125.00000000",
  "currency_from": "USDTTRC20",
  "currency_to": "P24UAH",
  "created_at": "2024-03-18T10:00:00+00:00",
  "updated_at": "2024-03-18T10:15:00+00:00"
}