POST /v1/webhook_endpoints.
For signature verification, retries and idempotent handling, see
Webhooks.
The envelope
Every event has the same outer shape.data carries the payload for that event type.
string
Unique per event. Dedupe on this: delivery is at-least-once.
checkout.succeeded | checkout.failed | checkout.step_up_required | merchant.connected
Which event this is. Branch on it to know what
data holds.test | live
Which environment produced it, so one endpoint can serve both safely.
string
When Ringup created the event, ISO 8601. Not when it was delivered.
object
The payload for this event type.
Dedupe on
event_id. Delivery is at-least-once, so the same event can arrive more than once,
and an endpoint that is not idempotent will double-fulfil an order eventually rather than never.Event types
checkout.succeeded
A charge against a Checkout Session succeeded. The money moved.string
The session that was paid.
string
The charge that paid it.
pending | succeeded | failed
Always
succeeded on this event; present so one parser handles both outcomes.number
What was actually charged, in the smallest currency unit.
string
ISO 4217, uppercase. Matches the session.
string | null
The processor’s own id for the payment, for reconciliation against their dashboard.
string
The merchant who was paid.
string | null
The merchant’s order number, and the confirmation a caller can quote back to them.
string | null
Your platform’s call id, to tie this payment to your own call logs.
object | null
The card that paid, for a receipt line. Never more than brand and last four.
apple_pay | google_pay |
Which wallet paid (
apple_pay | google_pay), when the pay page’s wallet button did. Null on a card payment. Wallet payments carry card: null: a wallet never becomes a saved card, so there is no brand or last four to report.object | null
Whatever you attached at create_checkout, echoed back untouched.
checkout.failed
A charge was declined, or the session expired without payment.reason tells you which, and last_payment_error carries the same error object the 402 returned.
string
The session that was not paid.
string | null
Null when the session expired without any attempt.
declined | expired
declined fires on a real decline; expired when the session lapsed unpaid.number
What we tried to charge, in the smallest currency unit.
string
ISO 4217, uppercase. Matches the session.
string
The merchant the payment was for.
string | null
The merchant’s order number, so you can mark the right order unpaid.
string | null
Your platform’s call id, to tie this failure to your own call logs.
apple_pay | google_pay |
Which wallet the failed attempt came from, mirroring the succeeded payload. Null on a card attempt or an expiry.
object | null
Whatever you attached at create_checkout, echoed back untouched.
object | null
The SAME error object the 402 returned, minus
request_id, which belongs to a request and not to an event. Stripe embeds the error this way on last_payment_error rather than flattening it, so one parser handles the synchronous and asynchronous paths. Null when the session merely expired: nothing was attempted, so there is no error to report.checkout.step_up_required
Screening found a positive risk signal on the caller’s number, so their saved card was not offered on this call and they were texted a payment link instead.reasons says why. Fires once per session, whichever signal found it.
string
The session whose caller must pay by link instead of with their saved card.
string
The merchant the payment was for.
string
Always
step_up on this event. Present so one parser reads it and the session field alike.array
Why, as stable codes:
ported_recently when the caller’s number changed hands inside the last seven days, attestation_C or attestation_F when the carrier’s signature on the original call was poor or failed. More than one can apply. Codes only: the underlying carrier records stay ours.A | B | C | F |
The carrier attestation grade for the original call, when it resolved.
boolean | null
True when a recent port was the cause. Null when the lookup did not resolve.
string | null
Your platform’s call id, to tie this to your own call logs.
object | null
Whatever you attached at create_checkout, echoed back untouched.
merchant.connected
A merchant finished connecting their payment processor, so their calls can now take payment.string
Ringup’s id for the merchant that just connected.
string | null
YOUR id for this merchant, echoed back, so you can join it to your own record (R15d).
string
Which processor they connected.
Next steps
Webhooks
Signatures, retries, and handling events idempotently.
Error codes
What
last_payment_error can carry on a failed checkout.