Polysia merchant API (v1)
Polysia သည် Polygon PoS ပေါ်ရှိ self-hosted၊ non-custodial USDT ငွေလက်ခံစနစ် ဖြစ်သည်။ သင့် server သည် ဤ REST API ဖြင့် သင့်ကိုယ်ပိုင် Polysia install နှင့် ဆက်သွယ်သည်။ Customer များသည် ငွေပေးချေရန် စာမျက်နှာတွင် သို့မဟုတ် သင်ကိုယ်တိုင် ပြသော လိပ်စာသို့ ပေးချေသည်။ သင့် server သည် ငွေပေးချေမှုများကို signed webhook များမှ သိရှိသည် (API ကိုလည်း အမြဲ မေးနိုင်သည်)။
| စာမျက်နှာ | ပါဝင်သည့်အရာ |
|---|---|
| Invoice များ | ဖန်တီး / ကြည့် / စာရင်း / ပယ်ဖျက်၊ အဆင့်များ၊ ပမာဏ၊ သက်တမ်း၊ tolerance၊ နောက်ကျ ပေးချေမှု |
| ငွေပေးချေရန် စာမျက်နှာ | customer မြင်ရသောအရာ၊ ဘာသာစကား၊ QR၊ redirect၊ embed |
| Payment link များ | ထပ်ခါသုံးနိုင်သော link /l/… (ပုံသေ သို့မဟုတ် customer ရိုက်ထည့်သော ပမာဏ) |
| လိပ်စာနှင့် ငွေပေးချေမှုများ | customer တစ်ယောက်လျှင် အမြဲတမ်း လိပ်စာ တစ်ခု၊ on-chain ငွေပေးချေမှုများ |
| ကြေးနှင့် business | ရက် ၃၀ fee period၊ ကြေး ခန့်မှန်းချက်၊ business အချက်အလက် |
| Webhook များ | event များ၊ signature စစ်ခြင်း (Python / Node / PHP / openssl)၊ ပြန်ပို့ခြင်း |
| Deployment | HTTPS reverse proxy (Caddy / Nginx)၊ ဘာကို ဖွင့်ပေးရမလဲ၊ .env |
ဥပမာများ: curl command များကို local Polysia API ပေါ်တွင် run ခဲ့သည် (2026-11-18)။ Node.js (
fetch၊ Node 18+) နှင့် PHP (ext-curl) နမူနာများသည် request တူတူကို လိုက်ရေးထားခြင်းဖြစ်သော်လည်း run မကြည့်ရသေးပါ (build စက်တွင် Node/PHP မရှိ) — သင့် test install ပေါ်တွင် အရင် စမ်းပါ။
အမြန်စတင်ခြင်း
- Dashboard → API → New API key (တစ်ကြိမ်သာ ပြမည်) — သို့မဟုတ်
polysiad apikey create -business 1 -name shop။ သင့် server ၏ secret store / environment ထဲတွင် သိမ်းပါ — browser၊ mobile app သို့မဟုတ် git ထဲ ဘယ်တော့မှ မထည့်ပါနှင့်။ - Invoice တစ်ခု ဖန်တီးပြီး customer ကို
pay_urlသို့ ပို့ပါ —
export API=https://pay.example.com # your API_PUBLIC_URL
read -rs POLYSIA_API_KEY; export POLYSIA_API_KEY # paste the key; nothing is echoed
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":"25.00","order_id":"A-1042","redirect_url":"https://shop.example.com/thanks"}'{ "object": "invoice", "id": "inv_8f2c0a1b9d3e4f5a6b7c8d9e0f1a2b3c", "status": "pending",
"amount": "25.000000", "amount_units": "25000000", "currency": "USDT", "network": "polygon", "chain_id": 137,
"token": "0xc2132D05D31c914a87C6611C10748AEb04B58e8F", "address": "0x9A1b…7cD2",
"pay_url": "https://pay.example.com/pay/pt_9c…", "expires_at": "2026-11-18T12:30:00Z", "payments": [], … }invoice.paidwebhook ရောက်လာသောအခါ (signature ကို စစ်ပါ) သို့မဟုတ်GET /v1/invoices/{id}က"status": "paid"ဟု ပြန်သောအခါ order ကို ပေးချေပြီးအဖြစ် မှတ်ပါ။paidသည် နောက်ဆုံးအခြေအနေ ဖြစ်ပြီး ဘယ်တော့မှ ပြန်မပြောင်းပါ။
Node.js (run မကြည့်ရသေး):
const API = process.env.POLYSIA_API_URL, KEY = process.env.POLYSIA_API_KEY;
// idempotencyKey: required for POST /v1/invoices and /v1/payment-links — keep it and reuse it on a retry
async function polysia(method, path, body, idempotencyKey) {
const headers = { Authorization: `Bearer ${KEY}` };
if (body !== undefined) headers['Content-Type'] = 'application/json';
if (idempotencyKey) headers['Idempotency-Key'] = idempotencyKey;
const res = await fetch(API + path, { method, headers, body: body === undefined ? undefined : JSON.stringify(body) });
const data = await res.json();
if (!res.ok) throw Object.assign(new Error(data.error?.message ?? res.statusText), { status: res.status, code: data.error?.code });
return data;
}
const inv = await polysia('POST', '/v1/invoices', { amount: '25.00', order_id: 'A-1042' }, crypto.randomUUID());
console.log(inv.pay_url);PHP (run မကြည့်ရသေး):
<?php
function polysia(string $method, string $path, ?array $body = null, ?string $idempotencyKey = null): array {
$h = ['Authorization: Bearer ' . getenv('POLYSIA_API_KEY')];
if ($body !== null) { $h[] = 'Content-Type: application/json'; }
if ($idempotencyKey !== null) { $h[] = 'Idempotency-Key: ' . $idempotencyKey; }
$ch = curl_init(getenv('POLYSIA_API_URL') . $path);
curl_setopt_array($ch, [CURLOPT_CUSTOMREQUEST => $method, CURLOPT_HTTPHEADER => $h, CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 20, CURLOPT_POSTFIELDS => $body === null ? null : json_encode($body)]);
$raw = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
$data = json_decode((string)$raw, true) ?? [];
if ($status >= 400) { throw new RuntimeException(($data['error']['code'] ?? 'http_' . $status) . ': ' . ($data['error']['message'] ?? '')); }
return $data;
}
$inv = polysia('POST', '/v1/invoices', ['amount' => '25.00', 'order_id' => 'A-1042'], bin2hex(random_bytes(16)));
header('Location: ' . $inv['pay_url'], true, 303);စည်းမျဉ်းများ
Base URL https://<your payment domain>/v1 (API_PUBLIC_URL)။ အဝင်/အထွက် JSON၊ UTF-8။ Production တွင် HTTPS သာ။
အထောက်အထားစစ်ခြင်း Authorization: Bearer pk_live_<12>_<52> (test network များတွင် pk_test_…)။ Key များကို SHA-256 hash အဖြစ်သာ သိမ်းသည် — ပျောက်သွားသော key ကို ပြန်ပြ၍ မရပါ၊ အသစ်ဖန်တီးပြီး အဟောင်းကို revoke လုပ်ပါ။ မအောင်မြင်မှုတိုင်း (မသိသော key၊ secret မှား၊ revoke ပြီး၊ network မှား၊ ပုံစံမမှန်) သည် 401 invalid_api_key တစ်မျိုးတည်းကိုသာ ပြန်သည်။ Revoke သည် ချက်ချင်း အသက်ဝင်သည်။ Key တစ်ခုသည် business တစ်ခုတည်း နှင့်သာ သက်ဆိုင်သည် — အခြား business ၏ id များကို မရှိသော id များကဲ့သို့ပင် 404 ပြန်သည်။
Scope များ invoices:read၊ invoices:write (invoice + payment link)၊ payments:read (payment၊ လိပ်စာ)၊ addresses:write၊ business:read (business၊ ကြေး)။ နည်းနည်းသာ မရွေးလျှင် key အသစ်များ အားလုံးကို ရသည်။ Key ကို IP လိပ်စာ / CIDR များဖြင့် ကန့်သတ်နိုင်သည် (မဟုတ်လျှင် 403 ip_not_allowed)။
ပမာဏများ သည် ဒသမ ၆ နေရာအထိ ပါသော USDT decimal string ဖြစ်သည် ("25"၊ "25.5"၊ "25.000001")။ Response များတွင် ဒသမ ၆ နေရာ ("25.000000") နှင့် *_units (base unit၊ string) ကို သုံးသည်။ Float ကို ဘယ်တော့မှ မသုံးပါနှင့်။
Id များ သည် prefix ပါသော ကျပန်း string များ ဖြစ်သည်: inv_၊ pay_၊ addr_၊ plink_၊ evt_၊ we_။ ၎င်းတို့ကို ခွဲခြမ်း မဖတ်ပါနှင့်။
Idempotency POST /v1/invoices နှင့် POST /v1/payment-links တွင် Idempotency-Key header မဖြစ်မနေ လိုသည် (မြင်ရသော ASCII စာလုံး ၁–၆၄ လုံး။ logical request တစ်ခုလျှင် UUID တစ်ခု သုံးပြီး timeout ဖြစ်၍ ပြန်ကြိုးစားသောအခါ ထိုတန်ဖိုးကိုပဲ ပြန်သုံးပါ)။ Key များသည် business အလိုက် သီးခြားဖြစ်ပြီး ၂၄ နာရီ သိမ်းထားသည်။ Body တူတူဖြင့် ထပ်ပို့လျှင် မူလ response ကို ပြန်သည် (header Idempotent-Replayed: true) — ၎င်းသည် လက်ရှိ အခြေအနေ မဟုတ်ပါ၊ လက်ရှိအခြေအနေအတွက် GET ကို ခေါ်ပါ။ Key တူတူ၊ body မတူလျှင် → 422 idempotency_key_reused။ POST /v1/addresses သည် customer_id အလိုက် idempotent ဖြစ်ပြီး key မလိုပါ။ cancel နှင့် deactivate တို့သည် သဘာဝအရ idempotent ဖြစ်သည်။
စာရင်းများ သည် အသစ်ဆုံးမှ စသည်: ?limit=1–100 (မူလ 50) &starting_after=<ယခင် စာမျက်နှာ၏ နောက်ဆုံး id> → {"object":"list","data":[…],"has_more":true}။ အချိန် filter created[gte] / created[lte] တို့တွင် unix စက္ကန့် သို့မဟုတ် RFC 3339 ကို သုံးနိုင်သည်။
Rate limit များ client IP အလိုက် (20/s၊ burst 60)၊ key အလိုက် (10/s၊ burst 30၊ header RateLimit-Limit၊ RateLimit-Remaining)၊ key အလိုက် invoice ဖန်တီးခြင်း (1/s၊ burst 20)။ IP တစ်ခုမှ မှားယွင်းသော key များ ထပ်ခါထပ်ခါ ပို့ပြီးနောက် ထို IP မှ နောက်ထပ် မှားယွင်းသော ကြိုးစားမှုများသည် ခဏကြာ 429 ရမည် (မှန်ကန်သော key ပါသည့် request များကို ဘယ်တော့မှ မပိတ်ပါ)။ 429 rate_limited တွင် Retry-After (စက္ကန့်) ပါသည်။
Error များ {"error":{"code":"…","message":"…","param":"…"}}:
| HTTP | code | အဓိပ္ပာယ် |
|---|---|---|
| 400 | invalid_request | JSON ပုံစံမမှန်၊ မသိသော field၊ တန်ဖိုးမမှန် (param က ဖော်ပြသည်) |
| 400 | idempotency_key_required | Idempotency-Key မပါသော POST |
| 400 | amount_out_of_range | ပမာဏသည် business ၏ invoice ကန့်သတ်ချက် ပြင်ပတွင် ရှိသည် (message တွင် min/max ပါ) |
| 400 | cookies_not_accepted | dashboard cookie ကို API သို့ ပို့လိုက်သည် |
| 401 | invalid_api_key | အထောက်အထားစစ်ခြင်း မအောင်မြင်မှု အားလုံး |
| 403 | insufficient_scope / ip_not_allowed / cors_not_supported | key တွင် scope မပါ / IP မှား / browser preflight |
| 404 | resource_missing / not_found | ထို id မရှိ (သို့မဟုတ် အခြား business ၏ id) / ထို endpoint မရှိ |
| 409 | order_id_exists | ဤ order_id ဖြင့် သက်တမ်းမကုန်သေး၊ ပယ်ဖျက်မထားသော invoice ရှိပြီးသား |
| 409 | invoice_not_cancellable | pending invoice များကိုသာ ပယ်ဖျက်နိုင်သည် |
| 409 | invoice_limits_misconfigured | business ၏ min/max setting များ အချင်းချင်း ဆန့်ကျင်နေသည် — dashboard တွင် ပြင်ပါ |
| 413 | body_too_large | body 16 KB ကျော် |
| 422 | idempotency_key_reused | Idempotency-Key တူ၊ request မတူ |
| 429 | rate_limited / too_many_open_invoices | နှေးပါ / business တွင် ဖွင့်ထားသော invoice များလွန်း (မူလ 10,000) |
| 500 | internal_error | Idempotency-Key တူတူဖြင့် နောက်မှ ပြန်ကြိုးစားပါ |
| 503 | chain_unavailable | /v1/fees က contract ကို မဖတ်နိုင်ပါ၊ ပြန်ကြိုးစားပါ |
CORS မရှိပါ။ API သည် server-to-server သာ ဖြစ်သည်။ Browser များသည် preflight တွင် 403 ရသည်။ Key ကို front-end code ထဲ ဘယ်တော့မှ မထည့်ပါနှင့်။
Health GET /v1/health → {"ok":true} (auth မလို) — သင့် monitoring အတွက်။