Choosing Between a Hosted Checkout and a Custom API Integration
A hosted checkout is a pre-built payment page you can launch in days with minimal development work, ideal for most small and mid-sized businesses. A custom API integration gives full control over the checkout experience and is worth the added development time when you need a fully branded flow, complex product logic, or deep integration with existing systems.
When you're setting up online payments, one of the first decisions is how customers actually complete a purchase on your site. Two main approaches exist: a hosted checkout, where a pre-built payment page handles the transaction, or a custom API integration, where your development team builds the entire payment flow using your processor's API. Both are legitimate choices — the right one depends on your team's resources, your timeline, and how much control you need over the experience.
What is a hosted checkout?
A hosted checkout is a ready-made, secure payment page provided by your processor. When a customer is ready to pay, they're directed to (or shown, via an embedded overlay) this pre-built page, which handles the entire payment collection process — card fields, validation, 3D Secure authentication, and confirmation — before returning the customer to your site once the payment completes.
Because the processor builds and maintains the entire payment form, hosted checkouts typically launch in days rather than weeks, require little to no custom development, and shift much of the PCI compliance burden to the processor, since sensitive card data never touches your own servers.
What is a custom API integration?
An API integration means your development team builds the checkout experience directly, using your processor's API to submit and process payments programmatically. This gives full control over the visual design, the flow (single-page checkout, multi-step, embedded within a larger app), and how payment logic interacts with the rest of your systems — inventory, subscriptions, custom pricing rules, and so on.
The tradeoff is development time and ongoing maintenance: your team is responsible for building a compliant, secure checkout experience (even if using the processor's pre-built UI components to reduce PCI scope), testing it thoroughly, and maintaining it as your processor's API evolves.
Side-by-side comparison
Time to launch
Hosted checkout: typically live within a few days, often requiring just a redirect link or a small embed snippet. API integration: commonly several days to a few weeks of development time, depending on the complexity of your checkout flow and how much custom logic is involved.
Development resources required
Hosted checkout: minimal — often no dedicated developer needed for a straightforward setup. API integration: requires a developer familiar with your processor's API, along with testing across browsers and edge cases.
Design control
Hosted checkout: limited to the customization options your processor provides (colors, logo, basic layout). API integration: complete control over every visual and interaction detail of the checkout.
PCI compliance burden
Hosted checkout: minimal, since card data is captured and processed entirely on the processor's infrastructure. API integration: higher, though using the processor's client-side tokenization components (rather than handling raw card numbers yourself) significantly reduces this burden compared to a fully custom-built card form.
Flexibility for complex use cases
Hosted checkout: works well for standard one-time and subscription purchases, but can be limiting for complex product configurations, multi-step checkouts, or deep integration with in-house systems. API integration: built specifically to handle whatever logic your business needs, since you control the entire flow.
When a hosted checkout is the right choice
- You want to start accepting payments quickly, without a development project.
- Your team doesn't have dedicated developer resources to build and maintain a custom checkout.
- Your product and checkout flow are relatively standard — cart, checkout, confirmation.
- You want the processor to carry most of the PCI compliance responsibility.
When a custom API integration is worth the investment
- You need the checkout to be fully embedded and visually seamless with the rest of your site or app, with zero redirect.
- Your checkout involves complex logic — dynamic pricing, bundled products, multi-party payments, or custom subscription rules — that a standard hosted page can't accommodate.
- You need deep integration with existing systems, like a custom inventory management platform or an internal CRM.
- You have in-house development resources and plan to maintain the integration over time.
A hybrid approach: embedded components
Many processors, including Harbour, also offer a middle path: pre-built, PCI-compliant UI components (like card input fields) that you embed directly into your own checkout page design. This gives you more visual control than a full redirect-based hosted checkout, without the full development burden and PCI scope of building card capture entirely from scratch. It's worth asking your processor about this option if a fully hosted page feels too restrictive but a full custom build feels like more than you need.
How to decide for your business
Start by asking two questions: how much custom logic does your checkout actually need, and does your team have development resources to build and maintain a custom integration? If your checkout is largely standard and you want to move fast, a hosted checkout is almost always the right starting point — you can always move to a custom integration later as your needs grow more complex. If you already know your checkout requires deep custom logic or a fully seamless embedded experience, it's worth investing in the API integration from the start rather than working around a hosted page's limitations.
How Harbour supports both approaches
Harbour offers a pre-built hosted checkout that can be live in days, a full REST API for custom integrations, and embeddable PCI-compliant components for teams that want a middle ground. Merchants can start with the hosted checkout and move to the API later without switching processors or re-doing underwriting, since it's the same underlying account either way.
Frequently asked questions
Can I switch from a hosted checkout to an API integration later?
Yes. Most processors, including Harbour, let you move between the two without needing a new merchant account, since the underlying payment processing and account remain the same.
Is a hosted checkout less secure than a custom integration?
No — if anything, a hosted checkout typically has a smaller attack surface for your own systems, since sensitive card data is handled entirely on the processor's PCI-compliant infrastructure rather than passing through your servers.
How long does a typical API integration take to build?
It varies significantly by complexity, but a straightforward integration using a processor's official SDK and documentation commonly takes a developer anywhere from a few days to a couple of weeks, including testing.