Create

Creates an invoice and returns the payment link url.

type sets how the client pays: in the Freedom SuperApp (superapp), with Bybit Pay (bybit) or Binance Pay (binance).

Open url for the client or send it. For superapp, the QR code qr_code is also returned.

external_id must be unique: it protects against duplicate invoices. A repeated X-Request-Id does not.

Pass state_callback to get a notification when the status of the invoice changes. Without it, get the status with Status.

Sign the request with X-JWS-Signature: see Overview.

Invoice payment flow

Get the state of the invoice with Status, details with Info. An unpaid invoice can be cancelled with Cancel.

Result

HTTP	Meaning	Next step
`201`	The invoice is created: `status = new`.	Give the client `url`, then follow the status.
`201`	`status = error`: the payment system did not create the payment.	Create a new invoice with a new `external_id`. If it repeats, contact Freedom Pay support.
`400`, `401`, `422`, `500`	The request is rejected.	See «Errors» below.

Errors

The error is returned in error_description; error_code is returned only for 401 and 422.

HTTP	`error_code`	When	What to do
`400`	—	An invoice with this `external_id` already exists.	Use a new `external_id`, or get the existing invoice with Info.
`401`	`9998`	The signature is invalid.	Check the signature: see Overview.
`422`	`9403`	The X-JWS-Signature header is missing.	Pass the signature.
`500`	—	A field is missing or invalid, X-Request-Id is not a UUID, or an internal error occurred. `error_description` names the field.	Fix the request. If the request is valid, repeat it later with a new X-Request-Id.

Request

Header Params

Body Params application/jsonRequired

Examples

Invoice with receipt itemsBybit Pay invoiceBinance Pay invoice

{
    "type": "superapp",
    "amount": 12500.5,
    "currency": "KZT",
    "external_id": "order_1001",
    "shop_name": "Example shop",
    "description": "Order #1001",
    "expires_at": "2027-01-31T12:00:00Z",
    "back_url": "https://merchant.example.com/back",
    "state_callback": "https://merchant.example.com/callback",
    "tax": [
        {
            "name": "Item 1",
            "count": 1,
            "price": 12000.0,
            "type": "vat12"
        },
        {
            "name": "Delivery",
            "count": 1,
            "price": 500.5,
            "type": "vat12"
        }
    ]
}

Responses

🟢201Created

application/json

Headers

Bodyapplication/json

Examples

Invoice createdBybit Pay invoice createdBinance Pay invoice createdPayment not created

{
    "status": "new",
    "id": "019d0652-4e2f-7f54-a179-007c80c48cef",
    "url": "https://freedombank.onelink.me/WNLd/payment?flow=fpay&providerId=1000053&orderId=019d0652-4e2f-7f54-a179-007c80c48cef&appName=InvoiceService",
    "created_at": "2026-10-29T16:24:47+05:00",
    "qr_code": "data:image/svg+xml;base64,PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4KPHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZlcnNpb249IjEuMSIg..."
}

🟠400Bad Request

🟠401Unauthorized

🟠422Unprocessable Entity

🔴500Internal Server Error

Invoice payment flow#

Result#

Errors#

Request

Responses

Invoice payment flow

Result

Errors