Hooks & events
Payment webhooks, returns and settlement reconciliation
Configure exact callbacks and distinguish signed notifications, authenticated returns and safe billing review.
About 3 min read
On this page
Callback routes
Use the exact HTTPS callback displayed for the saved connection. Replace no generated identifiers and do not reuse another merchant's secret. The invoice's stored seller determines its canonical payment context; shared storefronts use that saved account's central callback.
| Route | Actual purpose |
|---|---|
POST /hooks/payments/{connection-public-id} |
Provider notification verification and idempotent allocation. |
GET /hooks/payments/{connection-public-id} |
Newer optional provider endpoint challenge only when implemented; no settlement. |
GET or POST /payments/{connection-public-id}/return |
Newer signed, expiring provider return context for supported modules; untrusted locator fields never authorise payment. |
GET /account/payments/{attempt-uuid}/hosted |
Newer authenticated existing-attempt bridge/form handoff; not a public payment creation API. |
GET /account/invoices/{invoice-public-id}/payment-methods |
Newer read-only provider method preview where implemented. |
The optional routes/contracts require their matching source/core release; the original licensed release must not be assumed to contain every newer payment feature.
Verify actual funds
The module authenticates the raw notification with its provider-specific scheme, account/environment and replay/freshness rules. It reads the provider's authoritative final state where required, then returns a VerifiedPayment containing a stable event ID, attempt ID, external payment reference, exact amount/currency and checkout binding. The core matches the saved invoice, connection, seller and outstanding attempt before recording funds.
Authorization-only, partially captured, pending, refunded or mismatched results are not full settlement. A browser message or success URL is navigation/locator data. Provider-specific manuals define the required final state; for example Adyen requires captured CAPTURE evidence and eWAY uses authenticated AccessCode/transaction readback.
Duplicate and batch behavior
Webhook events retain a stable provider event identity and body hash. Exact retries do not duplicate the ledger. Conflicting replay or an otherwise verified event that cannot be allocated is rejected/held for billing review. BatchPaymentWebhook must fully verify one delivery before returning at most 250 distinct settlements; an unverified partial batch must not be silently accepted.
A module may implement a bounded provider-specific receipt acknowledgement only after verified handling. A GET endpoint challenge is not an authentication bypass for POST notifications. Keep raw secrets and customer payloads out of public logs.
Reconcile an uncertain checkout
Use the protected billing reconciliation action with payments.record, current password confirmation and the original attempt. Only modules implementing CheckoutReconciliation supply that capability. A provider-confirmed terminal unpaid state may close an attempt under its guards; abandoning a browser tab or a still-payable state does not. Review the provider before creating a replacement payment or accepting a bank reference.