Both integration methods display the PayConex-hosted checkout and process the payment as part of that hosted flow. The difference is how the checkout is created and reached.
Comparison
| Consideration | API initialization (Payment Instance Form) | Direct URL Access (Payment Configuration Form) |
|---|---|---|
| Server API call before checkout | Required | Not required |
| Customer URL | The url returned for an initialized instance | The url returned for the saved configuration |
| URL identifier | Instance ID (hpfi_...) | Configuration-based URL |
| Per-checkout reference | Supported through reference | Not explicitly supported |
| Prefill customer or shipping data | Supported by the instance API request | Supported by the configuration API request. Prefilling such data per customer is not supported since it is a (global) payment configuration. |
| Instance timeout | Returned by initialization; configurable with timeout | timeout can be set at the payment-configuration-level to define the default value for all the newly created instances but does not affect the payment configuration itself given that a payment configuration with direct URL access does not implement the timeout expiry and remains reusable for multiple payments until the configuration is paused or deleted. However, it does specify the real-time timeout value that determines when the session should expire before the page reloads. |
| Server-side result lookup | Use the authenticated instance GET | Refer to recipes covered at Direct-access lifecycle and Result Processing. |
| Best fit | Order-specific, time-limited, or prefilled checkout | Reusable public payment or donation link |
| Configuration requirement | Active, usable form configuration | directUrlAccess: "ENABLED" |
| Exposure | Customer receives a particular instance URL | Reusable URL can be copied, indexed, or targeted by automated traffic |
Choose Direct URL Access when
Use Direct URL Access for a link that customers can open without your server creating a session first. Common distribution channels include a merchant website, email, QR code, or printed material.
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.
This method works best when the saved form contains everything needed for checkout or asks the customer to enter the missing information.
For more, see Direct URL Access and Integration Methods.
Choose API initialization when
Using initialization if your application knows about the payment before checkout begins. Common examples include an invoice, order, registration, or account balance.
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 expiry in seconds. You send the customer to that returned URL and can retrieve the instance later to check its status and result fields.
Initialization is the recommended path when you need to:
- Associate a merchant
referencewith checkout; - Prefill customer or address information;
- Provide custom-field values;
- Apply instance-specific settings allowed by the V4 API;
- Instance-specific that override the payment configuration settings
- Unique Direction Page (
confirmationPage) per instance - Enforce an instance timeout; or
- Retrieve a known instance after checkout to examine
status,transactionId, andamount.
For more, see API initialization and rendering and Integration Methods.
Do not combine URL formats
Do not replace an instance ID in one URL with a configuration ID, or construct a hosted-page URL from an API path. Use the complete url value returned by the applicable PayConex API response.
If the URL is not registered by the PayConex gateway, it will be rejected via 404 not-found. PayConex can return a different host or route for the environment.
API paths such as /api/v4/payment-form/instance/{resourceInstanceId} return JSON used to describe a resource. They are not the hosted browser checkout URL.