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.
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.