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
| Aspect | Description |
|---|---|
| Integration | Reactive stores for methods, tokens, and payment state |
| UI Control | You build the entire checkout interface |
| Payment Methods | Access all methods via paymentMethods.subscribe() |
| Compliance | PCI-DSS compliant — secure fields handle sensitive data |
What You Build vs. What the SDK Handles
- SDK handles
- You build
- 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
- Complete checkout UI layout
- Payment method selection interface
- Pay button and form interactions
- Loading states and error display
- Custom styling and branding
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
| Scenario | Recommendation |
|---|---|
| Custom checkout design | ✅ Headless |
| Full UI control | ✅ Headless |
| Complex payment flows (split, gift cards) | ✅ Headless |
| Fast integration with minimal code | Consider Drop-in Checkout |
| Standard checkout flow | Consider 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