Payment Widgets

Payment Widgets add a payment collection experience to a Page. Use them when visitors need to pay for a product, service, registration, booking, or another transaction as part of a Project workflow.

A Payment Widget provides the payment interface on the Page and uses a configured payment provider connection. Provider account setup, credentials, test or live connection configuration, currency, and other account-specific details are managed under Integrations.

This page explains how to place and configure Payment Widgets in the Page Editor, supply payment amounts, coordinate surrounding Page Flow behavior, and test payment experiences. It does not replace payment provider configuration or trusted transaction processing.

When to Use Payment Widgets

Use a Payment Widget when an application needs to:

• Collect a fixed payment, such as an event registration fee or service charge.
• Collect a payment whose amount is determined by the visitor's selections or Project data.
• Include payment as one step in a larger registration, order, or booking workflow.
• Request a shipping address as part of checkout when required.
• Send supported customer receipts or payment notifications through an Email Delivery Connection.
• Coordinate payment-related Page interactions using Page Flow.

A Payment Widget is intended for collecting payments through its supported provider connection. Use Forms for general information collection and Page Flow for application-specific steps around checkout.

Available Payment Widgets

The Page Editor provides the following payment widgets:

Widget	Use It For
Stripe Payment	Collect payments through a configured Stripe connection.
Square Payment	Collect payments through a configured Square connection.

Select the widget that corresponds to the payment provider connection you intend to use:

• Use Stripe Payment with a Stripe Payment Connection.
• Use Square Payment with a Square Payment Connection.

The available connections depend on the Integrations configured for the Project. A provider account or connection must be configured separately; adding a Payment Widget does not create one.

The two widgets share the configuration concepts described below, although the resulting checkout experience and provider-specific behavior may differ.

Understanding the Payment Workflow

A payment experience may involve several Project capabilities:

Capability	Responsibility
Payment Widget	Presents the payment interface and applies the selected widget settings.
Integrations	Manages payment and email provider connections and related provider configuration.
Page Flow	Coordinates browser-side actions, such as preparing a dynamic amount and updating surrounding Page content.
Cloud Flow	Provides trusted backend processing when the application needs server-side validation, authorization, or business rules.
Database	Stores Project records, such as orders or registrations, when the application requires them.

For example, a paid event registration Page might collect registration details, calculate a fee, present the Payment Widget, and then update the registration's status after the payment has been reliably verified.

Displaying the payment interface, submitting a payment, and confirming a completed transaction are different steps. Do not assume that showing a success message in the browser is sufficient proof that a payment was completed.

Before You Begin

Before placing a Payment Widget, determine:

1. Provider: Whether the Project will use Stripe or Square.
2. Connection: Which configured payment connection the widget will use, including whether it is intended for testing or live transactions.
3. Amount: Whether the amount is fixed or will be supplied through Page Flow.
4. Email: Whether the application needs customer receipts or internal notifications and, if so, which Email Delivery Connection to use.
5. Address: Whether a shipping address is actually necessary.
6. Workflow: What should happen before checkout and after a payment has been verified.

Also confirm any currency and provider account settings in the appropriate Integration configuration. The Payment Widget's Amount setting does not itself configure the payment provider's currency or account.

Adding and Configuring a Payment Widget

A typical setup workflow is:

1. Open Integrations and configure the intended payment provider connection.
2. If receipts or notifications are needed, configure a supported Email Delivery Connection.
3. Open the Page in the Page Editor.
4. From the Element Library, add the matching Stripe Payment or Square Payment widget to the desired layout area.
5. Select the widget and open Element Settings.
6. Choose the Payment Connection and configure Amount.
7. Configure shipping address collection and email options as required.
8. If the amount or surrounding interactions are dynamic, configure the necessary Page Flow behavior.
9. Save the Page and use Preview to test the checkout experience with the intended test connection.
10. After testing, verify the live connection and publish through the Project's normal publishing workflow.

The widget's visual placement is only part of payment setup. Make sure any required application data, payment validation, and post-payment processing are configured as well.

For more about placing elements and accessing their settings, see Element Library and Element Settings.

Payment Widget Settings

After selecting a Payment Widget, open Element Settings to configure its available options.

Setting	What It Controls
Payment Connection	Selects the configured provider connection used to process the payment.
Email Delivery Connection	Selects the email connection used for supported customer receipts or payment notifications.
Require Shipping Address	Requires the visitor to provide shipping address information during checkout.
Email Payment Receipt to Customer	Enables a customer payment receipt email.
Email Notification	Enables an email notification about the payment to a configured recipient.
Notification Address	Specifies the email address that receives the payment notification.
Amount	Sets a fixed payment amount, or 0 when Page Flow will supply the amount dynamically.

Payment Connection and Amount must be configured for the payment experience. When customer receipts or notifications are enabled, select an appropriate Email Delivery Connection as well.

The settings shown in this section are specific to Payment Widgets. Other visual properties, where supported, are configured through the common Design controls in Element Settings.

Payment Connection

Payment Connection identifies the provider connection used by the widget.

Choose the connection that matches the widget type. For example, a Stripe Payment widget should use a Stripe connection rather than a Square connection.

When configuring and testing the connection:

• Verify that the connection belongs to the intended provider account.
• Check whether you are using the provider's test or live configuration.
• Confirm that the account and currency settings are appropriate for the transaction.
• Review the connection again before publishing a Page that can collect real payments.

Provider credentials should remain in Integrations. Do not embed secret credentials in Page content, Page Flow code, HTML, or browser-side JavaScript.

For provider and connection setup, see Integrations and Connections.

Fixed and Dynamic Amounts

The Amount setting determines whether the widget begins with a fixed charge or waits for a value supplied at runtime.

Amount Configuration	Behavior	Typical Use
A fixed amount greater than 0	The widget uses the configured amount for its payment experience.	Fixed registration fee, admission fee, or service charge.
0	The widget waits for Page Flow to provide a valid payment amount greater than zero.	Variable booking charge, calculated order total, or record-specific amount.

The payment form is presented only after the widget has a valid amount greater than zero. A widget configured with 0 requires the intended Page Flow behavior before checkout can proceed.

Fixed Amount

Use a fixed Amount when the charge is the same for every visitor using that payment experience.

For example, an event registration Page might charge a fixed registration fee. Configure the provider connection, enter the fee in Amount, and provide nearby Page content describing what the payment covers.

A fixed amount is generally the simplest configuration because Page Flow does not need to calculate or supply the charge.

Make sure the fee and the provider's currency configuration match the intended purchase. Currency and account configuration belong to the payment provider connection rather than the Page's explanatory text.

Dynamic Amount

Use a dynamic Amount when the amount depends on information gathered or selected at runtime, such as:

• A quantity or service option selected by the visitor.
• An amount associated with an order or invoice record.
• The number of registrations or tickets requested.
• A booking or request whose total is calculated by the application.
• Another supported Project workflow that determines a transaction amount.

To prepare a dynamic amount:

1. Set the Payment Widget's Amount to 0.
2. Gather the values needed to determine the payment amount.
3. Use supported Page Flow behavior to supply a valid amount to the widget.
4. Make the payment step available when its required information and amount are ready.
5. Test the result with several realistic input values.

This describes the workflow, not a specific Page Flow block name or programming API. Use the operations supported by the selected widget and current Page Flow configuration.

Validate the Amount

Page Flow executes in the visitor's browser. It can calculate or supply a display-time amount, but browser-side values must not be treated as authoritative for sensitive transactions.

For amounts derived from Project records, pricing rules, discounts, or customer entitlements, use appropriate trusted Backend processing to validate the amount and its relationship to the transaction. A visitor should not be able to change the amount owed merely by modifying browser-side values.

For example, a paid booking workflow may display a calculated total in the Page while trusted processing verifies the actual charge against the booking details.

Setting Amount to 0 enables the dynamic amount workflow; it is not a mechanism for accepting a free payment.

Email Receipts and Notifications

Payment Widgets can be configured to send supported email communications associated with payments.

Setting	Purpose
Email Payment Receipt to Customer	Sends a receipt email to the customer after payment.
Email Notification	Sends a payment notification to a configured email address.
Notification Address	Specifies the recipient for the notification.
Email Delivery Connection	Provides the configured email delivery connection used for these options.

Customer Receipts

Enable Email Payment Receipt to Customer when visitors should receive a confirmation of their payment by email.

Make sure the checkout experience provides or obtains the customer's email address as needed for the receipt. Test the receipt with the selected provider and Email Delivery Connection rather than assuming the email will arrive because the setting is enabled.

A receipt is a customer communication. It does not, by itself, authorize fulfillment or prove that unrelated Project records have been updated.

Internal Payment Notifications

Enable Email Notification when a Project administrator or operations team needs an email about a payment.

Set Notification Address to the intended recipient's email address and select the required Email Delivery Connection.

For example, an event organizer may want notification emails when payments are completed. An internal notification can help the team follow up, but it should not be the sole record of the payment.

Email Delivery Considerations

When testing email settings:

• Confirm that the Email Delivery Connection is configured and available.
• Verify the customer email information needed for receipts.
• Verify the Notification Address for internal emails.
• Test the enabled email options with a supported payment test flow.
• Check how the application handles a payment that succeeds but whose email is delayed or fails.

Payment processing and email delivery are separate operations. Do not interpret an email delivery failure as proof that a payment failed, or successful email delivery as independent proof of a completed payment.

Where the provider also offers separate receipt functionality, configure and test that provider behavior independently as applicable. Avoid sending unintended duplicate customer messages.

Require Shipping Address

Enable Require Shipping Address when checkout needs to collect a shipping address.

Examples include:

• Orders involving physical goods.
• Services that require delivery or a location supplied by the customer.
• Other payment workflows in which a shipping address is genuinely needed.

Keep this option disabled for payments that do not require shipping information, such as many digital services, access fees, or event registrations.

Require Shipping Address controls collection of the address. Do not assume that enabling it automatically calculates tax, determines delivery charges, validates whether an address is serviceable, or implements order fulfillment. Those requirements need the appropriate provider configuration or application logic.

If the application needs additional address fields beyond the widget's supported checkout experience, collect and process them through the appropriate Form or Project workflow.

Payment Widgets and Page Flow

Page Flow can coordinate browser-side actions before and after a supported Payment Widget interaction.

Common patterns include:

• Providing a dynamic payment amount.
• Requiring visitors to complete a selection or Form step before proceeding to payment.
• Updating surrounding Page content when the checkout state changes.
• Coordinating a payment step with another Page, Form, or Widget.
• Refreshing displayed data or advancing the user interface when the workflow allows.

Not every Payment Widget requires Page Flow. For a simple fixed-amount payment, the widget's own settings and the configured provider connection may be sufficient for presenting checkout.

Use Page Flow when the experience involves additional application-specific logic.

Example: Paid Registration

Consider a registration Page where a visitor chooses an event and pays a fee:

1. The visitor selects the registration option.
2. A Form collects the information required by the registration workflow.
3. The application determines the amount owed.
4. If the charge is variable, Page Flow supplies the amount to the Payment Widget.
5. The visitor completes the payment through the provider-connected widget.
6. Trusted processing verifies the payment outcome and applies the appropriate registration rules.
7. The Page presents an appropriate confirmation or follow-up state.

The Page and Page Flow coordinate the visitor experience. The payment provider and trusted Backend processing handle payment-sensitive decisions.

This is an example application design, not a claim that adding the widget automatically creates a registration record, confirms payment, or grants access.

Runtime Commands

Payment Widgets support runtime commands for dynamic checkout workflows. Use these commands when Page Flow or client-side logic needs to prepare the widget while the Page is running.

Common uses include:

• Supplying a calculated amount before checkout.
• Registering behavior that should run after a payment interaction.
• Reinitializing the Square widget when the surrounding workflow requires it.

Supported commands include:

Widget	Commands
Stripe Payment	set-amount, post-payment-hook
Square Payment	set-amount, reinit, post-payment-hook

Prefer ordinary Element Settings for fixed checkout configuration. Use runtime commands when the amount or payment step depends on Page state, user selections, records, or a surrounding workflow.

For exact API details, see $io.ui.widgetCommand. For Page Flow authoring, see Page Flow and Custom Code.

Confirming Payment and Completing the Workflow

A visitor may see different states during checkout, including a form ready for payment, an operation in progress, a success indication, or an error.

These user-interface states must be distinguished from the authoritative status of the transaction at the payment provider.

For workflows that create orders, grant paid access, mark registrations as paid, reserve limited inventory, or deliver services:

• Confirm the transaction through the supported provider integration or another trusted backend mechanism.
• Verify the payment belongs to the intended order, registration, or other Project record.
• Verify the expected amount and relevant transaction details before fulfillment.
• Design the backend workflow so that retries or duplicate notifications do not produce duplicate fulfillment.
• Record payment and fulfillment states in the Project's appropriate data model when needed.
• Provide a clear visitor-facing state when payment confirmation is still pending or cannot be established.

Cloud Flow can provide trusted server-side processing for application-specific rules when required. The exact provider confirmation mechanism and available integration events depend on the payment connection and the Project implementation.

Do not grant paid access or mark an order fulfilled solely because a Page Flow step executed or a browser-side message reports success.

For related concepts, see Cloud Flow and Page Flow.

Designing the Payment Experience

Payment is often one step in a larger Page. A clear checkout design helps visitors understand what they are purchasing and what will happen next.

Include the relevant information near the Payment Widget:

• A clear description of the product, service, or registration.
• The amount due and the applicable currency as configured for the payment experience.
• Any relevant terms, refund information, or conditions applicable to the purchase.
• An explanation of whether a shipping address or other information is required.
• An understandable message after success, cancellation, or failure, where the workflow supports those states.

For dynamic charges, display the current total before payment and avoid presenting an outdated amount after the visitor changes a selection.

Preview the layout at desktop, tablet, and mobile widths. Make sure the payment experience remains readable, visible, and usable without surrounding Page content obscuring checkout controls.

Testing Payment Widgets

Test the full transaction path before publishing, preferably through the payment provider's supported test configuration.

Scenario	What to Verify
Widget and connection	The Stripe or Square widget uses the matching configured provider connection.
Test or live configuration	The selected connection is the intended environment and account.
Fixed amount	Checkout uses the configured charge.
Dynamic amount	Page Flow supplies the correct amount before payment is offered.
Zero or unavailable amount	The widget does not present a payable checkout with an invalid amount.
Shipping address	Address fields appear when required and are omitted when unnecessary.
Customer receipt	The configured receipt behavior uses the intended customer email.
Internal notification	The configured notification reaches the intended address.
Successful payment	The Page handles the outcome and any subsequent business processing correctly.
Failed or cancelled payment	The visitor is not incorrectly told that payment succeeded.
Retry or duplicate outcome	A repeated action does not create duplicate orders, access grants, or fulfillment.
Responsive layout	The checkout interface works on the intended screen sizes.

Some payment states and test cases depend on the provider's supported testing tools. Use those tools and test credentials only in their intended test environment.

Preview, Save, and Publish

Use Save to retain Page Editor changes and Preview to test the experience during development.

Preview is not necessarily a simulated payment environment. A Page connected to live services may still interact with those services. Verify the selected payment connection before testing anything that could process a real charge.

When the workflow is ready, use Publish Project to release the application changes, then verify the published Page through Launch Project.

For more information, see Previewing and Publish Project.

Troubleshooting

Issue	What to Check
Payment interface does not appear	Confirm the matching Payment Connection and a valid Amount greater than zero. For a dynamic amount, confirm that Page Flow supplies it.
Payment provider connection is unavailable	Confirm the provider is configured under Integrations and matches the widget.
Unexpected amount	Review the fixed Amount or dynamic amount source, and verify the calculation against the intended transaction.
Wrong provider account or mode	Review the payment connection selected in Element Settings and its Integration configuration.
Receipt or notification is missing	Check the Email Delivery Connection, relevant email option, recipient information, and delivery behavior.
Shipping address is missing or unexpectedly required	Review Require Shipping Address.
Page indicates success but the order is still unpaid	Check authoritative payment status and the trusted workflow that updates order or registration data.
Payment works in one environment but not another	Compare the connection, configuration, access context, and published versus development state.

Avoid repeatedly retrying a payment that has an uncertain outcome without checking its status. An unclear browser result does not necessarily mean the provider did not process the transaction.

Good Practices

• Use the matching provider connection. Select Stripe Payment for Stripe and Square Payment for Square.
• Keep payment configuration in Integrations. Do not store provider secrets in the browser or Page content.
• Explain the purchase clearly. Show what the customer is paying for and the expected amount.
• Prefer fixed amounts for fixed fees. Use dynamic amounts when the workflow genuinely requires them.
• Validate transaction amounts in trusted processing. Do not rely exclusively on values that can be changed in the browser.
• Collect only necessary information. Enable shipping address collection and email options only when needed.
• Keep payment and email outcomes separate. A receipt or notification does not replace provider-confirmed payment status.
• Verify payment before fulfillment. Protect orders, registrations, entitlements, and other customer-impacting changes.
• Test unsuccessful outcomes. Check failure, cancellation, and retry behavior, not just successful payments.
• Test the intended environment. Use test connections before live operation and confirm the active connection before publishing.

Common Mistakes

Avoid these patterns:

• Adding a Payment Widget before creating its matching payment provider connection.
• Selecting a Stripe connection for a Square widget, or vice versa.
• Leaving Amount at 0 without supplying a dynamic value through Page Flow.
• Assuming that a successful browser-side event is authoritative proof of payment.
• Using browser-side calculations as the only validation of a sensitive charge.
• Marking an order or registration as paid before trusted confirmation.
• Treating receipt delivery or a notification email as the payment record.
• Enabling shipping address collection for purchases that do not need it.
• Testing only successful checkouts and overlooking failed, cancelled, or repeated attempts.
• Previewing against a live provider connection without realizing a real charge could be initiated.
• Saving changes and assuming they are already published.

Payment Widgets are most effective when the visible checkout experience, provider connection, Page Flow, and trusted transaction processing work together. Use the widget to collect payments, and use the appropriate Project capabilities to manage the application behavior and security around each transaction.

Related Topics

• Widgets
• Element Library
• Element Settings
• Forms
• Page Flow for Forms and Widgets
• Integrations
• Connections
• Cloud Flow
• Previewing