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).
အကျဉ်းချုပ် (မြန်မာ): API key (pk_live_…) ကို server ပေါ်မှာပဲ ထားပါ (browser / app ထဲ မထည့်ရ)။ POST /v1/invoices (+ Idempotency-Key) → customer ကို pay_url သို့ ပို့ → invoice.paid webhook (သို့) GET /v1/invoices/{id} → status: "paid" ဖြစ်မှ ပစ္စည်းပို့ပါ။ ပမာဏ အားလုံး USDT decimal string ("25.00") ဖြစ်ပြီး float မသုံးပါ။
| Page | Contents |
|---|---|
| Invoices | create / get / list / cancel, lifecycle, amounts, expiry, tolerances, late payments |
| Payment page | what the customer sees, languages, QR, redirect, embedding |
| Payment links | reusable links /l/… (fixed or customer-entered amount) |
| Addresses & payments | one permanent address per customer; on-chain payments |
| Fees & business | 30-day fee period, fee quote, business info |
| Webhooks | events, signature verification (Python / Node / PHP / openssl), retries |
| Deployment | HTTPS 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
- 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.
- 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": [], … }
- Mark the order paid when the
invoice.paidwebhook arrives (verify its signature) or whenGET /v1/invoices/{id}says"status": "paid".paidis 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":"…"}}:
| HTTP | code | meaning |
|---|---|---|
| 400 | invalid_request | malformed JSON, unknown field, bad value (param names it) |
| 400 | idempotency_key_required | POST without Idempotency-Key |
| 400 | amount_out_of_range | amount outside the business's invoice limits (message has min/max) |
| 400 | cookies_not_accepted | a dashboard cookie was sent to the API |
| 401 | invalid_api_key | any authentication failure |
| 403 | insufficient_scope / ip_not_allowed / cors_not_supported | key lacks the scope / wrong IP / browser preflight |
| 404 | resource_missing / not_found | no such id (or it belongs to another business) / no such endpoint |
| 409 | order_id_exists | an invoice with this order_id exists that is not expired or cancelled |
| 409 | invoice_not_cancellable | only pending invoices can be cancelled |
| 409 | invoice_limits_misconfigured | the business's min/max settings contradict each other — fix them in the dashboard |
| 413 | body_too_large | body over 16 KB |
| 422 | idempotency_key_reused | same Idempotency-Key, different request |
| 429 | rate_limited / too_many_open_invoices | slow down / the business has too many open invoices (default 10,000) |
| 500 | internal_error | retry later with the same Idempotency-Key |
| 503 | chain_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.