Developers

Crypto payment API na ginawa para sa diretsong settlement

Gumawa ng invoice sa isang authenticated request at ibabalik ng Unheld ang address na babayaran, ang eksaktong halaga, at ang lalim ng kumpirmasyong hihintayin nito. Diretso sa wallet na ikaw ang may kontrol ang bayad — hindi kailanman hinahawakan ng API ang bagay na ini-report nito.

Magsimula nang libre Presyo

Gumawa ng invoice

Isang POST lang. Isinusulat ang halaga sa paraang isinusulat ito ng tao at sini-scale sa server ayon sa sariling decimals ng asset, kaya hindi ka na mag-co-convert nang manu-mano papuntang base units.

curl -X POST https://api.unheld.io/api/v1/invoices \
  -H "Authorization: Bearer $UNHELD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "chainId": "11155111",
    "assetType": "native",
    "amountDecimal": "0.05",
    "expiresInSeconds": 900,
    "metadata": { "orderId": "A-1043" }
  }'

Response

{
  "id": "e2b0…",
  "status": "CREATED",
  "receiveAddress": "0x…",
  "expectedAmount": "50000000000000000",
  "minConfirmations": 3,
  "expiresAt": "2026-08-10T14:15:00.000Z",
  "instructions": {
    "chainId": "11155111",
    "to": "0x…",
    "amount": "50000000000000000",
    "assetType": "native"
  }
}

Ang receiveAddress ay nagmula sa wallet mo at naka-lock sa invoice na ito. Nasa base units ang expectedAmount. Ang minConfirmations ay ang sariling threshold ng chain, hindi setting na inimbento namin.

Authentication at scopes

Bearer token ang mga key, ginagawa sa dashboard at ipinapakita nang isang beses lang. May tahasang listahan ng scope ang bawat key at tinatanggihan ang request kung wala ang key ng scope para sa route na iyon.

Mga available na scope

invoices:write
invoices:read
webhooks:write
webhooks:read
balances:read
customers:write
customers:read
subscriptions:write
subscriptions:read

Ibigay ang pinakamakitid na set na gumagana. Ang key na puro paggawa lang ng invoice ay hindi makakabasa ng mga customer mo, at ang na-leak na read key ay walang maigagalaw — dahil wala sa API na ito ang kayang gumalaw.

Mga webhook na kaya mong i-verify

Nilalagdaan ang bawat delivery. Ang lagda ay HMAC-SHA256 ng timestamp at ng raw body na pinagdugtong ng tuldok, gamit ang webhook secret mo, ipinapadala bilang hex digest.

I-verify ang isang delivery

const signature = crypto
  .createHmac("sha256", webhookSecret)
  .update(`${req.headers["x-timestamp"]}.${rawBody}`)
  .digest("hex");

crypto.timingSafeEqual(
  Buffer.from(signature),
  Buffer.from(req.headers["x-signature"])
);

Ikumpara ang mga digest sa constant time, tanggihan ang timestamp na wala sa tolerance window mo, at ituring ang X-Request-Id bilang idempotency key: ginagamit ulit ito ng mga retry, kaya normal lang na dumating nang dalawang beses ang parehong event at hindi ito dapat maprosesong dalawang beses.

Mga invoice event

Dumadaan sa mga estado ang isang bayad sa halip na basta lumipat mula hindi bayad tungo sa bayad, at webhook ang bawat paglipat. Sariling event ang kulang at sobrang bayad, hindi mga error.

Event	Ano ang nangyari
invoice.created	Umiiral na ang invoice at binabantayan na ang receive address.
invoice.receiving	May nakitang transaksyon ng bayad sa chain pero hindi pa nakumpirma.
invoice.confirming	Kumukumpirma na ang bayad at hindi pa naaabot ang threshold ng chain.
invoice.paid	Ganap nang nakumpirma sa lalim na hinihingi ng chain. Ligtas nang ipagkaloob.
invoice.underpaid	Mas kaunti ang dumating kaysa inaasahan. Naiipon ang partial na bayad, kaya makakakumpleto ang pangalawang padala.
invoice.overpaid	Mas marami ang dumating kaysa inaasahan, naitala nang eksakto sa halip na i-round.
invoice.expired	Nagsara ang window nang walang buong bayad.

Subukan ang buong daloy nang libre

Subukan ang invoice, detection, confirmation at webhook nang walang totoong pondo. Walang halagang pinansyal ang testnet token. Hindi totoong bayad ang testnet activity.

Saklaw

Hindi ito kailanman humahawak ng pondo. Walang balance endpoint na mawi-withdraw, dahil sa address mo dumadapo ang bayad at doon ito nananatili.
Hindi ito nagko-convert o nagsi-settle sa fiat. Dumarating ang bayad sa asset at sa chain na ipinadala.
Wala pang opisyal na SDK. Purong HTTP ang lahat dito, at naglalathala kami ng mga halimbawa sa halip na mga package na hindi namin mamimintina nang maayos.

Mga tanong ng developer

May sandbox ba?

Subukan ang invoice, detection, confirmation at webhook nang walang totoong pondo. Walang halagang pinansyal ang testnet token. Hindi totoong bayad ang testnet activity.

Paano ko iiwasang maprosesong dalawang beses ang parehong webhook?

Gamitin ang X-Request-Id bilang idempotency key. Ginagamit ulit ng mga retry ang parehong halaga, kaya itala ito at balewalain ang ulit. Inaasahan ang mga retry: ang deliverying nabigo ay inuulit ayon sa iskedyul sa halip na itapon.

Kailangan ko bang mismong i-convert ang halaga sa base units?

Hindi. Ipadala ang amountDecimal gaya ng isusulat ng tao at sini-scale ito ng API ayon sa decimals ng asset. Ibinabalik ng response ang expectedAmount sa base units, kaya tahasan ang dalawang representasyon at hindi sila puwedeng maglihis.

Na-verify ang mga halimbawa laban sa live na API noong Setyembre 21, 2026.

Sa testnet ka muna mag-build

Gumawa ng key, ituro ito sa isang testnet chain, at patakbuhin ang buong daloy bago may tunay na gumalaw.

Magsimula nang libre

Presyo · Ang matatanggap mo ngayon. · Hindi dumadaan sa amin ang pera mo.