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).
Create — POST /v1/invoices (scope invoices:write, Idempotency-Key required)
| Field | Type | |
|---|---|---|
amount | string, required | USDT, ≤ 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_id | string ≤ 128 | your reference; unique among this business's invoices that are not expired/cancelled (409 order_id_exists) — reusable after expiry/cancel |
description | string ≤ 500 | shown to the customer on the payment page |
expires_in | integer seconds | 300–86,400; default = the business default (30 min) |
metadata | object | ≤ 20 string values, keys ≤ 40, values ≤ 500 chars, ≤ 4 KB; never shown to the customer |
redirect_url | https URL | the payment page sends the customer here 5 s after payment |
cancel_url | https 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, object | inv_…, "invoice" |
status | see below |
amount, amount_units | requested amount |
address | where the customer pays (checksummed), Polygon USDT only |
received, received_units | confirmed (finalized) payments inside the window |
received_detected | seen on chain, including not yet final — informational |
late_amount | confirmed payments after the window / after cancel |
overpaid | received more than amount + overpay tolerance |
payments | the on-chain payments (on GET of one invoice; [] at creation) — see payments |
order_id, description, metadata, redirect_url, cancel_url | as created (null when unset) |
payment_link | plink_… if the invoice was created from a payment link, else null |
pay_url | hosted payment page (null if the server has no API_PUBLIC_URL) |
qr_uri | EIP-681 ethereum:<USDT>@137/transfer?address=…&uint256=… (not every wallet understands it — see payment page) |
network, chain_id, token, currency, livemode | polygon, 137, USDT contract, USDT, true on mainnet |
expires_at, created_at, paid_at, closed_at | RFC 3339 UTC (null when not reached) |
Lifecycle
| status | meaning | final? |
|---|---|---|
pending | nothing received yet | no |
processing | a payment was seen (maybe partial, maybe not final yet) | no |
paid | finalized total ≥ amount − underpay tolerance (overpaid: true if above amount + overpay tolerance) | yes — ship now |
underpaid | window over with a partial confirmed amount | yes |
expired | window over, nothing received | yes |
cancelled | you cancelled it while pending | yes |
- The window is the block time. A transfer counts if the block that holds it has a timestamp before
expires_at— even if Polysia only processes it later. An invoice is closed (expired / underpaid) only after the finalized chain has passedexpires_at, so allow a few minutes after expiry before acting on "no payment". - Partial payments keep the invoice
processing; the customer can top up to the same address until expiry. With an underpay tolerance (dashboard → API → Invoice settings, % or fixed) a slightly short payment counts as paid; the tolerance is never more than 10 % of the invoice amount (a larger fixed value is capped per invoice). - Late payments (after the window, or to a cancelled invoice) never change the status: they add to
late_amountand sendinvoice.late_payment. Refund or accept them manually. - Reorgs: a detected payment that disappears becomes
orphaned; the invoice goes back topending/processing. That is why onlypaid(finalized) is final. - Settings changes apply to new invoices only; each invoice keeps the tolerances it was created with.
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.