Einzahlung abrufen

API-Schlüssel: Payment

Liest eine Einzahlung über ihre pcd_-Kennung, in jedem Zustand. Eine Kennung aus dem Webhook payment_channel.deposit.confirming lässt sich hier sofort auflösen — Sie müssen den Inhalt eines Webhooks also nicht aufbewahren, nur um später nachschlagen zu können.

Antwort (200 OK)

{
  "id": "pcd_8ScRvL4jNq2XkB7mTfZdWu",
  "payment_channel_id": "pc_2QhKZv6mRt9WdA3nYpLbXf",
  "project_id": "prj_xFukZuAJZR06pLVBh3uwzv",
  "payment_channel_external_id": "customer-42",
  "status": "confirmed",
  "is_final": true,
  "is_test": false,
  "currency": "USDT",
  "network": "TRC20",
  "chain_id": 728126428,
  "contract_address": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
  "gross": "100",
  "fee": "1",
  "net": "99",
  "applied_fee_percent": 1.0,
  "customer_fee_percent": 0,
  "tx_hash": "9f4c1b7e30ad52c8ef6a1d84b0c39f27a5e6d138f4b90c72ae51d63b8407fc25",
  "transfer_id": "9f4c1b7e30ad52c8ef6a1d84b0c39f27a5e6d138f4b90c72ae51d63b8407fc25:41a614f803b6fd780986a42c78ec9c7f77e6ded13c:41c9f6a2b7d0138e54ca3b91f6072ed48a5c1e93b7:0",
  "source_address": "TW9s4RkAqBnLpVdX2ChYzUeGm7QfKt3NbZ",
  "destination_address": "TN3W4H6rK2ce4vX9YnFQHwKENnHjoxb3m9",
  "block_height": 68421905,
  "first_included_block_timestamp": 1767225900,
  "explorer_url": "https://tronscan.org/#/transaction/9f4c1b7e30ad52c8ef6a1d84b0c39f27a5e6d138f4b90c72ae51d63b8407fc25",
  "created_at": 1767225870,
  "updated_at": 1767225930,
  "confirmed_at": 1767225930
}

Felder

Feld	Bedeutung
id	Die Kennung der Einzahlung (pcd_…). Darüber deduplizieren Sie.
payment_channel_id, payment_channel_external_id	Der Kanal, der sie erhalten hat, und die Kennung, die Sie diesem Kanal gegeben haben.
status	confirming, reorged oder confirmed.
is_final	Nur bei confirmed auf true.
currency, network, chain_id, contract_address	Welches Token wo eingegangen ist. contract_address ist die On-Chain-Kennung des Tokens — Vertragsadresse auf EVM und Tron, Jetton-Master auf TON, SPL-Mint auf Solana.
gross, fee, net	Dezimalzeichenketten. net ist der Betrag, der Ihr Guthaben erreicht.
applied_fee_percent, customer_fee_percent	Die Sätze, die bei der Zuordnung für diese Einzahlung eingefroren wurden.
tx_hash, transfer_id, block_height	Belege aus der Chain. transfer_id ist undurchsichtig — vergleichen Sie darauf, aber zerlegen Sie den Wert nicht.
source_address	Die Adresse des Kunden, sofern die Chain eine ausweist; sonst nicht vorhanden.
destination_address	Die Kanaladresse, an der das Geld eingegangen ist.
first_included_block_timestamp	Wann die Transaktion erstmals in einem Block stand.
explorer_url	Link in den Block-Explorer, sofern es für dieses Netzwerk einen gibt.
confirmed_at	Einmalig gesetzt, sobald die Einzahlung confirmed erreicht hat.

Im Schema ist contract_address optional und bleibt nur bei einem nativen Coin leer. Kein nativer Coin gehört zu den angenommenen Assets, also trägt jede Einzahlung, die Sie lesen können, einen Wert. Für payment.contract_address gilt bei GET /v1/invoices/:id dieselbe Regel — ein Codepfad deckt beide Ressourcen ab.

Status einer Einzahlung

Status	Bedeutung	Endgültig
confirming	On-Chain gesehen, wartet auf die Bestätigungen, die dieses Netzwerk verlangt	Nein
reorged	Eine Reorganisation der Chain hat die Transaktion verdrängt	Nein
confirmed	Abgeschlossen. Der Nettobetrag ist Ihrem Guthaben gutgeschrieben	Ja

confirmed ist absorbierend: Hat eine Einzahlung diesen Zustand erreicht, holt sie nichts mehr zurück. reorged ruht, ist aber nicht endgültig — wird dieselbe Transaktion in einem späteren Block wieder aufgenommen, kehrt dieselbe Einzahlung nach confirming zurück und kann anschließend bestätigt werden. Sie behält dabei durchgehend ihre pcd_-Kennung, Sie sehen zu einer Zahlung also nie eine zweite Einzahlung.

Einen Fehlerzustand gibt es nicht. Eine Einzahlung, die verdrängt und nie wieder aufgenommen wird, bleibt schlicht auf reorged.

Geld wird festgehalten, nicht neu berechnet

applied_fee_percent und customer_fee_percent sind eine Momentaufnahme aus dem Moment der Zuordnung. Ändern Sie Ihre Konditionen danach, ändert das eine bestehende Einzahlung nicht, und ein erneutes Lesen einer alten Einzahlung liefert dieselben gross, fee und net wie eh und je.

Bei einer bestätigten Einzahlung in der Produktion werden diese drei Beträge aus der Buchung gelesen, die Ihr Guthaben erhöht hat — es sind dieselben Zahlen wie in Ihrer Abrechnung, keine Neuberechnung. Bei einem Satz von 1 % meldet eine Einzahlung über 100 USDT gross 100, fee 1 und net 99.

Beträge sind Dezimalzeichenketten, überflüssige Nullen am Ende sind abgeschnitten. Lesen Sie sie in einen Dezimaltyp ein; binäre Gleitkommazahlen verlieren in der Größenordnung von Stablecoins an Genauigkeit.

Fehler

Code	HTTP	Wann
payment_channels_disabled	503	Zahlungskanäle sind für Ihr Konto in dieser Umgebung nicht freigeschaltet.
payment_key_required	403	Die Anfrage wurde mit einem Payout-Schlüssel (rk_) signiert.
payment_channel_deposit_not_found	404	Die Kennung führt zu nichts, was diese Zugangsdaten sehen dürfen.
field_invalid_format	400	Das Pfadsegment ist keine gültige pcd_-Kennung.

Den vollständigen Katalog finden Sie unter Fehlercodes.