Payment API
Endpoints for payment gateways, balance top-ups, webhook handling, and receipt downloads on FonProxy.
For authentication, error format, and common headers, see General API Info.
See payments.md for full architecture, flow diagrams, and gateway integration guide.
Gateways
List Payment Gateways Auth required
GET /payment/gateways
List available payment gateways.
Response
{
"gateways": [
{
"key": "monobank",
"name": "Monobank",
"description": "Ukrainian neobank. Pay with 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% per transaction"
},
"minAmount": 0.50,
"maxAmount": 29999,
"requiresMeta": false
},
...
]
}Get Gateway Meta Schema Auth required
GET /payment/gateways/:key/meta
Get the meta field schema for a gateway (when requiresMeta: true).
Parameters
| Name | Type | Description | Required |
|---|---|---|---|
:key | string | Gateway key | Yes |
Response
{
"meta": {
"fields": [
{
"key": "coin",
"type": "select",
"label": "payment.meta.coin",
"required": true,
"options": [
{ "value": "USDT", "label": "Tether" }
]
}
]
}
}Resolve Meta Field Options Auth required
POST /payment/gateways/:key/meta/options
Resolve dependent field options based on current selections.
Parameters
| Name | Type | Description | Required |
|---|---|---|---|
:key | string | Gateway key | Yes |
Request Body
{
"selections": { "coin": "USDT" }
}Response
Full meta fields with resolved options (same shape as GET /payment/gateways/:key/meta).
Top-ups
Preview Payment Auth required
POST /payment/preview
Preview a payment before confirming.
Request Body
{
"amount": 100,
"gateway": "monobank"
}Response
{
"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% per transaction"
},
"totalUsd": 2.47,
"totalDisplay": 102.07,
"lines": []
}
}Create Top-up Auth required
POST /payment/topup
Create a top-up. Returns a redirect URL to the payment page.
Request Body
| Name | Type | Description | Required |
|---|---|---|---|
amount | number | Amount in user's display currency | Yes |
gateway | string | Gateway key | Yes |
redirectUrl | string | Where user returns after payment | Yes |
orderId | string | Optional order ID to link | No |
reason | string | Optional reason | No |
gatewayMeta | object | Required when requiresMeta: true | No* |
{
"amount": 100,
"gateway": "monobank",
"redirectUrl": "https://dashboard.fonproxy.io/topup/callback",
"reason": "Balance top-up"
}Response
{
"topupId": "k5Xz9qR2Wp",
"pageUrl": "https://pay.mbnk.biz/abc123..."
}Poll Top-up Status Auth required
GET /payment/topup/:id/status
Parameters
| Name | Type | Description | Required |
|---|---|---|---|
:id | string | Top-up ID | Yes |
Response
{
"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"
}| Status | Meaning |
|---|---|
pending | Waiting for payment |
processing | Waiting for confirmation |
success | Balance credited |
failed | Payment failed |
expired | Payment page expired |
Receipts
View Receipt (Public)
GET /receipts/:id
View a transaction receipt as an inline PDF. Public โ ID acts as access token.
Parameters
| Name | Type | Description | Required |
|---|---|---|---|
:id | string | Receipt ID | Yes |
Response
Content-Type: application/pdf (inline)
Download Receipt (Public)
GET /receipts/:id/download
Download the receipt PDF as a file attachment.
Parameters
| Name | Type | Description | Required |
|---|---|---|---|
:id | string | Receipt ID | Yes |
Response
Content-Type: application/pdf (attachment)