Payment API

Щоб дізнатися про автентифікацію, формат помилок та заголовки, дивіться Загальна інформація про API.

Шлюзи

Перелік платіжних шлюзів Auth required

GET /payment/gateways

Перелік доступних платіжних шлюзів.

Відповідь

{
  "gateways": [
    {
      "key": "monobank",
      "name": "Monobank",
      "description": "Український необанк. Оплата Visa/Mastercard, Apple Pay, Google Pay.",
      "logo": "/assets/gateways/monobank.png",
      "website": "https://monobank.ua",
      "supportedCurrencies": ["USD", "EUR", "UAH"],
      "allCurrencies": true,
      "allRegions": true,
      "estimatedFee": {
        "percent": 2.0,
        "fixed": 0,
        "currency": "USD",
        "description": "2% за транзакцію"
      },
      "minAmount": 0.50,
      "maxAmount": 29999,
      "requiresMeta": false
    },
    ...
  ]
}

Отримати схему мета-поля шлюзу Auth required

GET /payment/gateways/:key/meta

Отримати схему для мета полів шлюзу (коли requiresMeta: true).

Параметри

Відповідь

{
  "meta": {
    "fields": [
      {
        "key": "coin",
        "type": "select",
        "label": "payment.meta.coin",
        "required": true,
        "options": [
          { "value": "USDT", "label": "Tether" }
        ]
      }
    ]
  }
}

Вирішити опції мета поля Auth required

POST /payment/gateways/:key/meta/options

Визначити залежні опції полів на основі поточних виборів.

Параметри

Тіло запиту

{
  "selections": { "coin": "USDT" }
}

Відповідь

Повні мета поля з врахованими опціями (така ж форма як GET /payment/gateways/:key/meta).

Поповнення

Попередній перегляд платежу Auth required

POST /payment/preview

Попередній перегляд платежу перед підтвердженням.

Тіло запиту

{
  "amount": 100,
  "gateway": "monobank"
}

Відповідь

{
  "preview": {
    "amount": 100,
    "currency": "UAH",
    "amountUsd": 2.42,
    "exchangeRate": 41.37,
    "fee": {
      "percent": 2.0,
      "fixed": 0,
      "estimatedFee": 0.05,
      "estimatedFeeDisplay": 2.07,
      "description": "2% за транзакцію"
    },
    "totalUsd": 2.47,
    "totalDisplay": 102.07,
    "lines": []
  }
}

Створити поповнення Auth required

POST /payment/topup

Створити поповнення. Повертає URL-адресу для переходу на сторінку оплати.

Тіло запиту

{
  "amount": 100,
  "gateway": "monobank",
  "redirectUrl": "https://dashboard.fonproxy.io/topup/callback",
  "reason": "Поповнення балансу"
}

Відповідь

{
  "topupId": "k5Xz9qR2Wp",
  "pageUrl": "https://pay.mbnk.biz/abc123..."
}

Якщо шлюз не може створити платіж, відповідь буде 503 з payment.gateway_unavailable. Нічого не списано, і ніяке поповнення не збережено; клієнт може вибрати інший шлюз.

Оплата за замовлення (fulfill)

З fulfill, сервер сам розміщує замовлення відразу після нарахування балансу, так що клієнт отримує проксі, навіть якщо він закриє вкладку з оплатою. Запит перевіряється, коли поповнення створено (запит із помилками відхилено з payment.invalid_fulfillment), а ціна та баланс перевіряються знову, коли гроші надійдуть.

{
  "amount": 8,
  "gateway": "monobank",
  "redirectUrl": "https://dashboard.fonproxy.io/api/billing-return",
  "fulfill": { "type": "create", "order": { "proxyTypeId": "residential-giga", "trafficGb": 5 } }
}

Якщо замовлення не може бути розміщено (ціна змінилася, продукт зник), гроші залишаються на балансі, поповнення все ще success, і fulfillment.status стає failed з ключем причини.

Опитування статусу поповнення Auth required

GET /payment/topup/:id/status

Параметри

Відповідь

{
  "topupId": "k5Xz9qR2Wp",
  "status": "pending",
  "amount": 100,
  "currency": "UAH",
  "amountUsd": 2.42,
  "gateway": "monobank",
  "pageUrl": "https://pay.mbnk.biz/abc123...",
  "fulfillment": { "type": "create", "status": "placed", "orderId": "10-645330", "error": null },
  "createdAt": "2026-03-15T12:00:00.000Z"
}

fulfillment є null для простого поповнення. Інакше status є pending (гроші ще не надійшли, або замовлення розміщується), placed (orderId — це замовлення, яке було створене, поновлене або поповнене) або failed (error — це ключ перекладу).

Квитанції

Переглянути квитанцію (Публічно)

GET /receipts/:id

Переглянути квитанцію транзакції у форматі PDF. Публічно — ID діє як токен доступу.

Параметри

Відповідь

Content-Type: application/pdf (inline)

Завантажити квитанцію (Публічно)

GET /receipts/:id/download

Завантажити PDF квитанції як файл-вкладення.

Параметри

Відповідь

Content-Type: application/pdf (attachment)