SDK reference
The complete reference is the KDoc of the published artifacts, generated from the code at every release: your IDE shows it from the javadoc jar Maven Central serves, and each GitHub release attaches the same reference as browsable HTML. This page is the map of the public surface; names are the Kotlin ones.
Packages
| Package | Mirrors (web) | Holds |
|---|---|---|
eu.purse.checkout | @upstreampay/headless-checkout | PurseHeadlessCheckout, PurseCheckoutHooks, PurseCheckoutException; element.rememberPaymentElement, payment.item.*, state.* |
eu.purse.partnerui | @upstreampay/partner-ui | PaymentElementListener, PaymentOutcome, PluginOptions, PurseTheme, CardFormTexts, PluginRegistry, PluginEvent, PartnerUiException, the coordinators, redirect.RedirectAction |
eu.purse.core | sdk, model, common | environment.PurseEnvironment, payment.Partner, Method, MethodKey, error.PurseErrorCode, PurseException, api.PaymentApiException, session.PurseSessionException |
Entry points
fun PurseHeadlessCheckout.Companion.init(
widgetData: String,
lockedEnvironment: PurseEnvironment? = null,
hooks: PurseCheckoutHooks? = null,
options: PluginOptions = PluginOptions(),
disabledMethods: Set<MethodKey> = emptySet(),
): PurseHeadlessCheckout
fun PurseHeadlessCheckout.Companion.restore(
state: CheckoutSavedState,
hooks: PurseCheckoutHooks? = null,
options: PluginOptions = PluginOptions(),
): PurseHeadlessCheckout
| Parameter | Meaning |
|---|---|
widgetData | The base64 widget.data string of the client session |
lockedEnvironment | Overrides the environment the session declares; release builds must pass PurseEnvironment.PRODUCTION |
hooks | onBeforeValidate, onAfterValidate, onRedirection |
options | locale, cardFormTexts, theme |
disabledMethods | (partner, method) pairs this build never lists, whatever the session offers; scoped to the instance |
state | A CheckoutSavedState from saveState(), or CheckoutSavedState.fromJson() |
PurseHeadlessCheckout.VERSION is the SDK version; checkout.instanceId identifies one checkout in Purse's monitoring.
Reactive state (StateFlow)
| Property | Type | Changes when |
|---|---|---|
sessionState | SessionState | READY → SUBMITTING → SUBMITTED / ERROR; EXPIRED, TERMINATED |
paymentSession | PaymentSession | The session in force; emits again after setSession |
paymentMethods | List<PaymentItem> | Primaries and gift cards, each with its live disabled state |
paymentTokens | List<PaymentToken> | Saved cards and saved PayPal accounts |
savedSecondaryTokens | List<SavedSecondaryToken> | Saved gift cards, balances resolving in the background |
remainingAmountToPay | BigDecimal | After setPrimary, applySecondary, removeSecondary |
amountSplit | List<PaymentSplit> | The slices submitPayment will send |
isPaymentFulfilled | Boolean | The split covers the amount and every form in it is valid |
itemGenerations | Map<String, Int> | Bumped by setSession for items that were rebuilt |
pluginEvents | SharedFlow<CheckoutPluginEvent> | Every partner lifecycle event, keyed by item id |
isTornDown | Boolean | After teardown() |
Plain properties: session, currency, currentSessionId, primaryMethods, secondaryMethods, appliedSecondaries, options, disabledMethods.
Functions
| Group | Functions |
|---|---|
| Split | setPrimary(method?), clearPrimarySplit(), setPrimaryToken(token), applySecondary(token, amount?), removeSecondary(token) (both for SecondaryToken and SavedSecondaryToken) |
| Gift cards | secondaryConfig(method), getSecondaryToken(method, pan, cvv?) (suspend), registerSecondary(token, registered, name?), registrationOf(token) |
| Saving | register(method, registered, name?), registrationOf(method) |
| Wallet (suspend) | editToken(token, name), setTokenFavorite(token), deleteToken(token), deleteAllTokens(); editToken and deleteToken also for SavedSecondaryToken |
| Submit | submitPayment(skipOnBeforeValidate = false) (suspend) |
| BNPL (suspend) | simulateLoan(method, product), simulateLoans(method, product) |
| Session | setSession(widgetData) (suspend), saveState(), teardown() |
| Assets | iconUrl(item), schemeAssets(method) |
| Extension | host(item) for a coordinator you drive yourself; PluginRegistry.getPlugin, register*, install(module); SecondaryConfigs.register; CheckoutEventBus.getInstance().subscribe { } |
Every suspend function runs its network call on Dispatchers.IO; call them from any dispatcher.
Payment element
@Composable
fun rememberPaymentElement(
checkout: PurseHeadlessCheckout,
item: PaymentItem,
listener: PaymentElementListener = object : PaymentElementListener {},
klarnaReturnUrl: String? = null,
): PaymentElement
@Composable
fun PaymentElementUi(element: PaymentElement, modifier: Modifier = Modifier)
PaymentElement exposes item, hasUi, selfSubmitting, ready and submit(). PaymentElementListener has onReady(ready), onOutcome(outcome), onRequiresAction() and onPaymentId(id), every member with a default.
sealed class PaymentOutcome {
data class Completed(val result: ValidationResult) // status: PaymentStatus, isSuccess
data object ReturnedFromRedirect // not an outcome: your backend confirms
data object Canceled
data class Failed(val error: PurseException) // error.code: PurseErrorCode
}
Coordinators, for an app that draws a wallet button or drives a native step itself: rememberCardCoordinator(host, listener) and rememberRedirectionCoordinator(listener) (in the SDK), rememberGooglePayCoordinator(listener), rememberPaypalCoordinator(listener) and rememberKlarnaCoordinator(listener) (in their artifacts). Only the card coordinator takes its PluginHost (from checkout.host(item)) at creation; the others receive it later through coordinator.prepare(host).
Types
| Type | Notes |
|---|---|
PaymentItem (sealed) | PrimaryMethod, SecondaryMethod, PaymentToken, SavedSecondaryToken; id, partner, method, disabled: DisabledState?, isSecondary, minAmount, maxAmount |
PrimaryMethod | canBeRegistered, simulable, integrationType, supportedBrands |
PaymentToken | isVaultedCard, requiresCvv, label, brand, maskedPan, holderName, favorite, tokenSource |
SecondaryToken, SavedSecondaryToken | pan, balance; SecondaryToken adds canBeRegistered, saved ones add balanceResolved, disabled |
DisabledState (sealed) | code, message, isFiltered, isTechnicallyDisabled, requiresUiClear, isRecoverable, isRecomputable; see Method states |
PaymentSplit | amount, source |
MethodKey | partner + method; id is the item id ("paypal-wallet") |
Partner, Method (sealed) | Purse, Paypal, Klarna, Illicado, … and Other(wireValue); CreditCard, GooglePay, Wallet, Installments, GiftCard, … and Other(wireValue) |
CheckoutSavedState | Parcelable snapshot from saveState(); toJson(), fromJson(), submitted, savedAt |
LoanProduct, LoanSimulation | Input and output of BNPL simulation |
ValidationResult | status: PaymentStatus, globalStatus, isSuccess, redirection, raw |
PaymentStatus (enum) | SUCCESS, FAILED, ERROR, UNCERTAIN, WAITING, UNKNOWN: the API's global_status |
RedirectAction (sealed) | Get(url), PostForm, PostHtml; what onRedirection receives |
PluginEvent (sealed) | Ready, Redirect, InitFailed, ClientError, PartnerError(recoverable), Cancelled, EndOfSession |
PurseException (abstract) | code: PurseErrorCode, documentationLink; subclasses in Error codes |
PurseTheme, CardFormTexts, PluginOptions | Presentation options, see Customization |
Extending the SDK
SecondaryConfig adds a gift card issuer; PartnerUiPlugin plus a PartnerModule add a payment method with its own Compose surface, registered with PluginRegistry.install. Both are documented in the KDoc. Declarations marked @InternalPurseApi are the seams the partner artifacts use and carry no compatibility promise.