Skip to main content
Read the listener contract before using these identities. Availability depends on checkout configuration, donor state, and layout. Optional controls have no hook until they render; adding a hook does not enable a feature.

​
Observation paths

input, blur, change, and click refer to native browser events observed through a capture listener inside the checkout document. selection and clear are wegive:checkout-interaction signals. For the three VGS card fields, focus and blur are provider callbacks delivered through that same bridge. Native focus and blur describe focus movement, not proof of an edit. The approval bridge reports an accepted provider callback, not a successful donation. Wallet support depends on the actual component path:
  • PayPal: payment-choice hooks exist in both portals/layouts. The native wallet component exposes payment-paypal-approval with an approval signal; saved already-authorized wallets need not produce a new approval. PayPal button paths outside the native wallet component do not expose this same dedicated approval bridge. Their stepper addedOtherPaymentType event is an alternative-payment continuation, not a universal PayPal approval event, and may include Venmo.
  • Apple Pay: V2’s native wallet button exposes payment-apple-pay click. Stripe-hosted payment-request buttons in either portal do not expose an equivalent public click bridge; V1 has no dedicated Apple Pay hook. Private wallet-sheet inputs are not exposed.
  • Google Pay: the supported approval bridge and V2 native charge-button click cover their respective paths. Validate real provider authorization separately from observing these hooks; a hook alone does not certify wallet authorization.
Use selection for a committed custom-selector choice; its opening click or internal search input is not a selection. In V1, custom checkboxes and payment preferences use selection; V2 native checkboxes use change. Native input/change can occur repeatedly and must not be counted again as a custom selection.

​
Context and repeated controls

  • Addresses use mailing or billing context. Addresses inside an explicitly scoped account/payment dialog or custom question include that parent context, such as payment-dialog.billing or custom-question.
  • Custom-question roots use the question definition ID as data-checkout-instance; their nested field controls add custom-question context. A checkbox/radio answer group is one compound field. Address, phone, and V1 date descendants retain the question definition ID. Answers and display labels are never identities.
  • Allocation fields use the designation ID as their instance. Preset amount and frequency options use their configured amount/frequency, not a donor’s free-entry amount. Configured information links use their stable configuration slot (1, 2, or 3).
  • Authentication/account editing can add login, password-reset, account-create, or update-details context. Use the checkout scope plus control/context/instance together; do not require only one matching element in the document.

​
Supported controls

“Both” means stepper and single-page. A row describes an available control, not a guarantee that every checkout configuration renders it. Native inputs also retain ordinary focus/change behavior where the browser emits it.

​
Field variants and limitations

  • address-region is a custom state selector for US addresses and a text field for other countries. address-street-2 currently appears in V2 checkout; V1’s shared address component also supplies the hook when its optional second line is enabled; current V1 checkout layouts do not enable that optional line.
  • custom-question supports text, phone/number, email, choices, radio, select, file, address, date, time, and toggle presentations. V2 additionally supports static/live autocomplete; V1 does not render autocomplete type 12. Use native input/blur for ordinary text, native change for files and native choices, and the selection bridge for component-only selections. V1’s desktop date picker uses date; its mobile native date input retains custom-question. V2 retains custom-question. Optional clearing has a custom-question-clear button. V1 question clearing and V2 autocomplete clearing also emit clear on the compound question; file clearing in V2 uses the native clear-button click.
  • donation-amount-preset is a button in the grid/list presentation. V1’s dropdown presentation also supplies a committed selection signal. V2’s dropdown opener has donation-amount-preset-open, and its options use donation-amount-preset.
  • designation-open in V2 additionally emits clear when the single-page selection is cleared. It does not mean the picker was opened.
  • V1 single-page dedication uses dedication-enabled; its stepper uses dedication-open. V1 bank microdeposit verification currently appears only in stepper checkout; V2 supports both layouts.
  • payment-continue includes add/update payment dialog submit actions as well as stepper progression. An observed click does not prove that validation or payment succeeded.
  • V1 card-security-help is a desktop help control. information-continue appears only when mobile information is configured as a step. Receipt controls follow the portal’s desktop/mobile visibility rules.
  • Hosted card fields expose SDK focus/blur only. Card values, keystrokes, provider-sheet contents, passwords, answers, and donor contact data are never copied into bridge payloads. Selecting an address autocomplete suggestion emits selection on address-street; manual address entry uses the native paths above. Real Google suggestion selection has been verified in both portals and layouts.
  • Checking/savings controls and thank-you story/account-password forms are not created by this hook API. In-checkout password and OTP entry do have login-password and login-verification-code hooks in both portals/layouts. Their values are excluded from tracking signals. Dedication uses a single dedication-name field rather than separate first/last-name inputs. Conversion prompt visibility can be observed through its hook markers as described in the listener guide; customer terminology does not add a separate prompt feature.