Customer Checkout Experience

The Hosted Payment Form presents a responsive PayConex-hosted page based on the saved configuration and any supported instance overrides.

Page layout and branding

Customers can see:

• The configured amount or amount choices;
• Merchant logo and cover imagery, when configured;
• Contact, billing, shipping, and custom fields selected by the merchant;
• Available payment methods;
• Terms and conditions, when required; and
• The Pay action with the configured colors and field style.

If a branding image cannot load, the form is designed to fall back without blocking payment.

Checkout Setup

The API does not cover all conditional business rules. In practice, the merchant should configure the settings needed by the selected page type and enable at least one payment method.

To put together the most optimal set of rules as required by your integration, refer to the API Definition Reference.

Amount selection

The amount experience depends on the form type:

• A FIXED E-Commerce form displays the amount without allowing the customer to change it.
• An OPEN E-Commerce form asks the customer to enter an amount within the configured minimum and maximum.
• A donation form displays a configured donation list or allows a custom amount, according to its saved settings.

Invalid or missing amounts produce an inline error and prevent submission.

Customer and custom information

Fields marked required must be completed before payment. Optional fields may be left blank, and omitted fields are not displayed.

The checkout retains entered values in real-time while the customer corrects validation errors. Custom fields appear in their configured order and use the configured text, dropdown, or radio behavior. View-only custom fields cannot be edited by the customer.

Billing Address | State Dropdown

The Hosted Payment Form offers the following supported state/province list. This is a built-in feature so the merchant does not need to add any additional custom fields or similar.

Alabama, Alaska, American Samoa, Arizona, Arkansas, California, Colorado, Connecticut, Delaware, District of Columbia, Florida, Georgia, Guam, Hawaii, Idaho, Illinois, Indiana, Iowa, Kansas, Kentucky, Louisiana, Maine, Marshall Islands, Maryland, Massachusetts, Michigan, Minnesota, Mississippi, Missouri, Montana, Nebraska, Nevada, New Hampshire, New Jersey, New Mexico, New York, North Carolina, North Dakota, Northern Mariana Islands, Ohio, Oklahoma, Oregon, Palau, Pennsylvania, Puerto Rico, Rhode Island, South Carolina, South Dakota, Tennessee, Texas, Utah, Vermont, Virgin Islands, Virginia, Washington, West Virginia, Wisconsin, Wyoming, U.S. Armed Forces, U.S. Armed Forces Americas, U.S. Armed Forces Pacific, Alberta, British Columbia, Manitoba, New Brunswick, Newfoundland, Nova Scotia, Ontario, Prince Edward Island, Quebec, Saskatchewan, Northwest Territory, Nunavut, Yukon Territory, Other

Payment methods

The page shows only methods included in allowedPaymentMethods and available to the account. When there is a single method, the page can rule out the method selector for convenience.

Card

The card experience collects the card information required by the hosted flow and any configured customer, billing, or shipping information. As the customer enters a recognizable card number, the form renders the corresponding card-brand icon. The icon is informational and does not guarantee acceptance or approval.

If 3-D Secure applies, the customer completes the authentication step as part of checkout.

ACH

When ACH is enabled, the customer can select Bank Account and provide the bank-account and authorization information required by the hosted ACH flow. The essential required fields are Name On Account, Bank Account Number, Routing Number.

Google Pay

When GOOGLE_PAY is enabled and available on the customer's browser or device, the page presents the Google Pay action. The customer selects an eligible wallet payment method in the Google Pay sheet and returns to the hosted flow for submission.

If Google Pay is unavailable, the option can be hidden or disabled and the customer can use another enabled method.

Save payment method

Depending on savePaymentOption, the customer may see an option to save the payment method:

• omit — no option;
• optional — customer chooses; or
• required — selected and not editable.

Merchants are responsible for the customer-facing disclosure and authorization appropriate to their future use of a saved payment method.

For the comprehensive documentation on subsequent payments, refer to Customer and Merchant Initiated Transactions and Customer/Merchant Initiated Transactions Use Case.

Terms acceptance

If agreement is required, the customer must accept the merchant's terms before submitting payment. Terms may be presented from merchant-provided text or through a merchant-provided URL, depending on the configuration.

A required agreement prevents payment submission until the customer accepts the terms.

Bot verification

On submission, the hosted page performs reCAPTCHA v3 verification. A normal customer can continue without an additional visible challenge. If the risk result requires step-up, the customer sees a reCAPTCHA v2 challenge and must pass it before PayConex submits the payment.

The submit action is disabled while verification and payment processing are in progress to reduce duplicate requests.

Submission and result

The Hosted Payment Form submits the payment to PayConex. This is the key difference from Checkout Component: the Hosted Payment Form does not simply return payment data for the merchant to charge later.

After submission:

• Field or validation problems are shown in customer-friendly language;
• A declined payment remains a payment failure and does not show an approved confirmation;
• An approved payment either shows the PayConex confirmation experience or redirects to the configured confirmationUrl; and
• Sensitive processor or internal error details are not displayed to the customer.

The hosted flow submits and processes the payment before showing the configured completion experience.

Unavailable links and sessions

The hosted runtime provides dedicated customer-facing states for:

• Page not found — invalid form or instance, or direct access is disabled;
• Session timed out — an initialized session expired; and
• Form already used — the initialized session already completed and cannot be reused.
• Unexpected Error — Payment Processor or PayConex gateway level error

Customers should request a new payment link from the merchant when an initialized checkout is expired or already used.