Zum Inhalt springen

API

Auf dieser Seite

Auflisten

Auszahlungen mit strengen Filtern und vorwärts gerichteter Cursor-Navigation auflisten, Zielnetzwerke prüfen und die Transferhistorie verlässlich abgleichen.

GET/v1/withdrawals

API-Schlüssel: Payout

Gibt ausschließlich Auszahlungen des authentifizierten Händlers zurück, die in der Umgebung des Schlüssels angelegt wurden. Die Sortierung ist created_at DESC, danach withdrawal_id DESC.

Query-Parameter

Parameter Typ Standard Beschreibung
limit Ganzzahl 20 Seitengröße von 1 bis 100.
cursor Zeichenkette Undurchsichtiger next_cursor aus der vorherigen Antwort.
status Zeichenkette Exakter Status in snake_case. Wiederholen Sie den Parameter, um mehrere Status zu treffen; senden Sie keinen kommagetrennten Wert.
external_order_id Zeichenkette Exakte externe Bestellnummer, bis zu 200 Zeichen.
created_from Unix-Sekunden Untere Grenze für created_at, einschließlich.
created_to Unix-Sekunden Obere Grenze für created_at, ausschließlich. Muss später liegen als created_from.

Unbekannte Parameter, wiederholte skalare Parameter, doppelte Status und falsche Groß- und Kleinschreibung im Enum werden abgewiesen, statt still ignoriert zu werden.

Beispiel

GET /v1/withdrawals?limit=20&status=created&status=pending_review HTTP/1.1
Host: api.paymos.io
Authorization: HMAC-SHA256 rk_live_…:…
X-Request-Timestamp: 1767225660

Codebeispiele

Jeder Reiter nutzt das offizielle SDK der jeweiligen Sprache. Signatur, Serialisierung, sichere Wiederholungen und typisierte Fehler übernimmt das SDK.

API_KEY_ID="rk_live_xxxxxxxxxxxx"
API_SECRET="sk_live_xxxxxxxxxxxx"
QUERY="?status=created&limit=20"

TS=$(date +%s)
# No body: the hash slot is the EMPTY STRING, not sha256("").
SIGNATURE=$(printf '%s\n%s\n%s\n%s\n%s' "$TS" GET /v1/withdrawals "$QUERY" '' \
  | openssl dgst -sha256 -hmac "$API_SECRET" -binary | base64)

curl -sS "https://api.paymos.io/v1/withdrawals$QUERY" \
  -H "Authorization: HMAC-SHA256 $API_KEY_ID:$SIGNATURE" \
  -H "X-Request-Timestamp: $TS"
import { Paymos } from '@paymos/sdk';

const paymos = new Paymos({
  apiKey: process.env.PAYMOS_PAYOUT_KEY,
  apiSecret: process.env.PAYMOS_API_SECRET,
});

const page = await paymos.withdrawals.list({ status: ['created', 'pending_review'], limit: 20 });

for await (const withdrawal of paymos.withdrawals.iterate({ status: ['completed'] }, 10)) {
  console.log(withdrawal.withdrawalId);
}
import os

from paymos import Paymos

paymos = Paymos(
    api_key=os.environ["PAYMOS_PAYOUT_KEY"],
    api_secret=os.environ["PAYMOS_API_SECRET"],
)

page = paymos.withdrawals.list(status=["created", "pending_review"], limit=20)

for withdrawal in paymos.withdrawals.iterate(10, status=["completed"]):
    print(withdrawal["withdrawal_id"])
<?php
use Paymos\Client;
use Paymos\ClientConfig;

$paymos = new Client(new ClientConfig(
    getenv('PAYMOS_PAYOUT_KEY'),
    getenv('PAYMOS_API_SECRET')
));

$page = $paymos->withdrawals()->listPage(array(
    'status' => array('created', 'pending_review'),
    'limit' => 20,
));

foreach ($paymos->withdrawals()->iterate(array('status' => array('completed')), 10) as $withdrawal) {
    echo $withdrawal['withdrawal_id'] . PHP_EOL;
}
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)
	}

	page, err := client.Withdrawals.List(context.Background(), paymos.WithdrawalListParams{
		Status: []paymos.WithdrawalStatus{paymos.WithdrawalCreated, paymos.WithdrawalPendingReview},
		Limit:  20,
	})
	if err != nil {
		panic(err)
	}
	fmt.Println(len(page.Items), page.NextCursor)

	iter := paymos.NewWithdrawalIterator(client.Withdrawals, paymos.WithdrawalListParams{
		Status: []paymos.WithdrawalStatus{paymos.WithdrawalCompleted},
	}, 10)
	for {
		withdrawal, ok, err := iter.Next(context.Background())
		if err != nil {
			panic(err)
		}
		if !ok {
			break
		}
		fmt.Println(withdrawal.WithdrawalID)
	}
}
using Paymos;

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

var page = await paymos.Withdrawals.ListAsync(new WithdrawalListOptions(
    Status: [WithdrawalStatus.Created, WithdrawalStatus.PendingReview],
    Limit: 20));

await foreach (var withdrawal in paymos.Withdrawals.IterateAsync(
    new WithdrawalListOptions(Status: [WithdrawalStatus.Completed]), maxPages: 10))
{
    Console.WriteLine(withdrawal.WithdrawalId);
}
import io.paymos.Page;
import io.paymos.PaymosClient;
import io.paymos.Withdrawal;
import io.paymos.WithdrawalListOptions;
import io.paymos.WithdrawalStatus;

import java.util.List;

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

Page<Withdrawal> page = paymos.withdrawals.list(WithdrawalListOptions.builder()
    .status(List.of(WithdrawalStatus.CREATED, WithdrawalStatus.PENDING_REVIEW))
    .limit(20)
    .build());

for (Withdrawal withdrawal : paymos.withdrawals.iterate(
        WithdrawalListOptions.builder().status(List.of(WithdrawalStatus.COMPLETED)).build(), 10)) {
    System.out.println(withdrawal.withdrawalId());
}
require 'paymos'

paymos = Paymos::Client.new(
  api_key: ENV.fetch('PAYMOS_PAYOUT_KEY'),
  api_secret: ENV.fetch('PAYMOS_API_SECRET')
)

page = paymos.withdrawals.list(status: ['created', 'pending_review'], limit: 20)

paymos.withdrawals.each(max_pages: 10, status: ['completed']) do |withdrawal|
  puts withdrawal.withdrawal_id
end
use paymos::{PaymosClient, WithdrawalListParams, WithdrawalStatus};

let paymos = PaymosClient::new(
    std::env::var("PAYMOS_PAYOUT_KEY")?,
    std::env::var("PAYMOS_API_SECRET")?,
)?;

let page = paymos
    .withdrawals()
    .list(&WithdrawalListParams {
        status: Some(vec![WithdrawalStatus::Created, WithdrawalStatus::PendingReview]),
        limit: Some(20),
        ..Default::default()
    })
    .await?;
println!("{} items, next_cursor={:?}", page.items.len(), page.next_cursor);

let mut pager = paymos.withdrawals().pager(
    WithdrawalListParams { status: Some(vec![WithdrawalStatus::Completed]), ..Default::default() },
    Some(10),
)?;
while let Some(withdrawal) = pager.next().await? {
    println!("{}", withdrawal.withdrawal_id);
}

Antwort (200 OK)

{
  "items": [
    {
      "withdrawal_id": "wdr_6Qm2fK8xR4vN7cT1bY9dL5",
      "external_order_id": "payout-1042",
      "status": "completed",
      "is_final": true,
      "is_test": false,
      "amount": "100.00",
      "fee": "1.00",
      "currency": "USDT",
      "network": "TRC20",
      "destination_address": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
      "created_at": 1767225600,
      "completed_at": 1767226120
    }
  ],
  "next_cursor": null
}

Der Listeneintrag ist bewusst knapp gehalten und legt weder Transaktions-Hashes noch Interna der Ausführung offen. Die vollständige Ressource liefert Auszahlung abrufen. Die Antwort trägt Cache-Control: private, no-store.

Regeln der Seitennavigation

  • Es gibt weder Seitenzahl noch total_count: Folgen Sie next_cursor, bis er null ist.
  • Der Cursor ist undurchsichtig, gegen Manipulation geschützt und läuft nach 24 Stunden ab.
  • Er ist an die Ressource der Auszahlungen und die exakten Filter gebunden. Lassen Sie die Filter zwischen den Seiten unverändert; limit darf sich ändern.
  • Ein fehlender oder letzter Cursor wird durch next_cursor: null dargestellt.
  • Ist der Cursor ungültig, abgelaufen, auf einer anderen Ressource verwendet oder mit anderen Filtern kombiniert, beginnen Sie ohne Cursor von vorn.

Fehler

Ein Payment-Schlüssel (pk_) wird mit 403 payout_key_required abgewiesen. Ungültige Filter liefern ein feldbezogenes 400; ein ungültiger Cursor liefert 400 pagination_cursor_invalid. Siehe Fehlercodes.