Android SDK
The Android SDK is the native counterpart of the web Headless Checkout: the same concepts (client session, payment methods, primary and secondary methods, split, submit) in Kotlin and Jetpack Compose. You build the checkout screen; the SDK exposes the session's payment methods as reactive state, renders each method's own step (a secure card form, Google Pay's button, Klarna's widget, a PSP page) and drives the payment to its outcome.
How it works
Key characteristics
| Aspect | Detail |
|---|---|
| Integration | StateFlow for methods, tokens, amounts and session state; one composable, rememberPaymentElement, renders any method |
| UI control | You build the whole checkout screen; the SDK renders only each method's own step |
| Payment methods | Card (Purse vault), Google Pay, PayPal, Klarna, every redirection method the session offers, gift cards, saved cards and saved PayPal accounts, BNPL instalment simulation |
| Compliance | Card data is captured by the embedded Android Secure Fields and never reaches your code |
| Distribution | Maven Central, group eu.purse: one SDK artifact plus one optional artifact per partner SDK |
| Web parity | Same session, same /init and /validate contract, same error codes and method states as the web SDK |
Artifacts
| Artifact | Contents | Add it when |
|---|---|---|
eu.purse:headless-checkout-android | Engine, payment elements, card and redirection methods, gift cards, saved methods | Always |
eu.purse:headless-checkout-googlepay | Google Pay plugin and Play Services Wallet | You offer Google Pay |
eu.purse:headless-checkout-klarna | Klarna plugin and the Klarna Mobile SDK | You offer Klarna |
eu.purse:headless-checkout-paypal | PayPal plugin and the PayPal Android SDK | You offer PayPal |
A merchant offering cards only embeds none of the partner SDKs. A partner artifact registers its payment method by itself once it is on the classpath; the four artifacts release together and share one version number. What each partner needs from your project is on its own page under Payment methods.
Requirements
| Requirement | Value |
|---|---|
| Minimum Android SDK | 26 (Android 8.0) |
| Compile SDK | 37 |
| Kotlin | 2.x; the SDK is compiled with Kotlin 2.4.20, use the same version or later |
| UI | Jetpack Compose (a View-based screen hosts the payment element in a ComposeView) |
| Client session | Created by your backend with the Purse API; the app receives its widget.data string |
When to use this SDK
| Scenario | Recommendation |
|---|---|
| Native Android checkout with your own design | ✅ Android SDK |
| Web checkout with your own design | Headless Checkout (web) |
| Collect card data only and pay server-side | Android Secure Fields |
| Fastest integration, standard checkout | Drop-in Checkout in a web view, or Hosted Page |
What you build vs. what the SDK handles
- SDK handles
- You build
- Decoding the client session and listing what it offers
- Each method's own step: secure card form, wallet sheet or button, Klarna widget, PSP page
/initand/validatecalls, 3-D Secure and redirect returns- Amount split between a primary method and gift cards
- Saved cards and accounts, wallet management, BNPL simulation
- Refusing a double submit, an expired or an already paid session
- Snapshot and restore across process death (
saveState/restore)
- The checkout screen and its navigation
- The method list and the selection UI
- The Pay button (except for Google Pay and PayPal, which bring their own)
- Loading, success and failure screens
- Styling of the card form through the theme
How this documentation is organized
Like the other Purse SDKs, this section follows the Diátaxis framework: each page is one of four kinds, and never mixes them.
| Kind | Read it to | Pages |
|---|---|---|
| Tutorial | Learn by doing | Getting started: a card payment in sandbox from an empty project |
| How-to guides | Solve one task | Payment methods, one guide per method · Advanced guides · Error handling · Run the sample app |
| Reference | Look something up | SDK reference · Error codes · Method states · Supported payment methods · Changelog |
| Explanation | Understand the model | This page · Key concepts |
The generated KDoc reference of every public declaration ships with each release and as the javadoc jar your IDE reads from Maven Central.
Known limitations
- Purse 3-D Secure is not supported yet. Card payments are authenticated only by the PSP's own 3-D Secure, which the SDK presents as a redirection. 3-D Secure run by Purse, as the Web SDK does with
threeDSChallenge, has no equivalent in this SDK.