Introduction

What you can build

The Manexx Merchant API turns a checkout into three moving parts: you create an invoice, send your customer to a hosted payment page, and receive a webhook when the money settles.

Accept a payment

Create an invoice, get a ready-to-use payment link.

Get notified

Receive a signed callback the moment an invoice settles.

Offer the right methods

Show only the methods and currencies enabled for you.

Track your payouts

List and inspect withdrawals programmatically.

Quickstart

Get your API key

Grab your secret key from the dashboard. It authenticates every request via the X-Api-Key header. Keep it server-side only.

export MANEXX_KEY="manexx_live_your_key_here"

Create an invoice

Send your order details. Use your own order id as external_id — it makes retries safe (see Idempotency).

curl -X POST https://api.manexx.com/api/v1/external/invoices \
  -H "X-Api-Key: $MANEXX_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "order-4821",
    "customer_id": "user-99",
    "amount": "1050.00",
    "currency": "UAH",
    "purpose": "Order #4821"
  }'

import httpx

resp = httpx.post(
    "https://api.manexx.com/api/v1/external/invoices",
    headers={"X-Api-Key": MANEXX_KEY},
    json={
        "external_id": "order-4821",
        "customer_id": "user-99",
        "amount": "1050.00",   # string, max 2 decimals
        "currency": "UAH",
        "purpose": "Order #4821",
    },
)
invoice = resp.json()["data"]

const resp = await fetch(
  "https://api.manexx.com/api/v1/external/invoices",
  {
    method: "POST",
    headers: {
      "X-Api-Key": process.env.MANEXX_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      external_id: "order-4821",
      customer_id: "user-99",
      amount: "1050.00",
      currency: "UAH",
      purpose: "Order #4821",
    }),
  },
);
const { data: invoice } = await resp.json();

Redirect the customer

The response contains a ready-to-use payment_url. Send your customer there; they pick a method and pay on our hosted page.

{
  "success": true,
  "data": {
    "uuid": "9f2c1e5a-...",
    "external_id": "order-4821",
    "status": "pending",
    "amount": "1050.00",
    "currency": { "code": "UAH", "symbol": "₴" },
    "payment_url": "https://manexx.com/pay/9f2c1e5a-...?token=...",
    "expires_at": "2026-07-16T10:24:11Z"
  }
}

payment_url is returned only to the creator (the X-Api-Key call). Store it or redirect immediately — a later public GET returns it as null.

Receive the webhook

When the invoice settles, we POST to your callback_url with the final status. Acknowledge with 2xx. Treat the webhook as the source of truth for fulfillment — see WebHooks.

Payment lifecycle

An invoice moves through a small, predictable set of states. Only success is terminal-and-good; the rest are final ways an invoice can end.

Created and waiting for the customer to pay. Has a live payment_url and an expires_at.

Paid and credited. Fulfill the order. A webhook is delivered.

The payment window elapsed before payment. Create a new invoice to retry.

Cancelled before payment.

A rare technical failure during settlement. Safe to treat like a non-success.

Fulfill strictly on success. Never fulfill on pending, and never infer payment from the customer landing on your success_url — always confirm via the webhook or a GET on the invoice.

Core concepts

Show Business & API key

Your business is your merchant account. Each business has one or more API keys (X-Api-Key). A key authenticates you and scopes every response to your own data — you can never see another business’s invoices.

Show Invoice, order_id & external_id

An invoice is a single payment order. It has two identifiers you can look it up by: uuid (our order_id) and external_id (your order id). Both are accepted wherever an {ident} path parameter appears.

Show Payment method & currency

A payment method is a way to pay (a bank, a card scheme). Which methods and currencies are available depends on what’s enabled for your business — discover them via Payment Methods and Currencies rather than hardcoding.

Show Webhook

A server-to-server callback we send to your callback_url when an invoice’s status changes to a terminal state. Idempotent and retried on failure — see WebHooks.

Base URL

https://api.manexx.com/api/v1/external

Authentication

Send your secret key in the X-Api-Key header on every request.

curl https://api.manexx.com/api/v1/external/rates \
  -H "X-Api-Key: manexx_live_your_key_here"

Your key is a secret: server-side only, never in a browser, mobile app, or git. Leaked? Revoke it in the dashboard and the old key dies instantly.

Situation	Result
Missing or unknown key	`401 API_KEY_INVALID`
Revoked key	`403 API_KEY_REVOKED`
Business not active	`403 BUSINESS_NOT_ACTIVE`
Account blocked	`403 MERCHANT_BLOCKED`

Response envelope

Every response uses one envelope, so you write one parser. Success puts the payload under data:

{ "success": true, "data": { "status": "pending" } }

Errors mirror it under error:

{
  "success": false,
  "error": {
    "code": "INVOICE_ALREADY_EXISTS",
    "message": "Invoice with this external_id already exists",
    "details": { "external_id": "order-4821", "status": "pending" }
  }
}

true on success, false on error. Always check this first.

Present when success is true. The endpoint’s payload (an object, or a page for lists).

Present when success is false.

Show properties

Stable machine-readable code. Branch on this, not on the message.

Human-readable text. May change between releases — don’t parse it.

Optional context. For validation errors, a map of field → [messages].

HTTP status codes

The HTTP status gives the class of outcome; error.code gives the exact reason. The full catalog lives on the Errors page.

Status	Meaning	Typical codes
`200`	Success	—
`201`	Created	—
`401`	Authentication failed	`API_KEY_INVALID`, `UNAUTHORIZED`
`403`	Not allowed	`API_KEY_REVOKED`, `BUSINESS_NOT_ACTIVE`, `MERCHANT_BLOCKED`
`404`	Not found	`INVOICE_NOT_FOUND`, `PAYMENT_METHOD_NOT_FOUND`
`409`	State conflict	`INVOICE_ALREADY_EXISTS`, `INVOICE_NOT_PAYABLE`
`422`	Invalid request	`VALIDATION_ERROR`, `CURRENCY_NOT_ALLOWED`
`429`	Rate limited	`RATE_LIMITED`, `TOO_MANY_UNPAID_INVOICES`
`500` / `503`	Server-side problem	`INTERNAL_ERROR`, `DB_UNAVAILABLE`

A 422 returns details as {field: [messages]}, e.g. {"amount": ["must have at most 2 decimal places"]}. Log it to debug bad requests fast.

Pagination

List endpoints take two query parameters and return a page object under data. 1-based page number. Items per page.

{
  "success": true,
  "data": {
    "items": [],
    "page": 1,
    "per_page": 20,
    "total_items": 137,
    "total_pages": 7,
    "has_next": true,
    "has_prev": false
  }
}

To walk everything: start at page=1 and keep going while has_next is true.

Money & amounts

All amounts are strings — "1050.00", never 1050.0. Parse with a decimal type (decimal.Decimal, BigDecimal), never a binary float, to avoid rounding errors.

Fiat amounts carry at most two decimal places; sending more is rejected with 422. USDT amounts follow their own precision and are likewise strings.

Timestamps

ISO 8601, always UTC ("2026-07-16T09:24:11Z"). Convert to local time for display only; store and compare in UTC.

Idempotency

Creating an invoice is idempotent on your ****external_id. Retry POST /external/invoices with an id you’ve already used and you won’t create a duplicate — you get 409 INVOICE_ALREADY_EXISTS with the existing invoice’s status in details.

Always set a stable external_id per order. Network retries then become safe: a retried create can never double-charge your customer.

Rate limiting

Requests are rate limited per API key. The current limit is 100 requests per 60 seconds. Over the limit → 429 RATE_LIMITED; back off and retry with exponential backoff. Some resources add their own guard, e.g. 429 TOO_MANY_UNPAID_INVOICES when too many invoices sit unpaid. Every response carries your current budget in headers:

Header	Meaning
`X-RateLimit-Limit`	Requests allowed per window
`X-RateLimit-Remaining`	Requests left in the current window
`X-RateLimit-Reset`	Seconds until the window resets

On a 429, the response also includes a Retry-After header (seconds) and details.retry_after_seconds.

These limits are current defaults and may change without notice. Don’t hardcode the numbers — read the X-RateLimit-* headers and honor Retry-After on 429.

Errors

Branch on the stable error.code — never on the HTTP status alone or the message. The complete, grouped list is on the Errors page.

Getting Started

API Reference

What you can build

Accept a payment

Get notified

Offer the right methods

Track your payouts

Quickstart

Payment lifecycle

Core concepts

Base URL

Authentication

Response envelope

HTTP status codes

Money & amounts

Timestamps

Idempotency

Rate limiting

Errors

​What you can build

Accept a payment

Get notified

Offer the right methods

Track your payouts

​Quickstart

​Payment lifecycle

​Core concepts

​Base URL

​Authentication

​Response envelope

​HTTP status codes

​Pagination

​Money & amounts

​Timestamps

​Idempotency

​Rate limiting

​Errors

What you can build

Quickstart

Payment lifecycle

Core concepts

Base URL

Authentication

Response envelope

HTTP status codes

Pagination

Money & amounts

Timestamps

Idempotency

Rate limiting

Errors