Ontwikkelaars

’n Kripto-betaal-API gebou vir direkte vereffening

Skep ’n faktuur met een geverifieerde versoek en Unheld gee die adres om te betaal, die presiese bedrag, en die bevestigingsdiepte waarvoor dit sal wag. Betalings vereffen reguit na ’n beursie wat jy beheer — die API neem nooit bewaring van dit waaroor dit verslag doen nie.

Begin gratis Pryse

Skep ’n faktuur

Een POST. Die bedrag word geskryf soos ’n mens dit skryf en word bedienerkant geskaal volgens die bate se eie desimale, sodat jy nooit met die hand na basiseenhede omskakel nie.

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" }
  }'

Respons

{
  "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"
  }
}

receiveAddress is van jou beursie afgelei en aan hierdie faktuur gekoppel. expectedAmount is in basiseenhede. minConfirmations is die ketting se eie drempel, nie ’n instelling wat ons uitgedink het nie.

Verifikasie en bereike

Sleutels is bearer-tokens, in die paneelbord geskep en net een keer gewys. Elke sleutel dra ’n uitdruklike lys bereike en ’n versoek word geweier as die sleutel nie die bereik vir daardie roete het nie.

Beskikbare bereike

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

Ken die nouste stel toe wat werk. ’n Sleutel wat net fakture skep kan nie jou kliënte lees nie, en ’n gelekte leessleutel kan niks skuif nie — want niks in hierdie API kan nie.

Webhooks wat jy kan verifieer

Elke aflewering word onderteken. Die handtekening is ’n HMAC-SHA256 van die tydstempel en die rou liggaam met ’n punt saamgevoeg, met jou webhook-geheim, gestuur as ’n heksadesimale samevatting.

Verifieer ’n aflewering

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"])
);

Vergelyk samevattings in konstante tyd, weier ’n tydstempel buite jou toleransievenster, en behandel X-Request-Id as die idempotensiesleutel: hertoetse hergebruik dit, dus is dieselfde gebeurtenis wat twee keer aankom normaal en mag dit nie twee keer verwerk word nie.

Faktuurgebeurtenisse

’n Betaling beweeg deur toestande eerder as om van onbetaal na betaal om te slaan, en elke oorgang is ’n webhook. Onderbetaling en oorbetaling is hul eie gebeurtenisse, nie foute nie.

Gebeurtenis	Wat gebeur het
invoice.created	Die faktuur bestaan en die ontvangsadres word dopgehou.
invoice.receiving	’n Betalingstransaksie is op die ketting gesien maar is nog nie bevestig nie.
invoice.confirming	Die betaling bevestig tans en het nie die ketting se drempel bereik nie.
invoice.paid	Volledig bevestig op die diepte wat die ketting vereis. Veilig om te lewer.
invoice.underpaid	Minder het aangekom as verwag. Gedeeltelike betalings tel op, so ’n tweede oorbetaling kan dit voltooi.
invoice.overpaid	Meer het aangekom as verwag, presies aangeteken eerder as weggerond.
invoice.expired	Die venster het gesluit sonder volle betaling.

Toets die hele vloei gratis

Toets fakture, bespeuring, bevestigings en webhooks sonder regte fondse. Toetsnetwerktokens het geen geldwaarde nie. Toetsnetwerkaktiwiteit is nie ’n regte betaling nie.

Omvang

Dit hou nooit fondse nie. Daar is geen saldo-eindpunt om van te onttrek nie, want betalings land op jou adres en bly daar.
Dit skakel nie om of vereffen nie in fiat nie. Betalings kom aan in die bate en op die ketting waarop dit gestuur is.
Daar is nog geen amptelike SDK’s nie. Alles hier is gewone HTTP, en ons publiseer voorbeelde eerder as pakkette wat ons swak sou onderhou.

Ontwikkelaarsvrae

Is daar ’n sandput?

Toets fakture, bespeuring, bevestigings en webhooks sonder regte fondse. Toetsnetwerktokens het geen geldwaarde nie. Toetsnetwerkaktiwiteit is nie ’n regte betaling nie.

Hoe vermy ek dit om dieselfde webhook twee keer te verwerk?

Gebruik X-Request-Id as ’n idempotensiesleutel. Hertoetse hergebruik dieselfde waarde, dus teken dit aan en ignoreer ’n herhaling. Hertoetse word verwag: ’n aflewering wat misluk word volgens ’n skedule herprobeer eerder as laat val.

Moet ek self bedrae na basiseenhede omskakel?

Nee. Stuur amountDecimal soos ’n mens dit sou skryf en die API skaal dit volgens die bate se desimale. Die respons gee expectedAmount in basiseenhede terug, sodat albei voorstellings uitdruklik is en nie kan wegdryf nie.

Voorbeelde geverifieer teen die lewendige API op 21 September 2026.

Bou eers teen testnet

Skep ’n sleutel, rig dit op ’n testnet-ketting, en loop die hele vloei deur voordat enigiets werkliks beweeg.

Begin gratis

Pryse · Wat jy vandag kan aanvaar. · Jou geld gaan nie deur ons nie.