Sign in
Betalningar och uttag/Payout API

Payout API

Skicka uttag från ditt handlarsaldo till valfri blockchain-adress.

Payout API:et låter dig programmatiskt göra uttag från ditt handlarsaldo till valfri blockchain-adress.

För alla Payout-endpoints måste du använda en separat Payout API key för att generera signaturen sign. Den här nyckeln skiljer sig från din vanliga API key och måste genereras i dina projektinställningar.

Skapa uttag

Skapar en uttagsbegäran från ditt handlarsaldo.

POST/v1/payout

Parametrar i förfrågan

FältTypObligatorisktBeskrivning
currencystringjaUttagsvaluta (se References)
networkstringjaNätverkskod (se References)
amountstringjaUttagsbelopp
to_addressstringjaMottagarens blockchain-adress
order_idstringnejIdempotensnyckel — unik inom ett projekt. En upprepad POST med samma order_id skapar inte ett nytt uttag — den befintliga returneras istället
url_callbackstringnejURL för uttags-webhooks. Utelämna för att inaktivera webhooks för det här uttaget
memostring | nullnejDestinationstagg / memo. Används för närvarande endast av nätverken TON och SOL; max 255 tecken
from_currencystringnejKällsaldo att debitera och automatiskt konvertera till currency vid tidpunkten för uttaget. Låter dig betala ut i volatila tillgångar (BTC, ETH, …) samtidigt som ditt saldo hålls i en stablecoin som USDT — du behöver inte själv hålla den volatila kryptovalutan. Skicka "USDT" för att debitera USDT-saldot
fee_optionstringnejHur avgifter debiteras. deduct (standard) — nätverks- + plattformsavgifter dras från amount, mottagaren får amount - fees. add — avgifter läggs ovanpå, handlaren debiteras amount + fees och mottagaren får exakt amount

Idempotens. Inom ett projekt är ett uttag unikt baserat på order_id. Att skicka samma POST med samma order_id igen är säkert — API:et returnerar det befintliga uttaget istället för att skapa en dubblett. Skicka alltid med ett order_id för uttag i produktion.

Exempel på förfrågan

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

Exempel på svar

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

Avgifter. Standard fee_option: deduct — nätverks- + plattformsavgifter dras från amount (mottagaren får amount - fees). Skicka fee_option: add för att lägga avgifter ovanpå — mottagaren får exakt amount och handlaren debiteras amount + fees.

Beräkna uttag

Uppskattar uttagsbelopp och avgifter utan att skapa ett uttag eller debitera ditt saldo. Använd för att visa användaren det exakta beloppet de kommer att få (eller betala) innan de bekräftar.

POST/v1/payout/calc

Parametrar i förfrågan

Identiska med Skapa uttag — samma fält, samma signering. order_id, url_callback, to_address och memo accepteras men ignoreras: inget uttag sparas och inga callbacks skickas.

Exempel på förfrågan

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

Exempel på svar

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

Endast förhandsvisning. Den här endpointen är skrivskyddad — inget saldo debiteras och ingen uttagspost skapas. Anropa så ofta du behöver för att visa avgiftsfördelning i din UI.

Uttagsstatus

Hämta status för en uttagsbegäran.

GET/v1/payout/status/{uuid}

Sökvägsparametrar

FältTypObligatorisktBeskrivning
uuidstringjaUttagets UUID (från result.uuid vid skapandet)

Exempel på svar

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

För den här GET-förfrågan beräknas signaturen från en tom body: hash_hmac('sha256', base64_encode(''), $apiKey)

Svarsfält

Fält som returneras i result från POST /v1/payout och GET /v1/payout/status/{uuid}:

FältTypBeskrivning
uuidstringUUID för uttaget som tilldelats av systemet
order_idstringDin interna identifierare för uttaget (unik inom projektet)
statusstringAktuell uttagsstatus (se nedan)
currencystringUttagsvaluta
networkstringNätverkskod
amountstringUttagsbelopp enligt begäran
merchant_amountstringBelopp som debiterats från handlarsaldot
network_amountstringBelopp som faktiskt skickats on-chain (efter nätverks- + plattformsavgifter)
amount_usdstringUSD-motsvarighet av uttagsbeloppet
to_addressstringMottagarens blockchain-adress
memostring | nullDestinationstagg / memo (TON, SOL). null annars
txidstring | nullBlockchain-transaktionshash. null tills transaktionen skickats
block_numberint | nullBlocknummer där transaktionen inkluderats. null tills den inkluderats
error_typestring | nullOrsak till fel när status = failed (se Feltyper nedan). null annars
created_atstring (ISO 8601)Tidpunkt då uttaget skapades
updated_atstring (ISO 8601)Tidpunkt för senaste statusändring
from_currencystring | nullKällsaldo som uttaget debiterades från när automatisk konvertering användes (t.ex. USDT för ett uttag i BTC). null om ingen konvertering skedde
debited_amountstring | nullBelopp som faktiskt debiterats från källsaldot efter konvertering. Finns endast vid automatisk konvertering
debited_currencystring | nullValuta för debited_amount — saldot som medlen debiterades från

Uttagsstatusar

Fältet status kan ha följande värden:

StatusBeskrivning
pendingSkapat, väntar på bearbetning
completedSlutfört framgångsrikt — txid är satt
failedSändningsfel — se error_type
cancelledAvbrutet

Feltyper

När status = failed beskriver fältet error_type orsaken:

KodBeskrivning
aml_riskUttag blockerat av AML-riskkontroller (mottagaradressen flaggades som högrisk)

Webhook-notifieringar

När ett uttags status ändras skickar systemet en POST webhook till den url_callback-URL som angavs när uttaget skapades. Om url_callback inte angavs skickas inga webhooks för det uttaget.

  • Metod: POST
  • Content-Type: application/json
  • Signatur: fältet sign i body, beräknat med Payout API key (samma nyckel som används för att signera uttagsförfrågningar).

Payloaden speglar result-objektet från GET /v1/payout/status/{uuid} plus ett sign-fält för verifiering.

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

Verifiera signaturen. Använd samma algoritm som för betalnings-webhooks, men signera med din Payout API key istället för den vanliga API-nyckeln. Ta bort fältet sign, JSON-koda den återstående payloaden, Base64-koda den, beräkna sedan hash_hmac('sha256', $base64, $payoutApiKey) och jämför med den mottagna sign.