Webhook Confirmations
Elements callbacks keep the browser moving. Signed webhooks let your backend reconcile links after tabs close, mobile WebViews background, or networks drop. Card storage returns a method identifier but no webhook. The Pay event contract is reserved, but execution is not available.
Callbacks are UX signals
Never fulfill from a browser callback alone
onSuccess, redirect URLs, and hosted-page completion screens run in user-controlled clients. Use them to update UI and send identifiers to your server, but verify signatures and dedupe webhook event IDs before changing durable server state.Confirmation paths by flow
| Flow | Browser signal | Durable confirmation | Webhook types |
|---|---|---|---|
| Interactive Connect | onSuccess(public_token) | Your server exchanges the public token, then reconcile link.completed. connection.ready and bill.created confirm the first retrieval. | link.completedconnection.readybill.created |
| Hosted/background Connect | Hosted page completion or redirect | Use link_token.completed as the durable server-side confirmation that BillerAPI completed the background exchange and created the link. | link_token.completedconnection.readybill.created |
| Add Card | onSuccess(payment_method_id) | No money moves and no payment webhook is emitted for card storage. Persist the payment_method_id server-side; it cannot currently be used to execute a bill payment. | No payment webhook |
| Pay (unavailable) | 501 PAYMENT_EXECUTION_NOT_AVAILABLE | No payment attempt is created and no pay.* webhook is emitted in sandbox or production. | No payment webhook |
Connect reconciliation
Interactive Connect returns a public_token to the browser so your backend can exchange it. Background Connect does the exchange inside BillerAPI and emits link_token.completed. In both paths, wait for signed link and bill webhooks before assuming bill data is ready.
Ready is separate from linked
link.completed means the link exists.connection.ready and bill.created tell you the first bill retrieval has produced usable data.Add Card reconciliation
Add Card returns a tokenized payment_method_id plus display-safe metadata. That is a stored method, not a paid bill. Because there is no payment attempt, BillerAPI does not emit a pay.* webhook for Add Card by itself.
Do not infer money movement
payment_method_id for later use, but do not infer money movement or build fulfillment around unavailable Pay events.Reserved Pay outcome contract
pay.scheduledReserved contract: if Pay launches, this will mean an attempt entered processing.
pay.succeededReserved contract: if Pay launches, this will be the signed terminal paid event.
pay.failedReserved contract: if Pay launches, this will report a terminal failed attempt.
pay.escalatedReserved contract: if Pay launches, this will identify an attempt needing human review.
Payment execution is unavailable
501 PAYMENT_EXECUTION_NOT_AVAILABLE. No payment attempt or pay.* event is produced. These event names document a reserved future contract, not a testable execution path.