Payment Gateway Integration: Complete Developer and Business Guide
Integrating a payment gateway is one of the most consequential technical decisions an e-commerce business or software team makes. The method you choose determines your PCI DSS scope, your checkout conversion rate, your ability to handle 3D Secure authentication, and how quickly you can support new payment methods. This guide covers every integration path available, from a no-code hosted page to a full server-to-server REST API, and walks through the exact steps required to go live with RoxPay. Whether you are a developer building a new checkout or a business owner evaluating options, this guide gives you the full picture.
What Payment Gateway Integration Means for Your Business
A payment gateway integration is the technical connection between your website or application and the payment processing network that authorises, captures, and settles card transactions. Without it, your customers cannot pay. With a poor integration, you lose revenue through failed transactions, friction-heavy checkout flows, and poor mobile experience.
The integration affects more than just developers. Business owners need to understand that the method they choose determines their liability under PCI DSS, their ability to support local payment methods, and the speed at which new features like Apple Pay or open banking transfers can be enabled. A hosted page integration moves all card data handling off your servers and minimises your compliance burden. A direct API integration gives maximum control but places card data handling on your infrastructure, requiring a higher level of PCI certification.
Why integration quality matters for conversion: Checkout friction is one of the top causes of cart abandonment. A gateway that requires multiple redirects and a separate bank portal visit will convert worse than a native, embedded checkout experience. Modern REST API integrations allow you to render the card input fields directly on your checkout page without the customer ever leaving your site, which improves completion rates measurably.
For merchants in high-risk verticals who also need a high risk payment gateway, the integration layer is even more important because additional checks, 3D Secure enforcement, and fraud filters all interact with how the payment form is built and how events are handled downstream. Choosing a gateway that handles both standard and high-risk processing in a single integration avoids the complexity of managing two separate systems.
Integration Methods: Hosted Page vs API vs SDK
There are three primary ways to integrate a payment gateway, each with different trade-offs between speed of implementation, PCI DSS scope, and customisation flexibility.
Hosted Payment Page: The simplest option. You redirect the customer from your checkout to a page hosted and managed by the payment gateway. The customer enters card details on the gateway's domain, not yours. This eliminates almost all PCI DSS requirements on your side because you never handle card data. The downside is limited customisation and the experience of leaving your site mid-checkout. Best for businesses that want to start accepting payments quickly with minimal development effort.
Embedded Drop-in UI (iFrame or JS Elements): A practical middle path. The gateway provides a JavaScript snippet that injects secure card input fields directly into your checkout page. The fields render inside iframes hosted on the gateway's domain, so card data never touches your server. From the customer's perspective, the checkout looks native to your site. PCI scope is minimal (SAQ A). This is the recommended approach for most e-commerce businesses. RoxPay supports this via its REST API and frontend SDK.
Server-to-Server API: Maximum control. Your frontend collects card data, your server sends it directly to the gateway API. This requires PCI DSS SAQ D compliance, which involves rigorous security audits and ongoing controls. It is appropriate for platforms building payment infrastructure products, not for most merchants processing their own transactions.
Platform Plugins and Modules: For merchants using e-commerce platforms such as Magento, PrestaShop, or WooCommerce, pre-built modules handle the integration details within the platform's architecture. The underlying method is typically a hosted page or drop-in UI, so PCI scope remains minimal and implementation time is measured in hours rather than days.
Step-by-Step: How to Integrate RoxPay via REST API
RoxPay provides a REST API with JSON request and response bodies. Full documentation is available at app.roxpay.eu/api/v4/docs. The integration follows a standard payment intent pattern familiar to any developer who has worked with modern gateway APIs.
Step 1: Create your sandbox account. To start your RoxPay application, navigate to the onboarding page. Sandbox credentials are issued automatically upon registration, with no payment information required to begin testing.
Step 2: Authenticate. All API calls use your API key in the Authorization header. Keys are scoped to your merchant account and can be rotated from the dashboard. Never expose your API key in client-side JavaScript or commit it to version control.
Step 3: Create a payment intent. POST to the payment intent endpoint with the amount, currency, accepted payment methods, and a unique order reference from your system. The API returns a payment intent ID and a client secret for use on the frontend.
Step 4: Mount the drop-in UI. Pass the client secret to the RoxPay.js library, which renders the card input fields on your page. The library handles card number formatting, validation, 3D Secure redirects, and Apple Pay or Google Pay buttons based on browser support.
Step 5: Handle the result. On successful payment, the library triggers a success callback. Your frontend notifies your backend, which independently verifies payment status via webhook before fulfilling the order. Never rely solely on frontend confirmation for order fulfilment.
Step 6: Reconcile via the dashboard. All transactions are visible in your merchant dashboard with full detail on amount, fees, card type, and settlement status. Export to CSV or use the API for accounting system integration.
Webhooks, Error Handling, and Testing in Sandbox
Webhooks are the backbone of a reliable payment integration. They allow RoxPay to notify your server of payment events asynchronously, without depending on the customer's browser remaining open or the network connection staying stable throughout the transaction.
Setting up webhooks: Register an HTTPS endpoint on your server in the dashboard. RoxPay will POST a signed JSON payload to this endpoint for every significant event: payment.completed, payment.failed, payment.refunded, chargeback.created, and others. Verify the signature on every incoming webhook using the secret key shown in your dashboard. Reject any request that fails signature validation to prevent replay attacks.
Idempotency: Webhooks can be delivered more than once due to network conditions. Your endpoint must process each event idempotently, meaning processing the same event twice produces the same outcome. Store the event ID and skip processing if you have already handled it.
Error handling in the API: RoxPay returns standard HTTP status codes. 200 for success, 400 for bad requests with invalid parameters, 401 for authentication failures, 422 for processing errors such as a card decline or insufficient funds. Always inspect the error code in the response body, not just the HTTP status, to distinguish between a technical error and a business logic rejection.
Sandbox testing: The sandbox environment mirrors production exactly. Use the provided test card numbers to simulate approved transactions, declines, 3DS challenges, insufficient funds, expired cards, and stolen card responses. Test your webhook handling by triggering each event type in the sandbox before touching production. Confirm your error UI works correctly for every decline scenario your customers might encounter, not just the happy path.
Retry logic: Implement exponential backoff on your webhook consumer. RoxPay retries undelivered webhooks over a defined period. Your endpoint must be idempotent before you rely on retry behaviour.
Going Live: Checklist Before Processing Real Transactions
Moving from sandbox to production requires completing a set of technical, security, and commercial steps. Skipping any of these creates risk for your business and your customers.
Technical checklist:
Replace sandbox API keys with production keys and store them in environment variables, never in source code or version control. Confirm your webhook endpoint is live, accessible over HTTPS with a valid certificate, and returning 200 responses consistently. Test idempotency handling with production credentials before switching customer traffic. Confirm 3D Secure is configured according to your acquirer's requirements for your merchant category. Validate that your checkout UI renders correctly on mobile devices, particularly for Apple Pay and Google Pay buttons.
PCI DSS checklist:
If using the drop-in UI, complete and file a SAQ A self-assessment questionnaire. Confirm you are not logging or storing raw card data anywhere in your system, including request logs, error logs, or analytics pipelines. Ensure your TLS configuration meets current standards (TLS 1.2 minimum, TLS 1.3 preferred). Remove any old payment integrations that may still be active in your codebase.
Business checklist:
Set your billing descriptor in the dashboard. This is the text that appears on the cardholder's bank statement. A clear, recognisable descriptor significantly reduces friendly fraud chargebacks because customers can identify the charge. Configure your settlement IBAN. RoxPay settles to any SEPA bank account in 24-48 hours. Enable email notifications for failed transactions and chargebacks so you can respond within dispute deadlines. Review your refund and cancellation policy and ensure it is clearly visible during checkout. Make sure your customer support contact is easy to find, as customers who can reach you directly are far less likely to initiate a bank dispute.
Frequently Asked Questions
How long does a payment gateway integration take?
Using the drop-in UI approach with RoxPay's REST API, an experienced developer can complete a production-ready integration in one to two days. A hosted page redirect takes less than a day. Full server-to-server API integration with a custom checkout UI typically takes one to two weeks and also requires a higher level of PCI DSS compliance work alongside the development effort.
Do I need to be PCI DSS certified to integrate a payment gateway?
Not certified in the formal sense, but you must be compliant. If you use a hosted page or drop-in UI (iFrame-based), your compliance burden is minimal and you complete a simple self-assessment questionnaire (SAQ A). If you handle raw card data on your own servers via a server-to-server API, you need SAQ D, which involves a rigorous audit. Most merchants choose the drop-in UI specifically to avoid this requirement.
What is a payment intent and why is it used?
A payment intent is a server-side object that represents a customer's intention to pay a specific amount. It tracks the payment state through authorisation, 3D Secure challenge, capture, and settlement. Using a payment intent model prevents double charges, enables reliable webhook tracking, and allows the payment to survive browser refreshes or dropped connections during checkout.
Can I test the integration without a live merchant account?
Yes. RoxPay provides a free sandbox environment accessible immediately upon registration. The sandbox mirrors production behaviour exactly and includes test cards for every scenario: approvals, declines, 3DS challenges, expired cards, and insufficient funds. No payment information or live account approval is required to begin testing.
You might also like
High Risk Payment Gateway
Secure payment processing for high-risk industries with multi-acquirer routing and chargeback protection.
Small Business Payment Solutions
Transparent IC++ pricing, free Smart POS terminal, and 24-hour activation for small businesses.
E-commerce Payment Integrations
One-click plugins for Shopify, WooCommerce, Magento, and PrestaShop with full API access.
Optimize your payments today
RoxPay provides a REST API with free sandbox access, full documentation, and settlement in 24-48 hours to any SEPA bank. PCI DSS Level 1 certified, IC++ pricing from 0.45%.
✓ No monthly fixed costs · ✓ Activation in 24 hours · ✓ Dedicated technical support
