Zum Inhalt springen

API

Auf dieser Seite

Erstellen

Eine Auszahlung aus einem Token-Guthaben an ein freigegebenes Wallet erstellen, das Auszahlungsnetzwerk wählen, die Anfrage signieren und den Status verfolgen.

POST/v1/withdrawals

API-Schlüssel: Payout

Auszahlungen sind unumkehrbar, sobald die Transaktion signiert und an die Chain gesendet ist. Prüfen Sie destination_address und network, bevor Sie senden — eine Anfrage landet in created und lässt sich nur stornieren, bis die Ausführung beginnt, was schon Augenblicke später der Fall sein kann. Nach dem Senden gibt es keinen Weg zur Rückbuchung, und eine falsche Adresse bedeutet verlorene Mittel.

Eine Auszahlung wartet auf keinen Sammellauf: Die Ausführung beginnt, sobald die Anfrage angenommen ist. Wie lange der Transfer danach unterwegs ist, bestimmt das Auszahlungsnetzwerk mit seiner aktuellen Auslastung.

Anfragekörper

Parameter Typ Erforderlich Beschreibung
amount Zeichenkette Ja Auszahlungsbetrag als Dezimalzeichenkette (etwa "100.00")
currency Zeichenkette Ja Krypto-Kürzel. Auszahlbar ist jedes Asset, in dem ein Guthaben besteht; die verfügbaren Netzwerke hängen vom Asset ab (siehe Unterstützte Währungen)
network Zeichenkette Ja Code des Auszahlungsnetzwerks — TRC20, ERC20, BEP20, POLYGON, ARBITRUM, OPTIMISM, BASE, TON, AVAX, SOL oder PLASMA. Elf der dreizehn Netzwerke, die Zahlungen annehmen: NEAR und SUI nehmen nur ein, eine Adresse dort lässt sich nicht freigeben (siehe Unterstützte Währungen)
destination_address Zeichenkette Ja Ziel-Wallet-Adresse. Muss bereits in der Auszahlungs-Freigabeliste dieses Händlers stehen
external_order_id Zeichenkette Ja Ihre Auszahlungskennung (höchstens 200 Zeichen), eindeutig je Händler. Dient der Idempotenz — eine Wiederholung mit demselben Wert gibt die bestehende Auszahlung zurück, statt erneut zu senden

Beispielanfrage

{
  "amount": "100.00",
  "currency": "USDT",
  "network": "TRC20",
  "destination_address": "TN3W4H6rK2ce4vX9YnFQHwKENnHjoxb3m9",
  "external_order_id": "payout-001"
}

Codebeispiele

Jeder Reiter nutzt ein offizielles SDK mit einem Payout-Schlüssel. Signatur, Serialisierung, sichere Wiederholungen und typisierte Fehler übernimmt das SDK.

API_KEY_ID="rk_live_xxxxxxxxxxxx"
API_SECRET="sk_live_xxxxxxxxxxxx"
BODY='{"destination_address":"TN3W4H6rK2ce4vX9YnFQHwKENnHjoxb3m9","network":"TRC20","currency":"USDT","amount":"50.00","external_order_id":"payout-123"}'

TS=$(date +%s)
BODY_HASH=$(printf '%s' "$BODY" | openssl dgst -sha256 -hex | sed 's/^.* //')
SIGNATURE=$(printf '%s\n%s\n%s\n%s\n%s' "$TS" POST /v1/withdrawals '' "$BODY_HASH" \
  | openssl dgst -sha256 -hmac "$API_SECRET" -binary | base64)

curl -sS https://api.paymos.io/v1/withdrawals \
  -H "Authorization: HMAC-SHA256 $API_KEY_ID:$SIGNATURE" \
  -H "X-Request-Timestamp: $TS" \
  -H "Content-Type: application/json" \
  -d "$BODY"
import { Paymos, externalOrderId } from '@paymos/sdk';

const paymos = new Paymos({
  apiKey: process.env.PAYMOS_PAYOUT_KEY,
  apiSecret: process.env.PAYMOS_API_SECRET,
});
const withdrawal = await paymos.withdrawals.create({
  destinationAddress: 'TN3W4H6rK2ce4vX9YnFQHwKENnHjoxb3m9',
  network: 'TRC20',
  currency: 'USDT',
  amount: '50.00',
  externalOrderId: externalOrderId('payout'),
});

console.log(withdrawal.withdrawalId, withdrawal.status);
import os

from paymos import Paymos

paymos = Paymos(
    api_key=os.environ["PAYMOS_PAYOUT_KEY"],
    api_secret=os.environ["PAYMOS_API_SECRET"],
)
withdrawal = paymos.withdrawals.create(
    destination_address="TN3W4H6rK2ce4vX9YnFQHwKENnHjoxb3m9",
    network="TRC20",
    currency="USDT",
    amount="50.00",
    external_order_id="payout-001",
)

print(withdrawal["withdrawal_id"], withdrawal["status"])
<?php
use Paymos\Client;
use Paymos\ClientConfig;
use Paymos\IdempotencyKey;

$paymos = new Client(new ClientConfig(
    getenv('PAYMOS_PAYOUT_KEY'),
    getenv('PAYMOS_API_SECRET')
));
$withdrawal = $paymos->withdrawals()->create(array(
    'destination_address' => 'TN3W4H6rK2ce4vX9YnFQHwKENnHjoxb3m9',
    'network' => 'TRC20',
    'currency' => 'USDT',
    'amount' => '50.00',
    'external_order_id' => IdempotencyKey::externalOrderId('payout'),
));

echo $withdrawal['withdrawal_id'] . ' ' . $withdrawal['status'];
package main

import (
	"context"
	"fmt"
	"os"

	paymos "github.com/Paymos-labs/go-sdk/v2"
)

func main() {
	client, err := paymos.NewClient(os.Getenv("PAYMOS_PAYOUT_KEY"), os.Getenv("PAYMOS_API_SECRET"))
	if err != nil {
		panic(err)
	}
	withdrawal, err := client.Withdrawals.Create(context.Background(), paymos.CreateWithdrawalParams{
		DestinationAddress: "TN3W4H6rK2ce4vX9YnFQHwKENnHjoxb3m9",
		Network:            "TRC20",
		Currency:           "USDT",
		Amount:             "50.00",
		ExternalOrderID:    "payout-001",
	})
	if err != nil {
		panic(err)
	}
	fmt.Println(withdrawal.WithdrawalID, withdrawal.Status)
}
using Paymos;

using var paymos = new PaymosClient(
    Environment.GetEnvironmentVariable("PAYMOS_PAYOUT_KEY")!,
    Environment.GetEnvironmentVariable("PAYMOS_API_SECRET")!);

var withdrawal = await paymos.Withdrawals.CreateAsync(new CreateWithdrawalRequest(
    DestinationAddress: "TN3W4H6rK2ce4vX9YnFQHwKENnHjoxb3m9",
    Network: "TRC20",
    Currency: "USDT",
    Amount: "50.00",
    ExternalOrderId: "payout-001"));

Console.WriteLine($"{withdrawal.WithdrawalId} {withdrawal.Status}");
import io.paymos.CreateWithdrawalRequest;
import io.paymos.PaymosClient;
import io.paymos.Withdrawal;

PaymosClient paymos = new PaymosClient(
    System.getenv("PAYMOS_PAYOUT_KEY"),
    System.getenv("PAYMOS_API_SECRET"));

Withdrawal withdrawal = paymos.withdrawals.create(new CreateWithdrawalRequest(
    "TN3W4H6rK2ce4vX9YnFQHwKENnHjoxb3m9",
    "TRC20",
    "USDT",
    "50.00",
    "payout-001"));

System.out.println(withdrawal.withdrawalId() + " " + withdrawal.status());
require 'paymos'

paymos = Paymos::Client.new(
  api_key: ENV.fetch('PAYMOS_PAYOUT_KEY'),
  api_secret: ENV.fetch('PAYMOS_API_SECRET')
)
withdrawal = paymos.withdrawals.create(
  destination_address: 'TN3W4H6rK2ce4vX9YnFQHwKENnHjoxb3m9',
  network: 'TRC20',
  currency: 'USDT',
  amount: '50.00',
  external_order_id: 'payout-001'
)

puts "#{withdrawal.withdrawal_id} #{withdrawal.status}"
use paymos::{CreateWithdrawalRequest, PaymosClient};

let paymos = PaymosClient::new(
    std::env::var("PAYMOS_PAYOUT_KEY")?,
    std::env::var("PAYMOS_API_SECRET")?,
)?;
let withdrawal = paymos
    .withdrawals()
    .create(&CreateWithdrawalRequest {
        destination_address: "TN3W4H6rK2ce4vX9YnFQHwKENnHjoxb3m9".to_owned(),
        network: "TRC20".to_owned(),
        currency: "USDT".to_owned(),
        amount: "50.00".to_owned(),
        external_order_id: "payout-001".to_owned(),
    })
    .await?;

println!("{} {}", withdrawal.withdrawal_id, withdrawal.status);

Antwort (201 Created / 200 bei idempotenter Übereinstimmung)

{
  "withdrawal_id": "wdr_2M8K6Q4P9X1Z7A3B",
  "external_order_id": "payout-001",
  "status": "created",
  "is_final": false,
  "is_test": true,
  "amount": "100.00",
  "currency": "USDT",
  "network": "TRC20",
  "destination_address": "TN3W4H6rK2ce4vX9YnFQHwKENnHjoxb3m9",
  "created_at": 1739289600
}

Felder der Antwort

Feld Typ Beschreibung
withdrawal_id Zeichenkette Auszahlungskennung mit Präfix (wdr_...)
external_order_id Zeichenkette Ihre eigene Auszahlungsreferenz, aus der Anfrage zurückgespiegelt
status Zeichenkette Auszahlungsstatus (snake_case — siehe Auszahlungsstatus)
is_final Boolescher Wert true, sobald die Auszahlung einen Endzustand erreicht hat (completed, failed, cancelled)
is_test Boolescher Wert true bei Sandbox-Auszahlungen
amount Zeichenkette Auszahlungsbetrag
fee Zeichenkette? Pauschale Auszahlungsgebühr je Token, aus dem Token-Katalog der Plattform ermittelt, im selben Asset wie amount. Je Token fest statt als Live-Gas-Angabe — sie liegt unter den Netzwerkkosten dieses Wegs und enthält keine Paymos-Provision. Entfällt, wenn keine Gebühr anfällt
currency Zeichenkette Krypto-Kürzel
network Zeichenkette Code des Blockchain-Netzwerks
destination_address Zeichenkette Zieladresse
tx_hash Zeichenkette? On-Chain-Hash des Transfers, der die Auszahlung abgewickelt hat. Wird erst gesetzt, wenn status auf completed steht
explorer_url Zeichenkette? Direktlink auf tx_hash im Block-Explorer des Netzwerks (etwa Tronscan, Etherscan). Wird nur gesetzt, wenn tx_hash gesetzt ist und für das Netzwerk ein Explorer hinterlegt ist. Unverändert als anklickbaren Link darstellen
created_at Ganzzahl Unix-Zeitstempel, Sekunden
completed_at Ganzzahl? Unix-Zeitstempel, Sekunden. Wird gesetzt, sobald die Auszahlung abgeschlossen ist
failed_at Ganzzahl? Unix-Zeitstempel, Sekunden. Wird gesetzt, sobald die Auszahlung fehlschlägt
cancelled_at Ganzzahl? Unix-Zeitstempel, Sekunden. Wird gesetzt, sobald die Auszahlung storniert wird

Idempotenz

Senden Sie bei einer Auszahlung immer eine external_order_id. Eine Wiederholung desselben Aufrufs mit derselben external_order_id gibt die bestehende Auszahlung zurück — niemals einen zweiten Transfer. Der Antwortstatus ist 200 OK (ohne Location-Header) bei einer idempotenten Übereinstimmung und 201 Created bei einer neuen Auszahlung.

Das ist Ihr Sicherheitsnetz gegen wackelige Netzwerke, abgestürzte Worker und Wiederholungsschleifen. Verwenden Sie dieselbe Kennung für dieselbe Auszahlung und eine neue Kennung für eine neue.

Fehler

Den vollständigen Katalog finden Sie unter Fehlercodes. Die type-URI in jeder Fehlerantwort verweist direkt auf die passende Zeile.