Betalingslevenscyclus

Twee vragen zijn belangrijk, en ze hebben verschillende antwoorden.

Heeft de klant betaald? Dat bepaalt of u de bestelling uitvoert. Lees outcome.

Heeft het geld mijn wallet bereikt? Dat is uw uitbetaling, en die vindt plaats nadat de bestelling is uitgevoerd. Lees settlement.

Uitvoeren op basis van outcome

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 heeft drie waarden.

outcome	Betekenis	Uitvoeren
pending	nog niet betaald, en nog niet afgerond	nee
paid	het geld van de klant is binnen	ja
failed	verlopen, geannuleerd of mislukt	nee

Dat is de hele regel. Voer uit bij paid, en niets eerder.

outcome is hetzelfde, ongeacht hoe de klant heeft betaald. Een betaling die rechtstreeks vanuit een wallet is gedaan en een betaling naar een gegenereerd depositoadres bereiken allebei paid, dus uw code heeft één tak nodig, niet twee.

isFinal vertelt u of het antwoord nog kan veranderen. outcome: pending met isFinal: false betekent: blijf wachten.

Volg daarna settlement voor uw uitbetaling

Een betaling staat op paid zodra het geld van de klant binnen is. Het geld naar uw wallet brengen is een aparte stap, en in zeldzame gevallen duurt die langer dan de betaling zelf. Dat ziet u terug in settlement:

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	Betekenis
pending	wacht op de klant
settling	betaling ontvangen, uitbetaling onderweg
delayed	uitbetaling nog bezig, wordt automatisch opnieuw geprobeerd
settled	in uw wallet
failed	uitbetaling kon niet worden voltooid, wij nemen contact met u op

delayed is geen probleem waarop u actie hoeft te ondernemen. Het wordt automatisch opnieuw geprobeerd en het geld is volledig verantwoord. failed is de enige status waarvoor iemand iets moet doen, en dan komen wij naar u toe in plaats van te wachten tot u het merkt.

Elke status heeft een message die voor mensen is geschreven, zodat u die in uw eigen dashboard kunt tonen zonder zelf de tekst te hoeven schrijven.

Hoeveel er is aangekomen: paymentState

paymentState beantwoordt een derde vraag: wat er met het geld is gebeurd, los van de vraag of de betaling is geslaagd.

paymentState	Betekenis
awaiting	er is nog niets aangekomen
underpaid	er is iets aangekomen, minder dan gefactureerd
completed	het volledige bedrag is aangekomen
overpaid_refunding	er is meer aangekomen dan gefactureerd, het overschot wordt afgehandeld
expired_refunding	verlopen met een te laag bedrag, wat is aangekomen wordt teruggestuurd

underpaid is geen mislukking. De betaling blijft open en wordt voltooid als de klant het verschil stuurt. U ontvangt een payment.underpaid-webhook wanneer dit gebeurt, en dat is het moment om de klant daarop te wijzen.

Bevestigen

Webhooks, als u die kunt ontvangen. U krijgt het te horen, in plaats van ernaar te moeten vragen. Zie Webhooks.

Polling in andere gevallen, via het statusendpoint hierboven.

Poll vanaf uw server, niet vanuit de browser. Een statusopvraging in de browser van de klant kan door de klant worden vervalst.

De onSuccess-callback van de SDK wordt geactiveerd wanneer de wallet van de klant de transactie accepteert. Op dat moment is de transactie uitgezonden, niet bevestigd. Ze kan nog mislukken, worden vervangen door een transactie met een hogere fee, of worden verwijderd. Behandel onSuccess als “de klant heeft verzonden” en bevestig apart.

Betalingen via depositoadres

Sommige betalingen worden gedaan naar een adres dat voor die ene betaling is gegenereerd, in plaats van rechtstreeks naar uw wallet te worden gestuurd. Het geld wordt daarna naar u doorgestuurd.

Dit verandert niets aan hoe u integreert. outcome gaat nog steeds naar paid, en settlement vertelt u nog steeds wanneer de uitbetaling binnenkomt. De extra stap is alleen zichtbaar in de deposit-webhookevents, die worden vermeld in Webhooks.

Het bedrag dat aankomt is niet altijd het gevraagde bedrag. Zie Overbetalingen en terugbetalingen.

Ruwe statuswaarden

status is een diagnostisch veld dat onze interne voortgang door een betaling beschrijft. U hebt het niet nodig om te integreren: outcome en settlement bevatten alles hierboven. Het wordt hier vermeld zodat u een waarde die u ziet in een ruwe API-response, een dashboardexport of een gesprek met support kunt opzoeken.

status	Gerapporteerd 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

Baseer geen logica op deze waarden. Ze beschrijven ons afwikkelingsmechanisme, ze kunnen veranderen, en alles wat u eruit nodig hebt, staat al in outcome en settlement.