Skip to main content

Headless Checkout

The Headless Checkout SDK gives you full control over the checkout UI while Purse handles secure payment orchestration, validation, and execution.

What is Headless Checkout?​

Headless Checkout provides reactive stores and payment elements that you integrate into your own custom UI. You control the layout, design, and user experience — the SDK handles payment method orchestration, tokenization, and submission.

Not Fully Headless — By Design​

The term "headless" refers to your control over the checkout layout and flow, not the payment method UI itself. Each payment method is rendered through a PaymentElement — a web component that displays the partner's UI for that method (Stripe's card form, PayPal's button, Klarna's widget, Adyen's Apple Pay, etc.).

This means:

  • You control: Checkout layout, method selection UI, pay button, loading states, and overall user flow
  • SDK renders: The partner's payment UI via PaymentElement

This hybrid approach gives you flexibility over the checkout experience while ensuring PCI-DSS compliance and consistent payment method rendering across all providers.

Key Characteristics​

AspectDescription
IntegrationReactive stores for methods, tokens, and payment state
UI ControlYou build the entire checkout interface
Payment MethodsAccess all methods via paymentMethods.subscribe()
CompliancePCI-DSS compliant — secure fields handle sensitive data

What You Build vs. What the SDK Handles​

  • Payment method availability and configuration
  • Secure input fields (PaymentElement)
  • Card validation and tokenization
  • Payment orchestration and routing
  • 3D Secure and redirect flows
  • Amount split calculations

Requirements​

  • Client session: Obtained from the Purse API
  • Payment methods: At least one method activated in your Purse dashboard
  • Browser: Chrome, Firefox, Safari, or Edge (current and previous major versions)
  • JavaScript knowledge: Familiarity with reactive patterns (subscribe/unsubscribe)

When to Choose Headless Checkout​

ScenarioRecommendation
Custom checkout design✅ Headless
Full UI control✅ Headless
Complex payment flows (split, gift cards)✅ Headless
Fast integration with minimal codeConsider Drop-in Checkout
Standard checkout flowConsider Drop-in Checkout

Supported Payment Methods​

The Headless Checkout supports a wide range of payment methods:

  • Cards: Via ACI, Adyen, Axepta, CentralPay, Checkout, HiPay, Ingenico, Mercanet, Oney, Paybox, Payline, Payzen, Redsys, Scellius, Stripe, WorldPay
  • Digital wallets: Apple Pay, Google Pay, PayPal
  • Buy Now Pay Later: Alma, Floa, Klarna, Oney, Riverty, Scalapay
  • Bank payments: Bancontact, iDEAL, SEPA, MBWay, Bizum, Multibanco, Twint
  • Alternative methods: Gift cards (Buybox, Easy2Play, Illicado, Ogloba), vouchers, loyalty cards

Next Steps​

Getting Started

Step-by-step integration guide

Key Concepts

Understand stores, methods, and elements

Advanced Guides

Gift cards, wallets, saved methods, and more

SDK Reference

Complete API documentation