Integration
Choosing between hosted checkout and a direct API integration
How the two integration models differ in data handling, PCI DSS scope, control over the payment page and engineering effort, and how to decide which fits your business.
· 6 min read
Two ways to take a payment
Most online payment integrations follow one of two models. In a hosted checkout, your site sends the customer to a payment page run by the payment provider. The customer enters their details there and is then returned to your site. In a direct API integration, your own server builds the payment request and sends it to the provider's API, and your own pages collect what the customer enters.
Both models end in the same place: an authorised payment, a status you can check, and funds that settle to your account. The difference is who handles the payment data along the way. That single difference drives most of the trade-offs: security obligations, how much of the page you control, how much you have to build and how much you have to maintain.
This article sets out those trade-offs so you can make the decision on facts rather than habit. There is no universally correct answer. There is only the model that fits your product, your team and your obligations.
How a hosted checkout works
A hosted flow usually has four steps. Your server creates a payment with the amount, currency, order reference and the URLs the customer should return to. The provider responds with a link to its payment page and a payment token that identifies the payment. You redirect the customer to that link. When the customer finishes, they are sent back to your success or fail URL, and the provider separately notifies your server of the final status.
The return URL tells you where the customer is. It does not prove that the payment succeeded, because a customer can close the browser, lose connectivity or open the success URL directly. The status that counts is the one your server receives through a callback or retrieves from the API using the payment token.
How a direct API integration works
In a direct integration, your server calls the payment API to create, confirm, refund and query payments. You design the whole checkout experience. You can place payment fields inside your own flow, run your own validation and handle every response code in your own interface.
If card details pass through your servers, your systems store, process or transmit cardholder data. That places them in scope for the Payment Card Industry Data Security Standard (PCI DSS), with the controls, assessments and evidence that follow. Many providers, including Rainbow Pay, only permit raw card data to be sent from a merchant server after a specific approval.
A direct integration also means more engineering. You own the retry logic, error handling, timeouts, logging and monitoring. You need secure storage for API credentials and a clear separation between test and production environments. None of this is unusual for a team that already runs production systems, but it is real work that continues after launch.
Comparing the trade-offs
| Consideration | Hosted checkout | Direct API |
|---|---|---|
| Where card data is entered | On the provider's page | On your pages, sent from your server |
| PCI DSS scope | Typically narrower, but still yours to assess | Broader: your systems handle cardholder data |
| Control over the payment page | Limited to what the provider allows | Full control of layout and flow |
| Initial build effort | Lower | Higher |
| Ongoing maintenance | Mostly on the provider | Shared: your code, your infrastructure, your controls |
| Customer journey | Leaves your site briefly, then returns | Stays on your site |
Two things in this table are often misread. First, narrower PCI DSS scope is not the same as no scope. You still need to determine and validate your obligations with your acquirer or assessor. Second, control over the page is only valuable if you have a reason to use it. A payment page that is consistent, fast and clear is usually more important than one that matches your brand in every detail.
Questions that settle the decision
- Do you have a specific reason to handle card data yourself? If not, a hosted page is usually the simpler and safer starting point.
- Can your organisation meet and evidence PCI DSS controls for card data on its own systems? If the honest answer is not yet, a direct card integration is premature.
- How much engineering time can you commit, now and after launch? A hosted flow needs less of both.
- Which features do you need? Refunds, recurring payments, two-step payments and payouts are all server-side operations. They are handled through the API, so check with your provider which of them are available for the integration model you choose.
- Who will support it? A payment integration needs an owner who reads callbacks, investigates failures and answers finance and support questions.
Many businesses start with hosted checkout and use the API for everything around it: status checks, refunds, recurring charges and reconciliation. That combination keeps card entry off their own systems while still giving them programmatic control of the payment lifecycle.
Next steps
Whichever model you choose, build and test it in a sandbox first. Test declines, abandoned payments, duplicate callbacks and refunds, not just the successful path. The integration guides outline both routes, and the API documentation (opens in a new tab) holds the request and response details.
If you are unsure which model your business should use, raise it during onboarding. The answer depends on your payment methods, your markets and your existing controls, and it is easier to settle before the build starts than after.