docs
On this page

Polysia merchant API (v1)

Polysia is a self-hosted, non-custodial USDT payment gateway on Polygon PoS. Your server talks to your own Polysia install over this REST API; customers pay on the hosted payment page or to an address you show yourself; your server learns about payments from signed webhooks (and can always ask the API).

PageContents
Invoicescreate / get / list / cancel, lifecycle, amounts, expiry, tolerances, late payments
Payment pagewhat the customer sees, languages, QR, redirect, embedding
Payment linksreusable links /l/… (fixed or customer-entered amount)
Addresses & paymentsone permanent address per customer; on-chain payments
Fees & business30-day fee period, fee quote, business info
Webhooksevents, signature verification (Python / Node / PHP / openssl), retries
DeploymentHTTPS reverse proxy (Caddy / Nginx), what to expose, .env

Examples: the curl commands were run against a local Polysia API (2026-11-18). The Node.js (fetch, Node 18+) and PHP (ext-curl) snippets follow the same requests but were not executed (no Node/PHP on the build machine) — try them against your test install first.

Quick start

  1. Dashboard → API → New API key (shown once) — or polysiad apikey create -business 1 -name shop. Keep it in your server's secret store / environment, never in a browser, mobile app or git.
  2. Create an invoice and send the customer to pay_url:
export API=https://pay.example.com                       # your API_PUBLIC_URL
read -rs POLYSIA_API_KEY; export POLYSIA_API_KEY         # paste the key; nothing is echoed
curl -sS "$API/v1/invoices" \
  -H "Authorization: Bearer $POLYSIA_API_KEY" \
  -H "Idempotency-Key: $(cat /proc/sys/kernel/random/uuid)" \
  -H "Content-Type: application/json" \
  -d '{"amount":"25.00","order_id":"A-1042","redirect_url":"https://shop.example.com/thanks"}'
{ "object": "invoice", "id": "inv_8f2c0a1b9d3e4f5a6b7c8d9e0f1a2b3c", "status": "pending",
  "amount": "25.000000", "amount_units": "25000000", "currency": "USDT", "network": "polygon", "chain_id": 137,
  "token": "0xc2132D05D31c914a87C6611C10748AEb04B58e8F", "address": "0x9A1b…7cD2",
  "pay_url": "https://pay.example.com/pay/pt_9c…", "expires_at": "2026-11-18T12:30:00Z", "payments": [], … }
  1. Mark the order paid when the invoice.paid webhook arrives (verify its signature) or when GET /v1/invoices/{id} says "status": "paid". paid is final and never reverted.

Node.js (not executed):

const API = process.env.POLYSIA_API_URL, KEY = process.env.POLYSIA_API_KEY;
// idempotencyKey: required for POST /v1/invoices and /v1/payment-links — keep it and reuse it on a retry
async function polysia(method, path, body, idempotencyKey) {
  const headers = { Authorization: `Bearer ${KEY}` };
  if (body !== undefined) headers['Content-Type'] = 'application/json';
  if (idempotencyKey) headers['Idempotency-Key'] = idempotencyKey;
  const res = await fetch(API + path, { method, headers, body: body === undefined ? undefined : JSON.stringify(body) });
  const data = await res.json();
  if (!res.ok) throw Object.assign(new Error(data.error?.message ?? res.statusText), { status: res.status, code: data.error?.code });
  return data;
}
const inv = await polysia('POST', '/v1/invoices', { amount: '25.00', order_id: 'A-1042' }, crypto.randomUUID());
console.log(inv.pay_url);

PHP (not executed):

<?php
function polysia(string $method, string $path, ?array $body = null, ?string $idempotencyKey = null): array {
    $h = ['Authorization: Bearer ' . getenv('POLYSIA_API_KEY')];
    if ($body !== null) { $h[] = 'Content-Type: application/json'; }
    if ($idempotencyKey !== null) { $h[] = 'Idempotency-Key: ' . $idempotencyKey; }
    $ch = curl_init(getenv('POLYSIA_API_URL') . $path);
    curl_setopt_array($ch, [CURLOPT_CUSTOMREQUEST => $method, CURLOPT_HTTPHEADER => $h, CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT => 20, CURLOPT_POSTFIELDS => $body === null ? null : json_encode($body)]);
    $raw = curl_exec($ch);
    $status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
    curl_close($ch);
    $data = json_decode((string)$raw, true) ?? [];
    if ($status >= 400) { throw new RuntimeException(($data['error']['code'] ?? 'http_' . $status) . ': ' . ($data['error']['message'] ?? '')); }
    return $data;
}
$inv = polysia('POST', '/v1/invoices', ['amount' => '25.00', 'order_id' => 'A-1042'], bin2hex(random_bytes(16)));
header('Location: ' . $inv['pay_url'], true, 303);

Conventions

Base URL https://<your payment domain>/v1 (API_PUBLIC_URL). JSON in and out, UTF-8. HTTPS only in production.

Authentication Authorization: Bearer pk_live_<12>_<52> (pk_test_… on test networks). Keys are stored only as a SHA-256 hash; a lost key cannot be shown again — create a new one and revoke the old. Every failure (unknown key, wrong secret, revoked, wrong network, malformed) answers the same 401 invalid_api_key; revocation is immediate. A key belongs to one business: ids of another business answer 404, exactly like ids that do not exist.

Scopes invoices:read, invoices:write (invoices + payment links), payments:read (payments, addresses), addresses:write, business:read (business, fees). New keys get all of them unless you choose fewer. A key can be limited to IP addresses / CIDRs (403 ip_not_allowed otherwise).

Amounts are decimal strings in USDT with at most 6 decimals ("25", "25.5", "25.000001"); responses use 6 decimals ("25.000000") plus *_units (base units, string). Never use floats.

Ids are opaque random strings with a prefix: inv_, pay_, addr_, plink_, evt_, we_. Do not parse them.

Idempotency POST /v1/invoices and POST /v1/payment-links require an Idempotency-Key header (1–64 visible ASCII characters; use a UUID per logical request and reuse it when you retry after a timeout). Keys are scoped per business and kept 24 h. A repeat with the same body returns the original response (header Idempotent-Replayed: true) — it is not the current state: call GET for that. The same key with a different body → 422 idempotency_key_reused. POST /v1/addresses is idempotent by customer_id and needs no key; cancel and deactivate are idempotent by nature.

Lists are newest first: ?limit=1–100 (default 50) &starting_after=<last id of the previous page> → {"object":"list","data":[…],"has_more":true}. Time filters created[gte] / created[lte] take unix seconds or RFC 3339.

Rate limits per client IP (20/s, burst 60), per key (10/s, burst 30, headers RateLimit-Limit, RateLimit-Remaining), invoice creation per key (1/s, burst 20); after repeated invalid keys from an IP, further invalid attempts from it get 429 for a while (requests with a valid key are never blocked). 429 rate_limited comes with Retry-After (seconds).

Errors {"error":{"code":"…","message":"…","param":"…"}}:

HTTPcodemeaning
400invalid_requestmalformed JSON, unknown field, bad value (param names it)
400idempotency_key_requiredPOST without Idempotency-Key
400amount_out_of_rangeamount outside the business's invoice limits (message has min/max)
400cookies_not_accepteda dashboard cookie was sent to the API
401invalid_api_keyany authentication failure
403insufficient_scope / ip_not_allowed / cors_not_supportedkey lacks the scope / wrong IP / browser preflight
404resource_missing / not_foundno such id (or it belongs to another business) / no such endpoint
409order_id_existsan invoice with this order_id exists that is not expired or cancelled
409invoice_not_cancellableonly pending invoices can be cancelled
409invoice_limits_misconfiguredthe business's min/max settings contradict each other — fix them in the dashboard
413body_too_largebody over 16 KB
422idempotency_key_reusedsame Idempotency-Key, different request
429rate_limited / too_many_open_invoicesslow down / the business has too many open invoices (default 10,000)
500internal_errorretry later with the same Idempotency-Key
503chain_unavailable/v1/fees could not read the contract; retry

No CORS. The API is server-to-server only; browsers get 403 on preflight. Never put the key in front-end code.

Health GET /v1/health → {"ok":true} (no auth) for your monitoring.