Sign in
Zahlungen und Auszahlungen/Payout API

Payout API

Senden Sie Auszahlungen von Ihrem Händlerguthaben an eine beliebige Blockchain-Adresse.

Mit der Payout API können Sie programmatisch Mittel von Ihrem Händlerguthaben an eine beliebige Blockchain-Adresse auszahlen.

Für alle Payout-Endpoints müssen Sie einen separaten Payout-API-Schlüssel verwenden, um die sign-Signatur zu erzeugen. Dieser Schlüssel unterscheidet sich von Ihrem regulären API-Schlüssel und muss in den Projekteinstellungen erzeugt werden.

Auszahlung erstellen

Erzeugt eine Auszahlungsanfrage von Ihrem Händlerguthaben.

POST/v1/payout

Anfrageparameter

FeldTypPflichtBeschreibung
currencystringjaAuszahlungswährung (siehe References)
networkstringjaNetzwerkcode (siehe References)
amountstringjaAuszahlungsbetrag
to_addressstringjaBlockchain-Adresse des Empfängers
order_idstringneinIdempotenzschlüssel — innerhalb eines Projekts eindeutig. Ein wiederholter POST mit derselben order_id erzeugt keine neue Auszahlung — stattdessen wird die bestehende zurückgegeben
url_callbackstringneinURL für Payout-Webhooks. Auslassen, um Webhooks für diese Auszahlung zu deaktivieren
memostring | nullneinDestination-Tag / Memo. Wird derzeit nur in den Netzwerken TON und SOL verwendet; max. 255 Zeichen
from_currencystringneinQuell-Guthaben, von dem zum Zeitpunkt der Auszahlung abgebucht und automatisch in currency umgerechnet wird. Ermöglicht Auszahlungen in volatilen Assets (BTC, ETH, …), während Ihr Guthaben in einem Stablecoin wie USDT bleibt — Sie müssen die volatile Krypto nicht selbst halten. Übergeben Sie "USDT", um vom USDT-Guthaben abzubuchen
fee_optionstringneinWie Gebühren berechnet werden. deduct (Standard) — Netzwerk- und Plattformgebühren werden vom amount abgezogen, der Empfänger erhält amount - fees. add — Gebühren werden oben aufgeschlagen, dem Händler werden amount + fees belastet, der Empfänger erhält exakt amount

Idempotenz. Innerhalb eines Projekts ist eine Auszahlung über die order_id eindeutig. Erneutes Senden desselben POST mit derselben order_id ist sicher — die API gibt die bestehende Auszahlung zurück, statt ein Duplikat zu erstellen. Übergeben Sie für produktive Auszahlungen stets eine order_id.

Anfragebeispiele

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

Antwortbeispiel

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

Gebühren. Standardmäßig fee_option: deduct — Netzwerk- und Plattformgebühren werden vom amount abgezogen (der Empfänger erhält amount - fees). Übergeben Sie fee_option: add, um die Gebühren oben aufzuschlagen — der Empfänger erhält exakt amount und dem Händler werden amount + fees belastet.

Auszahlung berechnen

Schätzt Auszahlungsbeträge und Gebühren ohne eine Auszahlung anzulegen oder das Guthaben zu belasten. So kannst du dem Nutzer vor der Bestätigung den exakten Betrag anzeigen, den er erhält (oder zahlt).

POST/v1/payout/calc

Anfrageparameter

Identisch zu Auszahlung erstellen — gleiche Felder, gleiche Signatur. order_id, url_callback, to_address und memo werden akzeptiert, aber ignoriert: es wird keine Auszahlung gespeichert und keine Callbacks gesendet.

Anfragebeispiel

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

Antwortbeispiel

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

Nur Vorschau. Dieser Endpoint ist nur lesend — es wird kein Guthaben belastet und kein Auszahlungs­datensatz erstellt. Rufe ihn so oft auf, wie du brauchst, um Gebühren­details in der Oberfläche darzustellen.

Auszahlungsstatus

Status einer Auszahlungsanfrage abrufen.

GET/v1/payout/status/{uuid}

Pfadparameter

FeldTypPflichtBeschreibung
uuidstringjaAuszahlungs-UUID (aus result.uuid bei der Erstellung)

Antwortbeispiel

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

Bei dieser GET-Anfrage wird die Signatur über einen leeren Body berechnet: hash_hmac('sha256', base64_encode(''), $apiKey)

Antwortfelder

Felder, die in result von POST /v1/payout und GET /v1/payout/status/{uuid} zurückgegeben werden:

FeldTypBeschreibung
uuidstringVom System vergebene Auszahlungs-UUID
order_idstringIhre interne Auszahlungs-ID (innerhalb des Projekts eindeutig)
statusstringAktueller Auszahlungsstatus (siehe unten)
currencystringAuszahlungswährung
networkstringNetzwerkcode
amountstringAngeforderter Auszahlungsbetrag
merchant_amountstringVom Händlerguthaben abgebuchter Betrag
network_amountstringTatsächlich on-chain gesendeter Betrag (nach Netzwerk- und Plattformgebühren)
amount_usdstringUSD-Gegenwert des Auszahlungsbetrags
to_addressstringBlockchain-Adresse des Empfängers
memostring | nullDestination-Tag / Memo (TON, SOL). Andernfalls null
txidstring | nullHash der Blockchain-Transaktion. null, bis die Transaktion gesendet wurde
block_numberint | nullBlocknummer, in der die Transaktion enthalten ist. null, bis sie aufgenommen wurde
error_typestring | nullFehlerursache, wenn status = failed (siehe unten Fehlertypen). Andernfalls null
created_atstring (ISO 8601)Erstellungszeitpunkt der Auszahlung
updated_atstring (ISO 8601)Zeitpunkt der letzten Statusänderung
from_currencystring | nullQuell-Guthaben, von dem die Auszahlung bei automatischer Umrechnung abgebucht wurde (z. B. USDT für eine BTC-Auszahlung). null, wenn keine Umrechnung erfolgte
debited_amountstring | nullTatsächlich vom Quell-Guthaben nach Umrechnung abgebuchter Betrag. Nur vorhanden, wenn die automatische Umrechnung verwendet wird
debited_currencystring | nullWährung von debited_amount — das Guthaben, von dem die Mittel abgebucht wurden

Auszahlungsstatus-Werte

Das Feld status kann folgende Werte annehmen:

StatusBeschreibung
pendingErstellt, wartet auf Verarbeitung
completedErfolgreich abgeschlossen — txid ist gesetzt
failedSendefehler — siehe error_type
cancelledStorniert

Fehlertypen

Wenn status = failed, beschreibt das Feld error_type den Grund:

CodeBeschreibung
aml_riskAuszahlung durch AML-Risikoprüfungen blockiert (Empfängeradresse als hohes Risiko gekennzeichnet)

Webhook-Benachrichtigungen

Wenn sich der Status einer Auszahlung ändert, sendet das System einen POST-Webhook an die url_callback-URL, die bei der Erstellung der Auszahlung übergeben wurde. Wurde keine url_callback angegeben, werden für diese Auszahlung keine Webhooks gesendet.

  • Methode: POST
  • Content-Type: application/json
  • Signatur: Feld sign im Anfrage-Body, berechnet mit dem Payout-API-Schlüssel (demselben Schlüssel, mit dem auch Auszahlungsanfragen signiert werden).

Der payload spiegelt das result-Objekt aus GET /v1/payout/status/{uuid} wider, ergänzt um ein sign-Feld zur Verifizierung.

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

Signatur verifizieren. Verwenden Sie denselben Algorithmus wie bei Zahlungs-Webhooks, signieren Sie aber mit Ihrem Payout-API-Schlüssel statt dem regulären API-Schlüssel. Entfernen Sie das Feld sign, JSON-codieren Sie den verbleibenden payload, base64-codieren Sie ihn und berechnen Sie anschließend hash_hmac('sha256', $base64, $payoutApiKey). Vergleichen Sie das Ergebnis mit der erhaltenen sign.