Zahlungslebenszyklus

Zwei Fragen sind wichtig, und sie haben unterschiedliche Antworten.

Hat der Kunde bezahlt? Davon hängt ab, ob Sie die Bestellung ausführen. Lesen Sie outcome.

Ist das Geld in meiner Wallet angekommen? Das ist Ihre Auszahlung, und sie erfolgt nach der Ausführung der Bestellung. Lesen Sie settlement.

Bestellungen anhand von outcome ausführen

curl https://hub.stablezact.com/api/v1/payments/PAYMENT_UUID/status \
  -H "X-Public-Key: pk_your_public_key"

{
  "success": true,
  "payment": {
    "paymentId": "e6c1…",
    "outcome": "paid",
    "isFinal": true,
    "amount": "50.00",
    "amountReceived": "50.00",
    "currency": "USDC",
    "network": "Base",
    "transactionHash": "0x…"
  }
}

outcome hat drei Werte.

outcome	Bedeutung	Ausführen
pending	noch nicht bezahlt und noch nicht abgeschlossen	nein
paid	das Geld des Kunden ist eingegangen	ja
failed	abgelaufen, storniert oder fehlgeschlagen	nein

Das ist die ganze Regel. Führen Sie die Bestellung bei paid aus, und nicht früher.

outcome ist dasselbe, unabhängig davon, wie der Kunde bezahlt hat. Eine Zahlung direkt aus einer Wallet und eine Zahlung an eine generierte Einzahlungsadresse erreichen beide paid, Ihr Code braucht also einen Zweig, nicht zwei.

isFinal gibt an, ob sich die Antwort noch ändern kann. outcome: pending mit isFinal: false bedeutet: weiter warten.

Dann settlement für Ihre Auszahlung beobachten

Eine Zahlung zeigt paid, sobald das Geld des Kunden eingegangen ist. Es in Ihre Wallet zu bringen, ist ein separater Schritt, und in seltenen Fällen dauert er länger als die Zahlung selbst. In settlement wird das sichtbar:

curl https://hub.stablezact.com/api/v1/payments/PAYMENT_UUID \
  -H "X-Public-Key: pk_your_public_key"

{
  "success": true,
  "payment": {
    "settlement": {
      "state": "settled",
      "message": "Paid out to your wallet."
    }
  }
}

state	Bedeutung
pending	wartet auf den Kunden
settling	Zahlung eingegangen, Auszahlung unterwegs
delayed	Auszahlung läuft noch, wird automatisch erneut versucht
settled	in Ihrer Wallet
failed	Auszahlung konnte nicht abgeschlossen werden, wir kontaktieren Sie

delayed ist kein Problem, bei dem Sie handeln müssen. Die Auszahlung wird automatisch erneut versucht, und das Geld ist erfasst. failed ist der einzige Zustand, bei dem jemand eingreifen muss, und wir kommen auf Sie zu, statt darauf zu warten, dass Sie es bemerken.

Jeder Zustand enthält eine message, die für Menschen geschrieben ist. So können Sie sie in Ihrem eigenen Dashboard anzeigen, ohne den Text selbst schreiben zu müssen.

Wie viel angekommen ist: paymentState

paymentState beantwortet eine dritte Frage: was mit dem Geld passiert ist, im Unterschied dazu, ob die Zahlung erfolgreich war.

paymentState	Bedeutung
awaiting	es ist noch nichts angekommen
underpaid	ein Teil ist angekommen, weniger als der Rechnungsbetrag
completed	der volle Betrag ist angekommen
overpaid_refunding	mehr als der Rechnungsbetrag ist angekommen, der Überschuss wird bearbeitet
expired_refunding	unterbezahlt abgelaufen, der angekommene Betrag wird zurückgegeben

underpaid ist kein Fehlschlag. Die Zahlung bleibt offen und wird abgeschlossen, wenn der Kunde die Differenz sendet. Sie erhalten einen payment.underpaid-Webhook, wenn das eintritt, und das ist der richtige Moment, den Kunden darauf hinzuweisen.

Bestätigen

Webhooks, wenn Sie sie empfangen können. Sie werden benachrichtigt, statt nachzufragen. Siehe Webhooks.

Polling, andernfalls, über den oben genannten Status-Endpunkt.

Fragen Sie von Ihrem Server ab, nicht aus dem Browser. Ein Statusabruf im Browser des Kunden kann vom Kunden gefälscht werden.

Der onSuccess-Callback des SDK wird ausgelöst, wenn die Wallet des Kunden die Transaktion akzeptiert. In diesem Moment wurde die Transaktion gesendet, aber nicht bestätigt. Sie kann noch fehlschlagen, durch eine Transaktion mit höherer Gebühr ersetzt oder verworfen werden. Behandeln Sie onSuccess als „der Kunde hat übermittelt“ und bestätigen Sie separat.

Zahlungen über Einzahlungsadressen

Manche Zahlungen gehen an eine Adresse, die für genau diese eine Zahlung generiert wurde, statt direkt an Ihre Wallet. Das Geld wird dann an Sie weitergeleitet.

An Ihrer Integration ändert das nichts. outcome wechselt weiterhin zu paid, und settlement zeigt weiterhin an, wann die Auszahlung eingeht. Der zusätzliche Schritt ist nur in den Webhook-Ereignissen für Einzahlungen sichtbar, die unter Webhooks aufgeführt sind.

Der Betrag, der ankommt, entspricht nicht immer dem angeforderten Betrag. Siehe Überzahlungen und Rückerstattungen.

Rohe Statuswerte

status ist ein Diagnosefeld, das unseren internen Fortschritt bei einer Zahlung beschreibt. Für die Integration brauchen Sie es nicht: outcome und settlement enthalten alles oben Beschriebene. Es ist hier aufgeführt, damit ein Wert, der in einer rohen API-Antwort, einem Dashboard-Export oder einem Support-Gespräch auftaucht, nachgeschlagen werden kann.

status	Gemeldet als
pending	outcome: pending
completed	outcome: paid
sweeping	outcome: paid, settlement: settling
swept	outcome: paid, settlement: settled
sweep_failed	outcome: paid, settlement: failed
expired	outcome: failed
cancelled	outcome: failed
failed	outcome: failed

Verzweigen Sie nicht anhand dieser Werte. Sie beschreiben unsere Auszahlungsmechanik, können sich ändern, und alles, was Sie daraus brauchen, steht bereits in outcome und settlement.