Sign in
Betalingen en uitbetalingen/Payout API

Payout API

Verstuur uitbetalingen vanaf je merchantsaldo naar elk blockchain-adres.

Met de Payout API kun je programmatisch geld vanaf je merchantsaldo uitbetalen naar elk blockchain-adres.

Voor alle Payout-endpoints moet je een aparte Payout API key gebruiken om de sign-handtekening te genereren. Deze key verschilt van je gewone API key en moet worden aangemaakt in je projectinstellingen.

Uitbetaling aanmaken

Maakt een uitbetalingsverzoek aan vanaf je merchantsaldo.

POST/v1/payout

Verzoekparameters

VeldTypeVereistBeschrijving
currencystringjaUitbetalingsvaluta (zie References)
networkstringjaNetwerkcode (zie References)
amountstringjaUitbetalingsbedrag
to_addressstringjaBlockchain-adres van de ontvanger
order_idstringneeIdempotentie-key — uniek binnen een project. Een herhaalde POST met dezelfde order_id maakt geen nieuwe uitbetaling aan — in plaats daarvan wordt de bestaande teruggegeven
url_callbackstringneeURL voor uitbetalingswebhooks. Laat weg om webhooks voor deze uitbetaling uit te schakelen
memostring | nullneeDestination tag / memo. Wordt momenteel alleen gebruikt door de TON- en SOL-netwerken; max. 255 tekens
from_currencystringneeBronsaldo dat op het moment van de uitbetaling wordt gedebiteerd en automatisch naar currency wordt omgezet. Hiermee kun je uitbetalen in volatiele activa (BTC, ETH, …) terwijl je saldo in een stablecoin als USDT blijft staan — je hoeft de volatiele crypto niet zelf aan te houden. Geef "USDT" mee om het USDT-saldo te debiteren
fee_optionstringneeHoe fees worden berekend. deduct (standaard) — netwerk- + platformfees worden van amount afgetrokken, de ontvanger krijgt amount - fees. add — fees worden bovenop berekend, de merchant wordt gedebiteerd met amount + fees, de ontvanger krijgt precies amount

Idempotentie. Binnen een project is een uitbetaling uniek op order_id. Dezelfde POST opnieuw versturen met dezelfde order_id is veilig — de API geeft de bestaande uitbetaling terug in plaats van een duplicaat aan te maken. Geef in productie altijd een order_id mee bij uitbetalingen.

Voorbeelden van verzoeken

Shell
curl -X POST https://api.2328.io/api/v1/payout \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyShop/1.0 (+https://myshop.example)" \
  -H "project: YOUR_PROJECT_UUID" \
  -H "sign: YOUR_HMAC_SIGNATURE" \
  -d '{"currency":"TRX","network":"TRX-TRC20","amount":"1.00","to_address":"TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t","order_id":"9ed25264-8be4-439f-acf5-2a8732538d27","url_callback":"https://your-site.com/webhook/payout","memo":null,"fee_option":"deduct"}'

Voorbeeld van een response

JSON
{
  "state": 0,
  "result": {
    "uuid": "019dea62-1727-72aa-ac2c-eaf2ade193ef",
    "order_id": "9ed25264-8be4-439f-acf5-2a8732538d27",
    "status": "pending",
    "currency": "TRX",
    "network": "TRX-TRC20",
    "amount": "1.00",
    "merchant_amount": "1",
    "network_amount": "0.89",
    "amount_usd": "0.33",
    "to_address": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
    "memo": null,
    "txid": null,
    "block_number": null,
    "error_type": null,
    "created_at": "2026-05-02T23:29:50+03:00",
    "updated_at": "2026-05-02T23:29:50+03:00"
  }
}

Fees. Standaard fee_option: deduct — netwerk- + platformfees worden van amount afgetrokken (de ontvanger krijgt amount - fees). Geef fee_option: add mee om fees bovenop te berekenen — de ontvanger krijgt precies amount en de merchant wordt gedebiteerd met amount + fees.

Uitbetaling berekenen

Schat uitbetalingsbedragen en kosten zonder een uitbetaling aan te maken of je saldo te debiteren. Gebruik dit om de gebruiker vóór bevestiging het exacte bedrag te tonen dat hij ontvangt (of betaalt).

POST/v1/payout/calc

Verzoekparameters

Identiek aan Uitbetaling aanmaken — dezelfde velden, dezelfde ondertekening. order_id, url_callback, to_address en memo worden geaccepteerd maar genegeerd: er wordt geen uitbetaling opgeslagen en er worden geen callbacks verzonden.

Voorbeeld van een verzoek

Shell
curl -X POST https://api.2328.io/api/v1/payout/calc \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyShop/1.0 (+https://myshop.example)" \
  -H "project: YOUR_PROJECT_UUID" \
  -H "sign: YOUR_HMAC_SIGNATURE" \
  -d '{"currency":"USDT","network":"TRX-TRC20","amount":"100","fee_option":"add"}'

Voorbeeld van een response

JSON
{
  "state": 0,
  "result": {
    "currency": "USDT",
    "network": "TRX-TRC20",
    "amount": "100",
    "fee_option": "add",
    "merchant_amount": "103.00000000",
    "network_amount": "100",
    "total_fee": "3.00000000",
    "total_fee_usd": "3.00000000"
  }
}

Alleen preview. Dit endpoint is alleen-lezen — er wordt geen saldo gedebiteerd en geen uitbetalings­record aangemaakt. Roep het zo vaak aan als nodig is om de kostenspecificatie in je UI te tonen.

Status van uitbetaling

Haal de status van een uitbetalingsverzoek op.

GET/v1/payout/status/{uuid}

Padparameters

VeldTypeVereistBeschrijving
uuidstringjaPayout UUID (uit result.uuid bij aanmaken)

Voorbeeld van een response

JSON
{
  "state": 0,
  "result": {
    "uuid": "019dff1f-0dbd-7277-8d45-271e7775388f",
    "order_id": "4dfdcc84402b1185b71cbe399321533e",
    "status": "completed",
    "currency": "TRX",
    "network": "TRX-TRC20",
    "amount": "3.00",
    "merchant_amount": "3.00",
    "network_amount": "3.00",
    "amount_usd": "1.04",
    "to_address": "THauRv5tcucQRohXg8NiyGTk16DX1XQG5x",
    "memo": null,
    "txid": "9242e533703704ef3eaba840f70b4a26333e72c943377ee375fea17badb53def",
    "block_number": null,
    "error_type": null,
    "created_at": "2026-05-07T00:08:38+03:00",
    "updated_at": "2026-05-07T00:08:54+03:00",
    "from_currency": "USDT",
    "debited_amount": "1.050735",
    "debited_currency": "USDT"
  }
}

Voor dit GET-verzoek wordt de handtekening berekend over een lege body: hash_hmac('sha256', base64_encode(''), $apiKey)

Responsevelden

Velden die in result worden teruggegeven door POST /v1/payout en GET /v1/payout/status/{uuid}:

VeldTypeBeschrijving
uuidstringPayout UUID toegewezen door het systeem
order_idstringJe interne uitbetalingsidentificatie (uniek binnen het project)
statusstringHuidige uitbetalingsstatus (zie hieronder)
currencystringUitbetalingsvaluta
networkstringNetwerkcode
amountstringUitbetalingsbedrag zoals aangevraagd
merchant_amountstringBedrag dat van het merchantsaldo is afgeschreven
network_amountstringBedrag dat daadwerkelijk on-chain is verstuurd (na netwerk- + platformfees)
amount_usdstringUSD-equivalent van het uitbetalingsbedrag
to_addressstringBlockchain-adres van de ontvanger
memostring | nullDestination tag / memo (TON, SOL). Anders null
txidstring | nullHash van de blockchain-transactie. null totdat de transactie is verstuurd
block_numberint | nullBlocknummer waarin de transactie is opgenomen. null totdat opgenomen
error_typestring | nullReden van mislukking als status = failed (zie Foutsoorten hieronder). Anders null
created_atstring (ISO 8601)Tijd van aanmaak van de uitbetaling
updated_atstring (ISO 8601)Tijd van laatste statuswijziging
from_currencystring | nullBronsaldo waarvan de uitbetaling is gedebiteerd wanneer automatische conversie is gebruikt (bijv. USDT voor een uitbetaling in BTC). null als er geen conversie heeft plaatsgevonden
debited_amountstring | nullBedrag dat na conversie daadwerkelijk van het bronsaldo is afgeschreven. Alleen aanwezig wanneer automatische conversie wordt gebruikt
debited_currencystring | nullValuta van debited_amount — het saldo waarvan geld is afgeschreven

Uitbetalingsstatussen

Het veld status kan de volgende waarden aannemen:

StatusBeschrijving
pendingAangemaakt, wacht op verwerking
completedSuccesvol voltooid — txid is ingesteld
failedVerzendfout — zie error_type
cancelledGeannuleerd

Foutsoorten

Wanneer status = failed, beschrijft het veld error_type de reden:

CodeBeschrijving
aml_riskUitbetaling geblokkeerd door AML-risicocontroles (ontvangeradres gemarkeerd als hoog risico)

Webhook-meldingen

Wanneer de status van een uitbetaling verandert, stuurt het systeem een POST-webhook naar de url_callback-URL die bij het aanmaken van de uitbetaling is meegegeven. Als url_callback niet is opgegeven, worden er geen webhooks voor die uitbetaling verstuurd.

  • Methode: POST
  • Content-Type: application/json
  • Handtekening: sign-veld in de body van het verzoek, berekend met de Payout API key (dezelfde key die wordt gebruikt om uitbetalingsverzoeken te ondertekenen).

De payload spiegelt het result-object van GET /v1/payout/status/{uuid} plus een sign-veld voor verificatie.

Payload

JSON
{
  "uuid": "019dff1f-0dbd-7277-8d45-271e7775388f",
  "order_id": "4dfdcc84402b1185b71cbe399321533e",
  "status": "completed",
  "currency": "TRX",
  "network": "TRX-TRC20",
  "amount": "3.00",
  "merchant_amount": "3.00",
  "network_amount": "3.00",
  "amount_usd": "1.04",
  "to_address": "THauRv5tcucQRohXg8NiyGTk16DX1XQG5x",
  "memo": null,
  "txid": "9242e533703704ef3eaba840f70b4a26333e72c943377ee375fea17badb53def",
  "block_number": null,
  "error_type": null,
  "created_at": "2026-05-07T00:08:38+03:00",
  "updated_at": "2026-05-07T00:08:54+03:00",
  "from_currency": "USDT",
  "debited_amount": "1.050735",
  "debited_currency": "USDT",
  "sign": "925ad7bf3d6841864101f7cc2c7e30652e70a06cdb04dbe07a0129480000ce4a"
}

De handtekening verifiëren. Gebruik hetzelfde algoritme als bij betalingswebhooks, maar onderteken met je Payout API key in plaats van de gewone API key. Verwijder het sign-veld, encodeer de overgebleven payload als JSON, encodeer in base64 en bereken vervolgens hash_hmac('sha256', $base64, $payoutApiKey) en vergelijk met de ontvangen sign.