Polysia

Invoices

An invoice asks for a fixed USDT amount within a time window. Each invoice gets its own fresh address (a factory child, CREATE2 with a random key — never reused), so a payment is matched by address alone; no memo, no "unique cents". Funds go from that address to your business's Hot Wallet in the next sweep (minus the platform fee).

အကျဉ်းချုပ် (မြန်မာ): pending → (ငွေတွေ့) processing → (final) paid။ သက်တမ်းကုန်ရင် ငွေမရ = expired၊ တစ်စိတ်တစ်ပိုင်း = underpaid (final)။ paid ဖြစ်မှသာ ပစ္စည်းပို့ပါ — processing မှာ မပို့ပါနှင့်။ သက်တမ်းကုန်ပြီးမှ ရောက်လာတဲ့ငွေက status မပြောင်းဘဲ late_amount နဲ့ invoice.late_payment webhook ရပါမယ်။

Create — POST /v1/invoices (scope invoices:write, Idempotency-Key required)

FieldType
amountstring, requiredUSDT, ≤ 6 decimals. Must be within the business limits (GET /v1/business → invoice_settings): never below 1 USDT or the business's sweep min-per-child; at most the install / business maximum (default 100,000)
order_idstring ≤ 128your reference; unique among this business's invoices that are not expired/cancelled (409 order_id_exists) — reusable after expiry/cancel
descriptionstring ≤ 500shown to the customer on the payment page
expires_ininteger seconds300–86,400; default = the business default (30 min)
metadataobject≤ 20 string values, keys ≤ 40, values ≤ 500 chars, ≤ 4 KB; never shown to the customer
redirect_urlhttps URLthe payment page sends the customer here 5 s after payment
cancel_urlhttps URL"Cancel and return" link on the payment page (does not cancel the invoice)

Response 201 = the invoice object. Errors: see README (amount_out_of_range, order_id_exists, too_many_open_invoices, …).

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":"12.50","order_id":"A-1043","description":"Green tea 1 kg","expires_in":3600,"metadata":{"cart":"c-77"}}'

Node / PHP: polysia('POST', '/v1/invoices', {...}, crypto.randomUUID()) / polysia('POST', '/v1/invoices', [...], bin2hex(random_bytes(16))) with the helpers from the README.

The invoice object

Field
id, objectinv_…, "invoice"
statussee below
amount, amount_unitsrequested amount
addresswhere the customer pays (checksummed), Polygon USDT only
received, received_unitsconfirmed (finalized) payments inside the window
received_detectedseen on chain, including not yet final — informational
late_amountconfirmed payments after the window / after cancel
overpaidreceived more than amount + overpay tolerance
paymentsthe on-chain payments (on GET of one invoice; [] at creation) — see payments
order_id, description, metadata, redirect_url, cancel_urlas created (null when unset)
payment_linkplink_… if the invoice was created from a payment link, else null
pay_urlhosted payment page (null if the server has no API_PUBLIC_URL)
qr_uriEIP-681 ethereum:<USDT>@137/transfer?address=…&uint256=… (not every wallet understands it — see payment page)
network, chain_id, token, currency, livemodepolygon, 137, USDT contract, USDT, true on mainnet
expires_at, created_at, paid_at, closed_atRFC 3339 UTC (null when not reached)

Lifecycle

statusmeaningfinal?
pendingnothing received yetno
processinga payment was seen (maybe partial, maybe not final yet)no
paidfinalized total ≥ amount − underpay tolerance (overpaid: true if above amount + overpay tolerance)yes — ship now
underpaidwindow over with a partial confirmed amountyes
expiredwindow over, nothing receivedyes
cancelledyou cancelled it while pendingyes

Get — GET /v1/invoices/{id} (scope invoices:read)

curl -sS "$API/v1/invoices/inv_8f2c0a1b9d3e4f5a6b7c8d9e0f1a2b3c" -H "Authorization: Bearer $POLYSIA_API_KEY"

List — GET /v1/invoices (scope invoices:read)

Filters: status, order_id, created[gte], created[lte], plus limit / starting_after.

curl -sS -G "$API/v1/invoices" -H "Authorization: Bearer $POLYSIA_API_KEY" --data-urlencode "status=paid" --data-urlencode "limit=20"

Cancel — POST /v1/invoices/{id}/cancel (scope invoices:write)

Only while pending (nothing detected): → cancelled, invoice.cancelled webhook. Repeating it returns the cancelled invoice; once a payment was seen → 409 invoice_not_cancellable. Money sent later still arrives (as late_amount), so tell the customer not to pay a cancelled invoice.

curl -sS -X POST "$API/v1/invoices/inv_8f2c0a1b9d3e4f5a6b7c8d9e0f1a2b3c/cancel" -H "Authorization: Bearer $POLYSIA_API_KEY"

Webhooks

invoice.detected, invoice.paid, invoice.overpaid, invoice.underpaid, invoice.expired, invoice.cancelled, invoice.late_payment — data is this invoice object. Order is not guaranteed; act on data.status or GET. See Webhooks.