API Платежів
Кінцеві точки для платіжних шлюзів, поповнення балансу, вебхуків та завантаження квитанцій на FonProxy.
Для аутентифікації, формату помилок та загальних заголовків, дивіться Загальна інформація API.
Дивіться payments.md для повної архітектури, діаграм потоків та посібника з інтеграції шлюзів.
Шлюзи
Список платіжних шлюзів 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).
Параметри
| Ім'я | Тип | Опис | Обов'язково |
|---|---|---|---|
:key | string | Ключ шлюзу | Так |
Відповідь
{
"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
Визначте параметри залежних полів на основі поточних виборів.
Параметри
| Ім'я | Тип | Опис | Обов'язково |
|---|---|---|---|
:key | string | Ключ шлюзу | Так |
Тіло запиту
{
"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 | number | Сума в валюті, що відображається користувачеві | Так |
gateway | string | Ключ шлюзу | Так |
redirectUrl | string | Куди користувач повертається після оплати | Так |
orderId | string | Необов'язковий ідентифікатор замовлення для зв'язку | Ні |
reason | string | Необов'язкова причина | Ні |
gatewayMeta | object | Необхідно, коли requiresMeta: true | Ні* |
{
"amount": 100,
"gateway": "monobank",
"redirectUrl": "https://dashboard.fonproxy.io/topup/callback",
"reason": "Поповнення балансу"
}Відповідь
{
"topupId": "k5Xz9qR2Wp",
"pageUrl": "https://pay.mbnk.biz/abc123..."
}Полінг статусу поповнення Auth required
GET /payment/topup/:id/status
Параметри
| Ім'я | Тип | Опис | Обов'язково |
|---|---|---|---|
:id | string | Ідентифікатор поповнення | Так |
Відповідь
{
"topupId": "k5Xz9qR2Wp",
"status": "pending",
"amount": 100,
"currency": "UAH",
"amountUsd": 2.42,
"gateway": "monobank",
"pageUrl": "https://pay.mbnk.biz/abc123...",
"createdAt": "2026-03-15T12:00:00.000Z"
}| Статус | Значення |
|---|---|
pending | Очікування оплати |
processing | Очікування підтвердження |
success | Баланс поповнено |
failed | Помилка оплати |
expired | Сторінка оплати закінчилася |
Квитанції
Перегляд квитанції (Публічно)
GET /receipts/:id
Переглянути квитанцію транзакції у вигляді вбудованого PDF. Публічно — ID діє як токен доступу.
Параметри
| Ім'я | Тип | Опис | Обов'язково |
|---|---|---|---|
:id | string | Ідентифікатор квитанції | Так |
Відповідь
Content-Type: application/pdf (вбудований)
Завантажити квитанцію (Публічно)
GET /receipts/:id/download
Завантажити квитанцію у форматі PDF як вкладений файл.
Параметри
| Ім'я | Тип | Опис | Обов'язково |
|---|---|---|---|
:id | string | Ідентифікатор квитанції | Так |
Відповідь
Content-Type: application/pdf (вкладений)