docs
ဤစာမျက်နှာတွင်

Invoice များ

Invoice တစ်ခုသည် သတ်မှတ်ချိန်အတွင်း ပုံသေ USDT ပမာဏကို တောင်းခံသည်။ Invoice တစ်ခုစီသည် ကိုယ်ပိုင် လိပ်စာအသစ် (ကျပန်း key ဖြင့် CREATE2 factory child — ဘယ်တော့မှ ပြန်မသုံး) ရသဖြင့် ငွေပေးချေမှုကို လိပ်စာတစ်ခုတည်းဖြင့် ကိုက်ညီစေသည်။ Memo မလို၊ ပမာဏကို ဒသမ အနည်းငယ် ပြောင်း၍ ခွဲခြားရန် မလို။ ငွေသည် ထိုလိပ်စာမှ နောက် sweep တွင် သင့် business ၏ Hot Wallet သို့ (platform fee နုတ်ပြီး) ရောက်သည်။

ဖန်တီးခြင်း — POST /v1/invoices (scope invoices:write၊ Idempotency-Key မဖြစ်မနေ)

Fieldအမျိုးအစား
amountstring၊ မဖြစ်မနေUSDT၊ ဒသမ ≤ 6။ business ကန့်သတ်ချက်အတွင်း ဖြစ်ရမည် (GET /v1/business → invoice_settings): 1 USDT သို့မဟုတ် business ၏ sweep min-per-child ထက် ဘယ်တော့မှ မနည်းရ၊ install / business အများဆုံး (မူလ 100,000) ထက် မကျော်ရ
order_idstring ≤ 128သင့် ကိုးကားချက်။ ဤ business ၏ သက်တမ်းမကုန်/မပယ်ဖျက်ရသေးသော invoice များအကြား ထပ်မရ (409 order_id_exists) — သက်တမ်းကုန်/ပယ်ဖျက်ပြီးမှ ပြန်သုံးနိုင်သည်
descriptionstring ≤ 500ငွေပေးချေရန် စာမျက်နှာပေါ်တွင် customer ကို ပြသည်
expires_ininteger စက္ကန့်300–86,400၊ မူလ = business ၏ မူလတန်ဖိုး (၃၀ မိနစ်)
metadataobjectstring တန်ဖိုး ≤ 20၊ key ≤ 40၊ တန်ဖိုး ≤ 500 စာလုံး၊ ≤ 4 KB။ customer ကို ဘယ်တော့မှ မပြ
redirect_urlhttps URLငွေပေးချေပြီး ၅ စက္ကန့်အကြာ ငွေပေးချေရန် စာမျက်နှာက customer ကို ဤနေရာသို့ ပို့သည်
cancel_urlhttps URLငွေပေးချေရန် စာမျက်နှာပေါ်ရှိ "Cancel and return" link (invoice ကို မပယ်ဖျက်ပါ)

Response 201 = invoice object။ Error များ: API အကျဉ်း ကို ကြည့်ပါ (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))) — API အကျဉ်း ရှိ helper များဖြင့်။

Invoice object

Field
id, objectinv_…၊ "invoice"
statusအောက်တွင် ကြည့်ပါ
amount, amount_unitsတောင်းခံသော ပမာဏ
addresscustomer ပေးချေရမည့်နေရာ (checksummed)၊ Polygon USDT သာ
received, received_unitsအချိန်အတွင်း အတည်ပြုပြီး (finalized) ငွေပေးချေမှုများ
received_detectedchain ပေါ်တွင် တွေ့ပြီး (မအတည်သေးသည်များ အပါအဝင်) — သိရန်သာ
late_amountအချိန်ကျော်ပြီး / ပယ်ဖျက်ပြီးနောက် အတည်ပြုပြီး ငွေပေးချေမှုများ
overpaidamount + overpay tolerance ထက် ပိုရရှိခဲ့သည်
paymentson-chain ငွေပေးချေမှုများ (invoice တစ်ခု၏ GET တွင်၊ ဖန်တီးချိန်တွင် []) — payment များ ကို ကြည့်ပါ
order_id, description, metadata, redirect_url, cancel_urlဖန်တီးစဉ်အတိုင်း (မထည့်ထားလျှင် null)
payment_linkpayment link မှ ဖန်တီးလျှင် plink_…၊ မဟုတ်လျှင် null
pay_urlငွေပေးချေရန် စာမျက်နှာ (server တွင် API_PUBLIC_URL မရှိလျှင် null)
qr_uriEIP-681 ethereum:<USDT>@137/transfer?address=…&uint256=… (wallet တိုင်း နားမလည်ပါ — ငွေပေးချေရန် စာမျက်နှာ ကို ကြည့်ပါ)
network, chain_id, token, currency, livemodepolygon၊ 137၊ USDT contract၊ USDT၊ mainnet တွင် true
expires_at, created_at, paid_at, closed_atRFC 3339 UTC (မရောက်သေးလျှင် null)

အဆင့်များ (lifecycle)

statusအဓိပ္ပာယ်နောက်ဆုံးလား?
pendingဘာမှ မရရှိသေးမဟုတ်
processingငွေပေးချေမှု တွေ့ပြီ (တစ်စိတ်တစ်ပိုင်း ဖြစ်နိုင်၊ မအတည်သေး ဖြစ်နိုင်)မဟုတ်
paidအတည်ပြုပြီး စုစုပေါင်း ≥ amount − underpay tolerance (amount + overpay tolerance ထက် ကျော်လျှင် overpaid: true)ဟုတ် — ယခု ပစ္စည်းပို့ပါ
underpaidအချိန်ကုန်ပြီး အတည်ပြုပြီး ပမာဏ တစ်စိတ်တစ်ပိုင်းသာဟုတ်
expiredအချိန်ကုန်ပြီး ဘာမှ မရဟုတ်
cancelledpending ဖြစ်စဉ် သင် ပယ်ဖျက်ခဲ့သည်ဟုတ်
  • အချိန်ကို block time ဖြင့် တွက်သည်။ ငွေလွှဲမှုပါသော block ၏ timestamp သည် expires_at မတိုင်မီ ဖြစ်လျှင် — Polysia က နောက်မှ process လုပ်သော်လည်း — ရေတွက်သည်။ Finalized chain က expires_at ကို ကျော်ပြီးမှသာ invoice ကို ပိတ်သည် (expired / underpaid)၊ ထို့ကြောင့် "ငွေမရ" အပေါ် ဆောင်ရွက်ခြင်းမပြုမီ သက်တမ်းကုန်ပြီးနောက် မိနစ်အနည်းငယ် စောင့်ပါ။
  • တစ်စိတ်တစ်ပိုင်း ငွေပေးချေမှု ရှိလျှင် invoice သည် processing ဖြစ်နေဆဲ — customer က သက်တမ်းမကုန်မီ လိပ်စာတူထံ ထပ်ဖြည့်နိုင်သည်။ underpay tolerance (dashboard → API → Invoice settings၊ % သို့မဟုတ် ပုံသေ) ထားလျှင် အနည်းငယ် လိုသော ငွေပေးချေမှုကို paid ဟု ရေတွက်သည်။ Tolerance သည် invoice ပမာဏ၏ 10 % ထက် ဘယ်တော့မှ မကျော်ပါ (ပိုကြီးသော ပုံသေတန်ဖိုးကို invoice တစ်ခုချင်းအလိုက် ကန့်သတ်သည်)။
  • နောက်ကျ ငွေပေးချေမှုများ (အချိန်ကျော်ပြီး သို့မဟုတ် ပယ်ဖျက်ပြီးသော invoice သို့) သည် status ကို ဘယ်တော့မှ မပြောင်းပါ — late_amount ထဲ ပေါင်းပြီး invoice.late_payment ပို့သည်။ ငွေပြန်အမ်းခြင်း သို့မဟုတ် လက်ခံခြင်းကို လက်ဖြင့် ဆောင်ရွက်ပါ။
  • Reorg: တွေ့ပြီးသော ငွေပေးချေမှု ပျောက်သွားလျှင် orphaned ဖြစ်ပြီး invoice သည် pending/processing သို့ ပြန်သွားသည်။ ထို့ကြောင့် paid (finalized) သာ နောက်ဆုံးအခြေအနေ ဖြစ်သည်။
  • Setting ပြောင်းလဲမှုများသည် invoice အသစ်များကိုသာ သက်ရောက်သည်။ Invoice တစ်ခုစီသည် ဖန်တီးစဉ်က tolerance များကို ဆက်ထိန်းထားသည်။

ကြည့်ခြင်း — GET /v1/invoices/{id} (scope invoices:read)

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

စာရင်း — GET /v1/invoices (scope invoices:read)

Filter များ: status၊ order_id၊ created[gte]၊ created[lte] နှင့် limit / starting_after။

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

ပယ်ဖျက်ခြင်း — POST /v1/invoices/{id}/cancel (scope invoices:write)

pending (ဘာမှ မတွေ့ရသေး) ဖြစ်နေစဉ်သာ — → cancelled၊ invoice.cancelled webhook။ ထပ်ခေါ်လျှင် ပယ်ဖျက်ပြီး invoice ကို ပြန်သည်။ ငွေပေးချေမှု တွေ့ပြီးပါက → 409 invoice_not_cancellable။ နောက်မှ ပို့သော ငွေသည် ရောက်လာဆဲ ဖြစ်သည် (late_amount အဖြစ်)၊ ထို့ကြောင့် ပယ်ဖျက်ထားသော invoice ကို မပေးချေရန် customer ကို ပြောပါ။

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

Webhook များ

invoice.detected၊ invoice.paid၊ invoice.overpaid၊ invoice.underpaid၊ invoice.expired၊ invoice.cancelled၊ invoice.late_payment — data သည် ဤ invoice object ဖြစ်သည်။ အစဉ်ကို အာမမခံပါ — data.status သို့မဟုတ် GET အပေါ် မူတည်၍ ဆောင်ရွက်ပါ။ Webhook များ ကို ကြည့်ပါ။