Custom checkout
Custom checkout integrations demand a flexible architecture for development teams building native application interfaces. Merchants can leverage a custom payment API to transmit raw transaction data directly between servers while routing volumes across an international acquirer partner network.
- Category
- Checkout
- Capabilities
- 6
- Available on
- All plans
Development teams managing complex digital products often outgrow templated user interfaces. Constructing a conversion-optimised payment flow requires absolute control over the Document Object Model, custom error handling for edge cases and the ability to dictate the precise rendering of card input fields on proprietary web applications.
Cardflo provides the backend infrastructure to support an API driven checkout architecture. Merchants transmit encrypted payload data directly from their servers to our orchestration layer. The platform evaluates the transaction against risk rules before directing the request to an appropriate acquirer partner without restricting the merchant interface design.
Cardflo's API-driven custom checkout provides direct access to our multi-acquirer network, enabling bespoke payment experiences and advanced SCA management. This flexibility allows for the optimisation of transaction lifecycles and significantly increases global approval ratios.
Custom checkout overview
Merchants handling unique customer journeys often require full technical ownership over the transaction lifecycle. By utilising a custom payment API, engineering teams can integrate payment processing natively into complex software environments without relying on third-party design constraints.
This server-to-server checkout API approach ensures the merchant retains complete programmatic control over input validation, network timeout handling and decline logic.
This architecture requires merchants to process raw card data and assume significant compliance obligations, unlike solutions that offload PCI requirements to a hosted payment page or rely on pre-built UI components through an embedded checkout widget. For operators focused on mobile wallet buttons, a mobile commerce checkout configuration offers a different technical path.
Cardflo acts purely as the orchestration layer, accepting raw payloads from the merchant server and routing them to a network of regulated acquirer partners for authorisation.
How custom checkout works
Server payload generation
The merchant application collects primary account numbers and expiry dates within a fully proprietary front-end interface built entirely by the internal engineering team. The backend server then formats this raw payment data into a JSON payload according to Cardflo specifications. This exact structure accommodates additional merchant-defined parameters, risk variables and mandatory authentication fields before initiating the transmission over a secure HTTPS connection.
API transmission and routing
The merchant server transmits the structured payload to the custom payment API endpoint. Cardflo evaluates the request against active orchestration rules, determining the optimal routing path based on the currency, region and card bin. The platform formats the request to match the specific technical expectations of the designated acquirer partner and submits it for authorisation.
Response parsing and UI updates
Cardflo receives the authorisation decision from the regulated acquirer partner and immediately returns a standardised API response to the merchant backend server. The merchant engineering team controls all application state logic, interpreting the network status code to either complete the order in the local database or trigger specific, custom decline messaging natively within the bespoke checkout integration interface.
Why custom checkout matters
Unrestricted interface design
Standardised widgets often clash with distinctive brand guidelines or complex user registration funnels. A server-to-server checkout API empowers merchants to design exact spacing, typography and animation for payment inputs. This native integration reduces friction in the conversion funnel, ensuring that buyers never experience visual dissonance or unexpected layout shifts during the critical final steps of a purchase.
Granular technical telemetry
Operating a bespoke frontend allows development teams to capture precise telemetry on user interaction, field abandonment and input latency. Merchants can analyse this proprietary data alongside network response times to continually optimise the conversion rate. By owning the full user flow, technical teams can deploy A/B testing on specific validation rules without waiting for third-party widget updates.
Regulatory notes for custom checkout
Cardholder data environment scope
Handling raw card data imposes stringent compliance obligations on the merchant organisation. The infrastructure collecting, transmitting or storing primary account numbers automatically becomes part of the regulated cardholder data environment.
This compliance scope encompasses all connected web servers, databases and internal networks interacting with the payment input fields prior to API transmission.
Businesses must implement continuous vulnerability scanning, network segmentation and access control measures.
Card scheme rules mandate that merchants conducting server-to-server transactions undergo thorough security assessments, often requiring an external Qualified Security Assessor to validate the network architecture before live volume can route to an acquirer partner.
API handling of SCA challenges
Even with complete control over the front-end interface, merchants operating within the European Economic Area must comply with the Payment Services Directive 2 and enforce Strong Customer Authentication. The API architecture must accommodate dynamic challenge flows for transactions that do not qualify for an exemption.
The merchant application is responsible for correctly displaying the authentication window provided by the issuing bank.
Card scheme mandates dictate that technical teams pass precise device telemetry and browser data in the API payload, allowing issuing banks to perform risk assessments and reduce unnecessary challenge prompts.
Custom checkout use cases
Inventory-linked order authorisation
Retailers with scarce or configurable stock must reserve inventory, recalculate tax and confirm delivery options before submitting an authorisation, without exposing stale totals. Cardflo’s custom payment API lets backend services control request sequencing, idempotency keys and capture timing while routing eligible transactions through the acquirer partner network.
In-app native card entry
Product teams building iOS and Android applications may need card fields, validation messages and recovery paths to follow native design systems rather than webview behaviour. Cardflo provides API access for tokenisation and server-side payment requests, while development teams retain control of field rendering, decline handling and 3DS2 challenge presentation.
Bespoke onboarding payment steps
Regulated services may collect identity evidence, select an account tier and take an initial card payment within one conditional onboarding journey, with errors returned at different stages. Cardflo’s API supports server-to-server payment initiation and structured response handling, allowing product teams to map validation, SCA and issuer declines to specific interface states.
Delayed capture fulfilment flows
Made-to-order merchants often authorise a card when production begins but capture only after goods pass inspection or enter fulfilment, requiring precise control over authorisation validity and order status. Cardflo enables backend systems to initiate, reference and capture transactions through its acquirer partners, with custom logic for expiry, cancellation and partial fulfilment.
Custom checkout by the numbers
Typical figures observed by enterprise merchants when moving from a multi-redirect hosted page to an integrated, single-domain checkout experience.
An industry benchmark for well-optimised custom flows, compared to higher abandonment rates often seen when third-party redirects increase friction.
The relative increase in successful mobile transactions frequently reported after customising gestures and form-factor elements for small-screen users.
Methodology: these figures are illustrative ranges drawn from published industry data and observed merchant cohorts, not guarantees. Actual results depend on your risk profile, card mix, geography and acquiring setup, and are confirmed only in your own pricing and approval terms.
Related terms
Talk to our team about a live rollout across our acquirer partners' rails.
What you get with Custom checkout
- Direct server-to-server communication enables development teams to construct native checkout experiences without front-end dependencies.
- Granular payload control allows developers to map bespoke transaction variables to specific acquirer partner requirements.
- Native error handling capabilities let engineers define custom retry logic and decline message rendering.
- Independent field validation logic gives merchants full control over character limits and data formatting rules.
- The white label payment API architecture keeps external branding absent from the entire transaction process.
- Synchronous webhook endpoints provide real-time notification capabilities for immediate backend state reconciliation after authorisation.
A short scoping call, then a written plan for your MIDs.
Questions about Custom checkout
What level of PCI DSS compliance is required for a server-to-server integration?
Merchants processing raw primary account numbers directly through their own infrastructure typically need to validate compliance against PCI DSS Level 1 or Level 2, depending on transaction volume, often completing a SAQ D.
Because the merchant server transmits sensitive card data to the custom payment API, the entire technical environment falls within the cardholder data environment scope.
Finance teams and technical architects must ensure robust network segmentation, logging and vulnerability management to satisfy external audits before routing volumes to an acquirer partner.
Can we implement 3D Secure authentication alongside a raw API integration?
Yes, merchants can integrate 3D Secure flows while maintaining control over the initial data collection. The merchant server initiates an authentication request via the API, and Cardflo returns the necessary challenge URLs or device fingerprinting parameters.
The engineering team must then render the issuer challenge window within an iframe or native webview on their proprietary interface. Once the user completes the authentication challenge, the application handles the callback and submits the final authorisation request containing the cryptographic validation cryptogram.
How does the orchestration layer handle disparate acquirer partner error codes?
Cardflo standardises network responses from the entire acquirer partner network into a uniform taxonomy. When a transaction is declined by an endpoint, the platform translates the specific proprietary error code into a consistent format before returning the payload to the merchant server.
This standardisation allows development teams to write a single set of error handling rules and decline state logic within their bespoke checkout integration, regardless of which underlying institution actually processed the transaction.
How should custom payment API integrations manage idempotency for duplicate requests?
Development teams should assign a unique idempotency key to each payment operation and retain it across retries caused by timeouts or uncertain responses. The merchant server should also store the relationship between its order reference, Cardflo transaction identifier and final payment state.
This prevents repeated API calls from creating unintended duplicate authorisations while allowing the original result to be retrieved or reconciled.
Related features.
Related guides.
See how Cardflo compares.
Ready to improve your payments setup?
Tell us about your business. We'll match you with the right acquiring partners and the right route, typically inside a week.