Auf dieser Seite
Auflisten
Rechnungen mit strengen Status- und Datumsfiltern auflisten, per Cursor vorwärts blättern und Ergebnisse ohne doppelte Seiten abgleichen.
API-Schlüssel: Payment
Gibt ausschließlich Rechnungen des authentifizierten Händlers zurück, in der Umgebung des Schlüssels und den für ihn sichtbaren Projekten. Die Sortierung ist created_at DESC, danach invoice_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 128 Zeichen. |
project_id |
Zeichenkette | — | Eine für diesen Payment-Schlüssel sichtbare ID mit Präfix prj_…. |
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. Ein Name außerhalb der Tabelle ist ein 400; ein Filter, den die API angenommen hat, ist damit auch ein Filter, den sie angewendet hat, und ein Tippfehler verbreitert Ihr Ergebnis nicht hinter Ihrem Rücken.
Die Tabelle ist zugleich der gesamte Filterumfang. Volltextsuche, ein Sortierparameter und Offset-Paginierung gibt es auf keiner Liste der Merchant-API.
Beispiel
GET /v1/invoices?limit=50&status=paid&status=paid_over&created_from=1767225600 HTTP/1.1
Host: api.paymos.io
Authorization: HMAC-SHA256 pk_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="pk_live_xxxxxxxxxxxx"
API_SECRET="sk_live_xxxxxxxxxxxx"
QUERY="?status=paid&limit=50"
TS=$(date +%s)
# No body: the hash slot is the EMPTY STRING, not sha256("") — its fixed
# e3b0c442… digest signs a different payload and the request is rejected. The
# query keeps its leading "?" exactly as transmitted.
SIGNATURE=$(printf '%s\n%s\n%s\n%s\n%s' "$TS" GET /v1/invoices "$QUERY" '' \
| openssl dgst -sha256 -hmac "$API_SECRET" -binary | base64)
curl -sS "https://api.paymos.io/v1/invoices$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_API_KEY,
apiSecret: process.env.PAYMOS_API_SECRET,
});
const page = await paymos.invoices.list({ status: ['paid', 'paid_over'], limit: 50 });
for await (const invoice of paymos.invoices.iterate({ status: ['paid'] }, 10)) {
console.log(invoice.invoiceId);
}
import os
from paymos import Paymos
paymos = Paymos(
api_key=os.environ["PAYMOS_API_KEY"],
api_secret=os.environ["PAYMOS_API_SECRET"],
)
page = paymos.invoices.list(status=["paid", "paid_over"], limit=50)
for invoice in paymos.invoices.iterate(10, status=["paid"]):
print(invoice["invoice_id"])
<?php
use Paymos\Client;
use Paymos\ClientConfig;
$paymos = new Client(new ClientConfig(
getenv('PAYMOS_API_KEY'),
getenv('PAYMOS_API_SECRET')
));
$page = $paymos->invoices()->listPage(array(
'status' => array('paid', 'paid_over'),
'limit' => 50,
));
foreach ($paymos->invoices()->iterate(array('status' => array('paid')), 10) as $invoice) {
echo $invoice['invoice_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_API_KEY"), os.Getenv("PAYMOS_API_SECRET"))
if err != nil {
panic(err)
}
page, err := client.Invoices.List(context.Background(), paymos.InvoiceListParams{
Status: []paymos.InvoiceStatus{paymos.InvoicePaid, paymos.InvoicePaidOver},
Limit: 50,
})
if err != nil {
panic(err)
}
fmt.Println(len(page.Items), page.NextCursor)
iter := paymos.NewInvoiceIterator(client.Invoices, paymos.InvoiceListParams{
Status: []paymos.InvoiceStatus{paymos.InvoicePaid},
}, 10)
for {
invoice, ok, err := iter.Next(context.Background())
if err != nil {
panic(err)
}
if !ok {
break
}
fmt.Println(invoice.InvoiceID)
}
}
using Paymos;
using var paymos = new PaymosClient(
Environment.GetEnvironmentVariable("PAYMOS_API_KEY")!,
Environment.GetEnvironmentVariable("PAYMOS_API_SECRET")!);
var page = await paymos.Invoices.ListAsync(new InvoiceListOptions(
Status: [InvoiceStatus.Paid, InvoiceStatus.PaidOver],
Limit: 50));
await foreach (var invoice in paymos.Invoices.IterateAsync(
new InvoiceListOptions(Status: [InvoiceStatus.Paid]), maxPages: 10))
{
Console.WriteLine(invoice.InvoiceId);
}
import io.paymos.InvoiceListItem;
import io.paymos.InvoiceListOptions;
import io.paymos.InvoiceStatus;
import io.paymos.Page;
import io.paymos.PaymosClient;
import java.util.List;
PaymosClient paymos = new PaymosClient(
System.getenv("PAYMOS_API_KEY"),
System.getenv("PAYMOS_API_SECRET"));
Page<InvoiceListItem> page = paymos.invoices.list(InvoiceListOptions.builder()
.status(List.of(InvoiceStatus.PAID, InvoiceStatus.PAID_OVER))
.limit(50)
.build());
for (InvoiceListItem invoice : paymos.invoices.iterate(
InvoiceListOptions.builder().status(List.of(InvoiceStatus.PAID)).build(), 10)) {
System.out.println(invoice.invoiceId());
}
require 'paymos'
paymos = Paymos::Client.new(
api_key: ENV.fetch('PAYMOS_API_KEY'),
api_secret: ENV.fetch('PAYMOS_API_SECRET')
)
page = paymos.invoices.list(status: ['paid', 'paid_over'], limit: 50)
paymos.invoices.each(max_pages: 10, status: ['paid']) do |invoice|
puts invoice.invoice_id
end
use paymos::{InvoiceListParams, InvoiceStatus, PaymosClient};
let paymos = PaymosClient::new(
std::env::var("PAYMOS_API_KEY")?,
std::env::var("PAYMOS_API_SECRET")?,
)?;
let page = paymos
.invoices()
.list(&InvoiceListParams {
status: Some(vec![InvoiceStatus::Paid, InvoiceStatus::PaidOver]),
limit: Some(50),
..Default::default()
})
.await?;
println!("{} items, next_cursor={:?}", page.items.len(), page.next_cursor);
let mut pager = paymos.invoices().pager(
InvoiceListParams { status: Some(vec![InvoiceStatus::Paid]), ..Default::default() },
Some(10),
)?;
while let Some(invoice) = pager.next().await? {
println!("{}", invoice.invoice_id);
}
Antwort (200 OK)
{
"items": [
{
"invoice_id": "inv_74BPZFhr9qy9Uz2fbRkdJX",
"project_id": "prj_7gK2mR9xQ4vN8cT1bY5dL3",
"external_order_id": "order-1042",
"client_id": "customer-42",
"status": "paid",
"is_final": true,
"is_test": false,
"amount": "49.95",
"currency": "USDT",
"network": "TRC20",
"created_at": 1767225600,
"expires_at": 1767227400,
"completed_at": 1767225908
}
],
"next_cursor": "CfDJ8JvN…"
}
Der Listeneintrag ist bewusst knapp gehalten. Für Zahlungen, Transfers, Einzahlungsadresse und Checkout-Details nutzen Sie Rechnung abrufen. Die Antwort trägt Cache-Control: private, no-store.
Regeln der Seitennavigation
- Es gibt weder Seitenzahl noch
total_count: Folgen Sienext_cursor, bis ernullist. - Der Cursor ist undurchsichtig, gegen Manipulation geschützt und läuft nach 24 Stunden ab.
- Er ist an die Ressource der Rechnungen und die exakten Filter gebunden. Lassen Sie die Filter zwischen den Seiten unverändert;
limitdarf sich ändern. - Ein fehlender oder letzter Cursor wird durch
next_cursor: nulldargestellt. - Ist der Cursor ungültig, abgelaufen, auf einer anderen Ressource verwendet oder mit anderen Filtern kombiniert, beginnen Sie ohne Cursor von vorn.
Fehler
Ein Payout-Schlüssel (rk_) wird mit 403 payment_key_required abgewiesen. Ungültige Filter liefern ein feldbezogenes 400; ein ungültiger Cursor liefert 400 pagination_cursor_invalid. Eine project_id außerhalb des Geltungsbereichs des Schlüssels liefert 404, ohne preiszugeben, ob sie existiert. Siehe Fehlercodes.