PayConex Hosted Payment Form provides a PayConex-hosted checkout page that collects customer and payment information and processes the payment as part of the hosted flow. Merchants can configure the amount, payment methods, customer fields, branding, terms, access behavior, and post-payment experience without building a complete checkout page.
When to use Hosted Payment Form
Hosted Payment Form is appropriate when you want to:
- Send a customer to a complete, hosted checkout;
- Accept a fixed amount, a customer-entered amount, or a donation amount;
- Offer one or more supported payment methods;
- Collect configured contact, billing, shipping, or custom information;
- Apply merchant branding and terms and conditions; and
- Let PayConex submit and process the payment within the hosted experience.
Hosted Payment Forms offer seamless checkout experience and can open in a normal browser tab.
Hosted Payment Form compared with Checkout Component
The two products solve different integration problems.
| Product | What the customer uses | What PayConex returns or does | Who submits the payment transaction |
|---|---|---|---|
| Hosted Payment Form | A complete PayConex-hosted checkout page | Collects checkout information and processes the payment in the hosted flow | The Hosted Payment Form runtime |
| Checkout Component | An embeddable component for collecting payment information | Tokenizes payment information for later use | The merchant or integrator submits a subsequent payment API request |
NoteDo not use Checkout Component SDK instructions, bearer-token rendering steps, or checkout callbacks to integrate Hosted Payment Form.
For Hosted Payment Form, simply direct the customer's browser to the hosted URL provided by PayConex.
If your integration requires transactions such as Storing a Card on File or Zero Amount Authorization, use PayConex Checkout Component.
Integration Methods
Hosted Payment Form offers two entry methods.
Payment Form Configurations | Direct URL Access
This ready-to-use option is ideal for merchants with no technical background who need to get started as quickly as possible. It requires no coding, server setup, or custom integration. All a merchant needs to do is configure and save a payment form in the PayConex Portal. Once the form is saved, it is ready to use—simply share the form’s public URL with customers so they can complete checkout.
With Direct URL Access enabled, customers can open the form's public URL directly. There is no need for the merchant's server to first create a form instance or generate a unique session. This makes the process simple and self-service for both the merchant and the customer.
To use this option, the form configuration must have directUrlAccess set to ENABLED. New forms are intended to default with direct access disabled, so merchants will need to turn this setting on when creating or editing the form if they want to use the ready-to-go public URL approach.
Compared to Payment Form Instances, the payment configuration form remains reusable for multiple payments until the configuration is paused or deleted.
Use Direct URL Access when you need a reusable payment link that can be distributed through a trusted channel, such as an email, QR code, printed material, or a merchant-controlled web page. It is best suited to forms that can collect the necessary amount and customer information at checkout.
Direct URLs can receive unsolicited traffic. Enable this mode only when a reusable public link is needed and when the merchant accepts the additional exposure described in Security and implementation considerations.
Payment Form Instances | API Initialization and Rendering
This option is intended for more technically involved merchants who prefer to manage their own integrations. They configure their global payment configuration with directUrlAccess set to DISABLED and then generate single-use payment instances.
Your server creates an instance of a saved form configuration. PayConex returns an instance ID, a hosted checkout URL, and a timeout in seconds. You send the customer to that returned URL and can retrieve the instance later to check its status and result fields.
Compared to Payment Form Configurations, payment form instances offer more features, and integrational flexibility, if required by your integration:
- A checkout URL created for a specific order, customer, or payment attempt;
- A merchant reference associated with the instance;
- Prefilled customer, billing, shipping, or custom-field values;
- Instance-specific amount or display settings supported by the V4 API;
- Instance-specific that override the payment configuration settings
- Unique Direction Page (
confirmationPage) per instance - A time-limited, single-use checkout session; or
- Server-side status lookup after the customer leaves the hosted page.
Conceptually, the flow involves:
Configuration → Initialize instance → Receive hosted URL → Customer checks out → Retrieve instance result
Supported payment methods
The V4 API supports the following payment methods as allowedPaymentMethods enumeration values:
CARDACHGOOGLE_PAY
Availability also depends on the PayConex account and processor configuration. For example, ACH or Google Pay is only supported if the account is enabled for that capability. When only one payment method is available, the checkout can present that method without a method selector.
Identifiers used by the integration
| Identifier | Meaning | V4 API Format |
|---|---|---|
accountId | The PayConex account that owns the form | 12 numeric digits |
resourceId | A saved Hosted Payment Form configuration ID | hpf_ followed by 32 hexadecimal characters |
resourceInstanceId | An initialized checkout instance ID | hpfi_ followed by 32 hexadecimal characters |
Keep configuration IDs and instance IDs separate. A configuration may be reused to create many instances, while an initialized instance represents a particular hosted checkout session.
Next steps
PayConex administrators
Start with Manage Hosted Payment Forms.
Developers
Compare the approaches in Choose an integration method, then follow API initialization and rendering or Direct URL Access.
Merchant support and operations teams
Review Customer checkout experience and Errors and troubleshooting.