Polysia

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_idrequired, ≤ 128 printable characters — your id for the customer
metadataobject, 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)

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, objectpay_…, "payment"
statusdetected (seen, not final) → confirmed (finalized) — or orphaned (removed by a reorg; ignore it)
amount, amount_units
invoiceinv_… or null
address, address_id, customer_idreceiving address; for customer addresses also addr_… and your customer id
latean invoice payment outside its window (counts in late_amount, not in received)
tx_hash, log_index, block_number, block_time, fromon-chain details (from is the sender — may be an exchange)
detected_at, confirmed_at