Zum Inhalt springen

API

Auf dieser Seite

Auflisten

Rechnungen mit strengen Status- und Datumsfiltern auflisten, per Cursor vorwärts blättern und Ergebnisse ohne doppelte Seiten abgleichen.

GET/v1/invoices

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