Hosted Payment Forms With Collect Checkout

A hosted payment form collects card details through the payment gateway instead of through the merchant’s own application. That single architectural decision changes how much cardholder data your environment touches, how much PCI scope you carry, and how much of checkout you have to build yourself.

Collect Checkout gives developers three ways to put a payment form on a website: a hosted checkout page reached by a payment link or button, embedded gateway-hosted fields through Collect.js, and a direct Payments API integration for workflows that need full server-side control.

This guide covers how the embedded checkout form works end to end, when a hosted form beats a direct API integration, and what to get right before you put the form in front of real customers.

What Is a Hosted Payment Form?

A hosted payment form collects card details on a page or in fields controlled by the payment gateway, not by your application. The gateway renders the inputs, receives the sensitive values, and hands your system back a reference it can use to submit the transaction.

With Collect Checkout, you can create a payment link and generate HTML for a button or form that sends customers to that hosted checkout experience. The gateway owns the payment surface end to end.

You can also manage product inventory, generate links for specific products or amounts, create QR codes, and adjust form layout and button colors. For a straightforward payment flow, these tools reduce the time spent building and maintaining custom checkout code.

Choose the Checkout Pattern That Fits

Collect Checkout supports three patterns, and they solve different problems. A hosted Collect Checkout page is the fastest path with little or no code. Collect.js embedded fields support a more integrated checkout on your own domain. A direct Payments API integration gives your application full control over payment requests and workflows, at the cost of additional scope in your own environment.

For more control over the customer experience, Collect.js places gateway-hosted payment fields inside a merchant-designed checkout page. This approach separates card-data collection from your application while allowing your team to manage the surrounding page and submit transactions through the Payments API.

Explore Collect Checkout and hosted payment forms.


How Embedded Collection Works

A hosted payment page and an embedded checkout are related but not identical. Collect Checkout can send customers to a gateway-hosted payment page; Collect.js provides gateway-hosted fields, technically rendered in iframes, within a form on your website.

In the embedded flow, the customer sees your checkout page and enters card data into the hosted fields. The sensitive values go directly from the browser to the gateway, which returns a payment_token for your server to use when submitting the transaction.

Walk Through the Request

1. Render your checkout. Build the page around your order summary, customer fields, and payment button. Load Collect.js with the public tokenization key created in the merchant control panel.
2. Collect payment details. Collect.js renders gateway-hosted fields within your form. The customer enters payment information into those fields, rather than into inputs handled by your server.
3. Receive a token. The gateway returns a `payment_token` to the browser. Treat it as temporary and intended for a single payment submission; do not store it as a reusable card reference.
4. Submit from your server. Send the token and the required transaction details from your backend to the Payments API. Keep the private API credentials on the server, then use the API response, not a browser redirect alone, to determine the transaction result.

Collect.js is a payment-data collection and tokenization layer, not a replacement for the Payments API. It lets your application retain its server-side transaction workflow without handling raw card data. Review the Collect.js integration overview before implementing the browser and server responsibilities, and read the walkthrough on tokenizing payments with Collect.js for the variable-level detail.


Hosted Forms or Direct API?

There is no universal choice. The right approach depends on how much checkout control your application needs and where it can safely handle payment data.

• Collect Checkout hosted page: good fit for product payments, invoices, donations, or simple online checkout. Payment details are entered on a gateway-hosted page, development effort is lower, and you configure checkout plus a link or button.
• Collect.js embedded fields: good fit for a branded website or app checkout with a custom page layout. Hosted fields send sensitive details to the gateway and your server uses the returned token. Development effort is moderate and includes the page plus the server-side transaction flow.
• Direct API with card data handled by your application: good fit for workflows that require direct control of payment-data collection and request construction. Cardholder data may pass through or be processed by your environment, development effort is higher, and you manage the related security controls and assessment scope.

A direct API integration can be the right technical choice. It supports server-side orchestration and custom payment logic. The key difference is whether your environment handles raw card data. Collect.js can be used with an API so your backend keeps transaction control while the card data goes directly to the gateway.

See the Payments API integration options for details on the direct request path, and the payment gateway integration architecture guide for how the payment layer fits into a larger application.


Advantages of Hosted Collection

Reduce Card-Data Exposure

When gateway-hosted fields collect payment details, raw card data does not pass through your application server. That can reduce the number of systems, logs, and services that must be considered in your payment-data security design.

It also avoids building your own card-data tokenization layer. The gateway manages the hosted fields and tokenization behavior, while your team focuses on the rest of checkout.

Reduce Integration Work

A payment link or generated button can support a basic checkout without a custom payment form. For a branded experience, Collect.js can be added to an existing checkout rather than requiring the application to create and secure card-entry fields itself.

Hosted collection also provides a defined handoff between browser-side payment entry and server-side transaction processing. That can simplify testing, maintenance, and troubleshooting.

Keep the Checkout Consistent With Your Site

Collect.js allows your team to control the surrounding page design: order summary, labels, layout, and other non-sensitive checkout content. Collect Checkout also includes controls for form layout and payment-button colors.

Test the page at common mobile widths. Make sure hosted fields fit the responsive layout, validation messages are visible, and customers can review the amount before submitting payment.


Protect Keys, Tokens, and Transaction State

The tokenization key is designed for use with Collect.js and is public-facing. It may appear in browser code, but it must not be treated as a private API credential or used for server-side transaction authorization. Keep the private API key on your server and out of HTML, JavaScript bundles, browser storage, and client-visible logs.

A payment_token is not a customer vault reference. Use it promptly for the intended transaction, and do not assume it can be reused for another charge. For repeat or recurring payments, store and use a gateway-managed Customer Vault reference instead of card details; recurring billing requires Customer Vault. Learn about Customer Vault and secure payment storage.

Build transaction handling around server-side state. Verify the gateway response before marking an order paid, and do not rely only on a customer reaching a success URL. If the browser closes or a request times out, the result may be unknown rather than declined. Check the transaction status before retrying to avoid duplicate charges.

Use an internal idempotency strategy to prevent your application from submitting the same order twice. If your chosen API supports a gateway idempotency feature, follow its documentation; do not invent or assume an undocumented request field. Handle declines as a separate outcome, show a clear next step, and never automatically resubmit a declined payment without a new customer action.

When a Direct API Integration Makes Sense

Use a direct API approach when the payment request must be coordinated closely with complex business logic or a server-side workflow. It may be preferable for multi-step authorization processes, unattended environments, or card-present integrations where the checkout model differs from a standard website form.

For website payments, a three-step redirect offers another server-side pattern: submit transaction details without sensitive payment values, render a form that posts card data directly to the gateway, then complete the transaction using the returned token ID. Review the three-step redirect API flow when this model better fits your implementation.

Common Mistakes to Avoid

• Confusing the keys. Use the public tokenization key only with Collect.js. Keep private API credentials on the server.
• Sending card data to your backend. Make sure the card-entry fields are the gateway-hosted fields, not custom inputs that submit raw card values to your server.
• Trusting a redirect as payment confirmation. Confirm the transaction result through your server-side processing flow.
• Retrying after a timeout without checking status. Resolve the original transaction outcome before creating another submission.
• Storing a temporary token as a card reference. Use Customer Vault for future charges or recurring billing.
• Assuming tokenization removes PCI obligations. It can reduce exposure and assessment scope, but does not replace the merchant’s annual compliance responsibilities.

Implementation Checklist

• Select the hosted Collect Checkout page for low-code payments, or Collect.js for embedded hosted fields and a custom checkout interface.
• Generate the tokenization key in the merchant control panel and use it only with Collect.js.
• Keep private API credentials on the server side and submit transactions using the `payment_token`.
• Verify transaction results server-side and design safe handling for declines, timeouts, and unknown outcomes.
• Use an internal idempotency strategy and check transaction status before retrying.
• Use Customer Vault, not a temporary payment token, for future or recurring charges.
• Test success, decline, timeout, retry, and mobile checkout scenarios in the [developer sandbox](https://www.integratepayments.com/developer-sandbox-payment-gateway-api-sdk).
• Complete the annual PCI Self-Assessment Questionnaire (SAQ) applicable to your business and integration.

Hosted payment forms can help developers launch checkout sooner, reduce exposure to raw card data, and retain control over the customer journey. Choose the pattern that matches your payment flow, then test the full transaction lifecycle before putting it into production.

Before you ship, work through the sandbox to production checklist to cover credentials, webhooks, and go-live verification.

Compliance disclosure: Tokenization does not by itself establish PCI DSS compliance or eliminate PCI DSS obligations. Merchants remain responsible for completing the applicable annual Self-Assessment Questionnaire (SAQ) and maintaining compliance based on their environment and payment flows.