Abrufen

API-Schlüssel: Payment

Gibt den aktuellen Zustand einer Rechnung zurück. Es gilt derselbe Antwortvertrag wie bei der Rechnungserstellung; das Objekt payment erscheint, sobald Token und Netzwerk gewählt sind.

Antwort (200 OK)

{
  "invoice_id": "inv_5CcyDYmMUGtzYL10q0Iimr",
  "project_id": "prj_xFukZuAJZR06pLVBh3uwzv",
  "status": "paid",
  "is_final": true,
  "is_test": false,
  "payment_url": "https://checkout.paymos.io/invoice/inv_5CcyDYmMUGtzYL10q0Iimr",
  "order": {
    "external_id": "order-12345",
    "client_id": "customer-67890",
    "amount": "50.00",
    "currency": "USDT",
    "network": "TRC20"
  },
  "payment": {
    "currency": "USDT",
    "network": "TRC20",
    "chain_id": 728126428,
    "contract_address": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
    "expected": "50.00",
    "address": "TLfGqSVPbET2KFczh3xb12Ja2RKfMCBPgp",
    "exchange_rate": "1.000000",
    "paid": "50.00",
    "remaining": "0",
    "fee": "0.50",
    "net": "49.50",
    "transfers": [
      {
        "tx_hash": "abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
        "amount": "50.00",
        "status": "confirmed",
        "created_at": 1739280712,
        "confirmed_at": 1739280912,
        "required_confirmations": 19,
        "estimated_confirmation_at": 1739280772,
        "explorer_url": "https://tronscan.org/#/transaction/abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890"
      }
    ]
  },
  "created_at": 1739280600,
  "updated_at": 1739280912,
  "expires_at": 1739284200,
  "completed_at": 1739280912
}

Felder der Zahlung

Ist payment vorhanden, enthält es:

Feld	Typ	Beschreibung
payment.currency	Zeichenkette	Für die Zahlung gewähltes Krypto-Kürzel (etwa USDT, USDC)
payment.network	Zeichenkette	Code des Blockchain-Netzwerks (etwa ERC20, TRC20, BEP20, POLYGON, BASE, TON, SOL)
payment.chain_id	Ganzzahl	Numerische Chain-ID nach den Konventionen von EIP-155, TRON oder TON (etwa 1 für Ethereum Mainnet, 728126428 für Tron)
payment.contract_address	Zeichenkette?	Die On-Chain-Kennung des Tokens — Vertragsadresse auf EVM und Tron, Jetton-Master auf TON, SPL-Mint auf Solana. Im Schema optional, weil ein nativer Coin keine solche Kennung hat; angenommen wird jedoch kein nativer Coin, deshalb trägt das Feld auf einer echten Rechnung immer einen Wert. Dieselbe Regel nennt GET /v1/payment-channel-deposits/:id für seine eigene contract_address
payment.expected	Zeichenkette	Erwarteter Krypto-Betrag, den der Kunde senden muss
payment.address	Zeichenkette?	Einzahlungsadresse, an die der Kunde zahlt. Solange die Rechnung in awaiting_client steht, fehlt das gesamte Objekt payment in der Antwort, sodass dieses Feld bei einer offenen Rechnung nie als null auftaucht — es gibt schlicht noch kein payment zu lesen
payment.exchange_rate	Zeichenkette?	Kurs von Fiat zu Krypto, aus dem expected entstanden ist
payment.paid	Zeichenkette?	Summe der bestätigten eingehenden Transfers
payment.remaining	Zeichenkette?	Offener Betrag, den der Kunde noch senden muss (expected - paid, nie negativ). Erst vorhanden, sobald mindestens ein Transfer bestätigt wurde
payment.fee	Zeichenkette?	Plattformgebühr, entnommen aus paid
payment.net	Zeichenkette?	Betrag, der dem Händler zusteht (paid - fee)
payment.transfers	Array?	Details je Transfer — vorhanden, sobald mindestens ein On-Chain-Transfer erkannt wurde. Siehe unten.

Felder eines Transfers

Jeder Eintrag in payment.transfers[]:

Feld	Typ	Beschreibung
tx_hash	Zeichenkette	Hash der On-Chain-Transaktion (Format je Netzwerk)
amount	Zeichenkette	Übertragener Krypto-Betrag
status	Zeichenkette	confirming (wartet auf Bestätigungen) oder confirmed
created_at	Unix-Zeitstempel	Wann unsere Pipeline den Transfer erstmals in einem verarbeiteten Block gesehen hat. Uhrzeit auf unserem Server, nicht der Zeitstempel des Blocks — beide unterscheiden sich, wenn die Pipeline hinterherhing. Nutzen Sie diesen Wert (nicht das created_at der Rechnung selbst) für die Formel „verbleibende Sekunden“ weiter unten.
confirmed_at	Unix-Zeitstempel?	Wann der Transfer die erforderliche Zahl an Bestätigungen erreicht hat. null, solange er noch offen ist
required_confirmations	Ganzzahl?	Bestätigungen, die dieser Transfer für seine USD-Betragsstufe bis confirmed braucht. null bei jedem Netzwerk, das statt über eine Blockzahl über die eigene Zusage finalized abschließt — heute BNB Smart Chain, Polygon, Solana, Avalanche und Plasma. Verzweigen Sie über das null, nicht über eine Netzwerkliste: Welche Chains über Finalität bestätigen, ist betrieblich und kann sich ändern
estimated_confirmation_at	Unix-Zeitstempel?	Wann der Transfer voraussichtlich abgeschlossen ist. Auf Netzwerken mit Blockzählung wird das zum Beobachtungszeitpunkt als transfer.created_at + required_confirmations × network_block_time berechnet; auf Finalitätsnetzwerken, wo es keine Blockzahl gibt, als transfer.created_at plus die übliche Finalität dieser Chain, sodass sich trotzdem eine Wartezeit anzeigen lässt. Statisch — verschiebt sich zwischen Anfragen NICHT, bei jeder Abfrage derselbe Wert, bis der Transfer bestätigt ist (oder seine USD-Stufe wechselt). Für „verbleibende Sekunden“ rechnen Sie im Client: max(0, estimated_confirmation_at − now).
explorer_url	Zeichenkette?	Direktlink auf diese Transaktion im Block-Explorer des Netzwerks (Tronscan, Etherscan, Tonviewer und weitere). null, wenn für das Netzwerk kein öffentlicher Explorer hinterlegt ist. Kann unverändert als anklickbarer Link dargestellt werden — eine Umwandlung ist nicht nötig.

Rechnungsstatus

Jede Rechnung meldet eine Zeichenkette status. Derselbe Wert steuert die Antwort der Händler-API, den SSE-Stream des Checkouts und den Webhook-Inhalt — es gibt eine einzige Quelle der Wahrheit. Die Tabelle unten ist die Referenz je Status: wann der Wert auftritt, ob er endgültig ist und welche genaue Bedingung dahintersteht. Das Übergangsdiagramm und die beiden Wege der Erstellung stehen unter Zahlungsablauf.

Ein endgültiger Status ist final: Die Rechnung bleibt dort stehen und bewegt sich nicht mehr. Fünf Status sind endgültig — paid, paid_over, underpaid, expired, cancelled.

Status	Endgültig	Wann er gilt
awaiting_client	Nein	Der Startstatus jeder Rechnung. Token und Netzwerk sind noch nicht gewählt, deshalb existiert keine Einzahlungsadresse. Nur hier ist eine Stornierung erlaubt
awaiting_payment	Nein	Token, Netzwerk und Einzahlungsadresse stehen fest. Paymos beobachtet die Adresse auf einen eingehenden Transfer
confirming	Nein	Ein Transfer ist on-chain eingegangen und sammelt die für seine Betragsstufe erforderlichen Bestätigungen
underpaid_waiting	Nein	Weniger als der erwartete Betrag ist durch, und die Rechnung bleibt für den Rest offen. Wird nur erreicht, wenn allow_multiple_payments auf true steht
paid	Ja	Der erwartete Betrag ist vollständig durch (oder innerhalb der Toleranz für Unterzahlung des Projekts)
paid_over	Ja	Mehr als der erwartete Betrag ist durch; der gesamte Transfer wird gutgeschrieben
underpaid	Ja	Die Rechnung wurde mit Fehlbetrag geschlossen — entweder lief sie unterhalb des erwarteten Betrags ab, oder eine einzelne Zahlung blieb zurück, während allow_multiple_payments auf false stand
expired	Ja	Die Frist lief ohne Eingang ab, oder im Fiat-Weg verstrich das Zeitfenster für die Token-Auswahl, bevor ein Token gewählt wurde
cancelled	Ja	Der Händler hat die Rechnung storniert, solange sie noch in awaiting_client stand

Fehler

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