Deposit addresses and payments
Deposit addresses (deposit-address mode)
Instead of an invoice per order, give each of your customers one permanent address (a wallet top-up, a subscription balance, …). Any amount at any time; there is no invoice and no expiry — every transfer is a payment with the customer's id, and the payment.* webhooks tell you about it.
အကျဉ်းချုပ် (မြန်မာ): customer_id တစ်ခုကို လိပ်စာတစ်ခုသာ (ထပ်ခေါ်လည်း တူတူ)။ ငွေဝင်တိုင်း payment.detected → payment.confirmed webhook (customer_id, address_id ပါ) ရပါမယ် — confirmed ဖြစ်မှ customer balance ထဲ ထည့်ပါ။
Create or get — POST /v1/addresses (scope addresses:write)
| Field | |
|---|---|
customer_id | required, ≤ 128 printable characters — your id for the customer |
metadata | object, as for invoices; stored only when the address is created |
Idempotent by customer_id (no Idempotency-Key needed): 201 when this call created the address, 200 with the existing one otherwise. The address uses a random key (not derived from your customer id).
curl -sS "$API/v1/addresses" -H "Authorization: Bearer $POLYSIA_API_KEY" -H "Content-Type: application/json" \
-d '{"customer_id":"cust-1001"}'
{"object":"address","id":"addr_…","customer_id":"cust-1001","address":"0x…","metadata":{},
"received":"0.000000","received_units":"0","received_detected":"0.000000","payment_count":0,
"network":"polygon","chain_id":137,"token":"0xc2132D05D31c914a87C6611C10748AEb04B58e8F","livemode":true,"created_at":"…"}
Get / list (scope payments:read)
GET /v1/addresses/{id}— with totals:received(confirmed),received_detected,payment_countGET /v1/addresses?customer_id=cust-1001(+limit,starting_after)
Credit your customer on payment.confirmed (finalized), not on payment.detected. Use the payment id (pay_…) as the de-duplication key in your ledger.
Payments
Every USDT transfer to an invoice or customer address is a payment.
| Field | |
|---|---|
id, object | pay_…, "payment" |
status | detected (seen, not final) → confirmed (finalized) — or orphaned (removed by a reorg; ignore it) |
amount, amount_units | |
invoice | inv_… or null |
address, address_id, customer_id | receiving address; for customer addresses also addr_… and your customer id |
late | an invoice payment outside its window (counts in late_amount, not in received) |
tx_hash, log_index, block_number, block_time, from | on-chain details (from is the sender — may be an exchange) |
detected_at, confirmed_at |
GET /v1/payments/{id};GET /v1/payments?invoice=inv_…&address=0x…&status=confirmed&created[gte]=…(scopepayments:read)- Webhooks
payment.detected,payment.confirmed,payment.orphanedwith this object asdata.