Payment API

FonProxy Payment API reference documentation.

FonProxy API — Payment

All endpoints require Authorization: Bearer <token> unless noted.

See payments.md for full architecture, flow diagrams, and gateway integration guide.

Payment

`GET /payment/gateways`

List available payment gateways. Requires JWT.

Response (200):

{
  "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 /payment/gateways/:key/meta`

Get the meta field schema for a gateway (when requiresMeta: true).

Response (200):

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

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

Resolve dependent field options based on current selections.

Request body:

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

Response (200): Full meta fields with resolved options.

`POST /payment/preview`

Preview a payment before confirming.

Request body:

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

Response (200):

{
  "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": []
  }
}

`POST /payment/topup`

Create a top-up. Returns a redirect URL to the payment page.

Request body:

{
  "amount": 100,
  "gateway": "monobank",
  "redirectUrl": "https://dashboard.fonproxy.io/topup/callback",
  "reason": "Balance top-up"
}

Field	Type	Required	Description
`amount`	number	yes	Amount in user's display currency
`gateway`	string	yes	Gateway key
`redirectUrl`	string	yes	Where user returns after payment
`orderId`	string	no	Optional order ID to link
`reason`	string	no	Optional reason
`gatewayMeta`	object	no*	Required when `requiresMeta: true`

Response (200):

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

`GET /payment/topup/:id/status`

Poll top-up status.

Response (200):

{
  "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

`POST /payment/webhook/:gateway`

Webhook callback from payment gateway. Public — no JWT required.

Response (200):

{ "ok": true }

Receipts

`GET /receipts/:id`

View a transaction receipt as an inline PDF. Public — hashid acts as access token.

Response: Content-Type: application/pdf (inline)

`GET /receipts/:id/download`

Download the receipt PDF as a file attachment.

Response: Content-Type: application/pdf (attachment)