Invoice များ
Invoice တစ်ခုသည် သတ်မှတ်ချိန်အတွင်း ပုံသေ USDT ပမာဏကို တောင်းခံသည်။ Invoice တစ်ခုစီသည် ကိုယ်ပိုင် လိပ်စာအသစ် (ကျပန်း key ဖြင့် CREATE2 factory child — ဘယ်တော့မှ ပြန်မသုံး) ရသဖြင့် ငွေပေးချေမှုကို လိပ်စာတစ်ခုတည်းဖြင့် ကိုက်ညီစေသည်။ Memo မလို၊ ပမာဏကို ဒသမ အနည်းငယ် ပြောင်း၍ ခွဲခြားရန် မလို။ ငွေသည် ထိုလိပ်စာမှ နောက် sweep တွင် သင့် business ၏ Hot Wallet သို့ (platform fee နုတ်ပြီး) ရောက်သည်။
ဖန်တီးခြင်း — POST /v1/invoices (scope invoices:write၊ Idempotency-Key မဖြစ်မနေ)
| Field | အမျိုးအစား | |
|---|---|---|
amount | string၊ မဖြစ်မနေ | USDT၊ ဒသမ ≤ 6။ business ကန့်သတ်ချက်အတွင်း ဖြစ်ရမည် (GET /v1/business → invoice_settings): 1 USDT သို့မဟုတ် business ၏ sweep min-per-child ထက် ဘယ်တော့မှ မနည်းရ၊ install / business အများဆုံး (မူလ 100,000) ထက် မကျော်ရ |
order_id | string ≤ 128 | သင့် ကိုးကားချက်။ ဤ business ၏ သက်တမ်းမကုန်/မပယ်ဖျက်ရသေးသော invoice များအကြား ထပ်မရ (409 order_id_exists) — သက်တမ်းကုန်/ပယ်ဖျက်ပြီးမှ ပြန်သုံးနိုင်သည် |
description | string ≤ 500 | ငွေပေးချေရန် စာမျက်နှာပေါ်တွင် customer ကို ပြသည် |
expires_in | integer စက္ကန့် | 300–86,400၊ မူလ = business ၏ မူလတန်ဖိုး (၃၀ မိနစ်) |
metadata | object | string တန်ဖိုး ≤ 20၊ key ≤ 40၊ တန်ဖိုး ≤ 500 စာလုံး၊ ≤ 4 KB။ customer ကို ဘယ်တော့မှ မပြ |
redirect_url | https URL | ငွေပေးချေပြီး ၅ စက္ကန့်အကြာ ငွေပေးချေရန် စာမျက်နှာက customer ကို ဤနေရာသို့ ပို့သည် |
cancel_url | https 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, object | inv_…၊ "invoice" |
status | အောက်တွင် ကြည့်ပါ |
amount, amount_units | တောင်းခံသော ပမာဏ |
address | customer ပေးချေရမည့်နေရာ (checksummed)၊ Polygon USDT သာ |
received, received_units | အချိန်အတွင်း အတည်ပြုပြီး (finalized) ငွေပေးချေမှုများ |
received_detected | chain ပေါ်တွင် တွေ့ပြီး (မအတည်သေးသည်များ အပါအဝင်) — သိရန်သာ |
late_amount | အချိန်ကျော်ပြီး / ပယ်ဖျက်ပြီးနောက် အတည်ပြုပြီး ငွေပေးချေမှုများ |
overpaid | amount + overpay tolerance ထက် ပိုရရှိခဲ့သည် |
payments | on-chain ငွေပေးချေမှုများ (invoice တစ်ခု၏ GET တွင်၊ ဖန်တီးချိန်တွင် []) — payment များ ကို ကြည့်ပါ |
order_id, description, metadata, redirect_url, cancel_url | ဖန်တီးစဉ်အတိုင်း (မထည့်ထားလျှင် null) |
payment_link | payment link မှ ဖန်တီးလျှင် plink_…၊ မဟုတ်လျှင် null |
pay_url | ငွေပေးချေရန် စာမျက်နှာ (server တွင် API_PUBLIC_URL မရှိလျှင် null) |
qr_uri | EIP-681 ethereum:<USDT>@137/transfer?address=…&uint256=… (wallet တိုင်း နားမလည်ပါ — ငွေပေးချေရန် စာမျက်နှာ ကို ကြည့်ပါ) |
network, chain_id, token, currency, livemode | polygon၊ 137၊ USDT contract၊ USDT၊ mainnet တွင် true |
expires_at, created_at, paid_at, closed_at | RFC 3339 UTC (မရောက်သေးလျှင် null) |
အဆင့်များ (lifecycle)
| status | အဓိပ္ပာယ် | နောက်ဆုံးလား? |
|---|---|---|
pending | ဘာမှ မရရှိသေး | မဟုတ် |
processing | ငွေပေးချေမှု တွေ့ပြီ (တစ်စိတ်တစ်ပိုင်း ဖြစ်နိုင်၊ မအတည်သေး ဖြစ်နိုင်) | မဟုတ် |
paid | အတည်ပြုပြီး စုစုပေါင်း ≥ amount − underpay tolerance (amount + overpay tolerance ထက် ကျော်လျှင် overpaid: true) | ဟုတ် — ယခု ပစ္စည်းပို့ပါ |
underpaid | အချိန်ကုန်ပြီး အတည်ပြုပြီး ပမာဏ တစ်စိတ်တစ်ပိုင်းသာ | ဟုတ် |
expired | အချိန်ကုန်ပြီး ဘာမှ မရ | ဟုတ် |
cancelled | pending ဖြစ်စဉ် သင် ပယ်ဖျက်ခဲ့သည် | ဟုတ် |
- အချိန်ကို 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 များ ကို ကြည့်ပါ။