For authentication, error format, and common headers, see General API Info.
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* |
fulfill | object | What to do with the money once it lands, so paying is enough to get the proxy. See below | 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..."
}If the gateway cannot create the payment, the answer is 503 with payment.gateway_unavailable. Nothing is charged and no top-up is saved; the customer can pick another gateway.
Paying for an order (fulfill)
With fulfill, the server places the order itself right after the balance is credited, so the customer gets the proxy even if they close the payment tab. The request is checked when the top-up is created (a malformed one is refused with payment.invalid_fulfillment) and the price and balance are checked again when the money lands.
type | Fields | Does |
|---|---|---|
create | order: the body of POST /orders/create | Creates the order |
renew | orderId, discountToken? | Renews a postpaid order |
topup_traffic | orderId, trafficGb, discountToken? | Adds traffic |
{
"amount": 8,
"gateway": "monobank",
"redirectUrl": "https://dashboard.fonproxy.io/api/billing-return",
"fulfill": { "type": "create", "order": { "proxyTypeId": "residential-giga", "trafficGb": 5 } }
}If the order cannot be placed (the price changed, the product is gone), the money stays on the balance, the top-up is still success, and fulfillment.status is failed with the reason key.
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...",
"fulfillment": { "type": "create", "status": "placed", "orderId": "10-645330", "error": null },
"createdAt": "2026-03-15T12:00:00.000Z"
}fulfillment is null for a plain top-up. Otherwise status is pending (the money has not landed yet, or the order is being placed), placed (orderId is the order that was created, renewed or topped up) or failed (error is a translation key).
| 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)