Setup and lifecycle

Install the SDK, initialize a session, and manage the checkout screen’s lifecycle.

Use one SDK instance per checkout screen. Initialize it with a payment session from your server, then keep it alive until the checkout is permanently released.

Installation and requirements

Obtain the Android Maven repository and version, or the Swift package, from ePay. iOS integration and device flows are still awaiting validation.

	Android	iOS
Minimum platform	Android API 23	iOS 16 for the standard Swift package
Distribution	Maven dependency `eu.epay:sdk-android`	Swift Package Manager, product `EpaySDK`
Import	`eu.epay.sdk.*`	`EpayPayPal` (includes the standard host and SDK API)
Owning screen	`Activity`	`UIViewController`
Asynchronous queries	Kotlin suspending functions	Swift `async throws`
Wallet	Google Pay	Apple Pay

Add the Maven repository supplied by ePay to your Gradle settings and the supplied SDK version to your app dependencies.

Initialize a checkout

Helpers such as showError and renderPayment represent your app’s UI. Retain the SDK as a screen property. Make configuration, lifecycle, and payment-start calls on the main/UI thread.

Initialize after setting up the Activity's content view. Run this code in the owning Activity, where lifecycleScope is available.

import eu.epay.sdk.*import androidx.lifecycle.lifecycleScopeimport kotlinx.coroutines.launch// Retain sdk as an Activity property.val sdk = Epay(AndroidPaymentHost(this))sdk.onStateChanged = { state -> showSdkState(state) }sdk.events.error = { error -> showError(error.message) }lifecycleScope.launch {    try {        sdk.initialize(sessionId, sessionKey)        showPaymentMethods(sdk.getSupportedPaymentMethodTypes())    } catch (error: EpayException) {        showError(error.message)    }}

Call sdk.dispose() from the owning screen's cleanup, such as onDestroy().

Lifecycle reference

Epay reference

initialize(sessionId, sessionKey)

Initialize with the supplied payment session and wait until ready. Replaces any previous session and invalidates its fields and age-verification object. Throws on failure or initialization timeout (30 seconds).

Kotlin suspend · Swift async throws

Parameters

sessionIdStringrequired: ID returned when your server creates the payment session.
sessionKeyStringrequired: Session key returned with that same payment session.

Returns Unit / Void

Throws EpayException. See error handling.

init(sessionId, sessionKey) / Swift startInitialization(sessionId:sessionKey:)

Start initialization without awaiting readiness; observe onStateChanged. Prefer initialize for sequential setup.

Parameters

sessionIdStringrequired: ID returned when your server creates the payment session.
sessionKeyStringrequired: Session key returned with that same payment session.

Returns Unit / Void

stateSdkStatenullable

Last reported SdkState, initially null / nil.

Values · SdkState

Readiness shared by the SDK and mounted card fields. Observe each object separately.

Loadingvalue: Initialization is in progress; operations requiring readiness are unavailable.
Readyvalue: Initialization completed successfully and the object is ready for use.
Failedvalue: Initialization failed or the object was disposed. It cannot perform operations requiring readiness.

onStateChangedCallback<SdkState>nullable

Optional callback for Loading, Ready, and Failed. Set before initialization.

eventsSdkEvents

Payment events and interactive decisions. Register before starting payments.

Properties · SdkEvents

Optional checkout event callbacks delivered on the UI thread. Use payment-attempt updates for the complete payment lifecycle.

transactionAcceptedCallback<TransactionAccepted>optionalnullable

Called when a transaction is accepted. Use server notifications to confirm the order before fulfilment.

Properties · TransactionAccepted

Notification that a transaction was accepted.

transactionIdStringnullable: Server transaction ID, or null when the event does not provide one.

transactionDeclinedCallback<TransactionDeclined>optionalnullable

Called when an authorization is declined. A payment attempt may continue through another authorization, so observe its state for the final outcome.

Properties · TransactionDeclined

Notification that an authorization was declined.

transactionIdStringnullable: Server transaction ID, or null when the event does not provide one.
maxAttemptsReachedBoolean: Whether the session has exhausted its permitted payment attempts and cannot be retried.

feeUpdatedCallback<FeeUpdated>optionalnullable

Called when the displayed payment fee changes. A zero fee clears a previously displayed fee.

Properties · FeeUpdated

Notification that the fee shown to the customer has changed.

feeLong: Current fee in minor units of the session currency. Zero clears a previously displayed fee.

confirmSurchargeCallback<Surcharge, SurchargeDecision>optionalnullable

Called before continuing with a surcharge. Show the amount and call confirm() or cancel() on the supplied decision. If no handler is set, the surcharge is accepted.

Properties · Surcharge

Fee and revised payment amount presented for customer confirmation. All amounts are in minor units of the session currency.

paymentMethodTypeString: Payment-method type to which the surcharge applies.
paymentMethodSubTypeStringnullable: More specific payment-method type, such as the card scheme, when available.
originalAmountLong: Payment amount before applying the surcharge.
updatedAmountLong: Total payment amount including the surcharge.
feeLong: Surcharge added to the original amount.
minimumFeeLong: Minimum fee configured for the surcharge.
flatFeeLong: Fixed fee component of the surcharge.
percentageDouble: Percentage fee rate, for example 2.5 for 2.5%.

paymentCancelCallback<PaymentCancel>optionalnullable

Notifies the app that a payment flow was cancelled. Observe the payment attempt for its resulting state.

Properties · PaymentCancel

Notification that a payment flow was cancelled.

paymentMethodTypeString: Type of payment method whose flow was cancelled.

clientRedirectCallback<ClientRedirect>optionalnullable

Notifies the app when the SDK opens an authentication or payment-provider flow. The SDK manages presentation and returns.

Properties · ClientRedirect

Information about an authentication or payment-provider flow presented by the SDK.

urlString: Destination URL opened for the flow.
reasonString: Reason for opening the flow, such as SCA, PAYMENT_METHOD, or AGE_VERIFICATION.

errorCallback<SdkError>optionalnullable

Receives a structured SDK error notification. Query failures are also reported through the corresponding thrown exception.

Properties · SdkError

Error details supplied through SDK events or a payment attempt.

errorCodeString: Machine-readable error code for identifying the failure.
messageString: Description of the failure for diagnostics. Use getClientMessage() when displaying a localized message to the customer.

payment()

Create reusable payment options and handlers.

Returns Payment

Properties · Payment

Reusable payment configuration obtained from sdk.payment(). Each create method starts an attempt using the current options and returns a PaymentAttempt to observe.

optionsTransactionOptions

Amount, note, and storage-consent settings applied to new attempts.

Properties · TransactionOptions

Options applied when starting a payment. Each attempt takes a snapshot, so later changes affect future attempts only.

amountLongoptionalnullable

Optional amount in minor units. Set only when the session has dynamicAmount: true; otherwise leave unset so the session determines the amount. Nonnegative, at most 9007199254740991.

noteStringoptionalnullable

Optional transaction note supplied with the payment.

storeBooleanoptionalnullable

Customer’s consent to store the payment method for future use. Set true only after consent; the session must support storing payment methods.

setStorageConsent(store)

Set the storage-consent option and return this same options object. Useful when setting a Kotlin nullable Boolean from Swift.

Parameters

storeBooleanrequired: Whether the customer has consented to saving the payment method.

Returns TransactionOptions

TransactionOptions reference

handlersPaymentAttemptHandlers

Callbacks attached to each new attempt started through this payment object.

Properties · PaymentAttemptHandlers

Callbacks copied to each attempt created by a payment object.

onUpdateCallback<PaymentAttempt>optionalnullable: Observe updates for each new attempt on the UI thread.

createCardTransaction()

Start a payment with the entered card details. The fields must be ready and valid, and their payment-button state must be active.

Returns PaymentAttempt

Properties · PaymentAttempt

Observable result of starting a payment. Observe onUpdate for progress and outcomes; use server notifications to confirm fulfilment.

idString

Local correlation ID, distinct from the server transaction ID.

statePaymentAttemptState

Current payment progress or outcome. Read canRetry before offering another attempt.

Values · PaymentAttemptState

Current outcome of a payment attempt. Use these states to display progress and decide whether to offer another attempt.

Processingvalue: The payment is in progress or waiting for customer interaction. Show progress and prevent another payment.
Acceptedvalue: The transaction was accepted. Show confirmation and use server notifications for fulfilment.
Declinedvalue: The payment was declined. Offer another attempt only when canRetry is true.
Cancelledvalue: The flow was cancelled; check canRetry before offering another attempt.
Failedvalue: The attempt could not complete because of an error. Show the error and retry only when canRetry and SDK readiness permit it.
OutcomeUnknownvalue: The SDK cannot establish the outcome of a submitted payment. Show “Awaiting payment confirmation” and resolve status through your backend before offering another payment.

transactionIdStringnullable

Server transaction ID when available; may be absent.

errorSdkErrornullable

Structured error details when available.

Properties · SdkError

Error details supplied through SDK events or a payment attempt.

errorCodeString: Machine-readable error code for identifying the failure.
messageString: Description of the failure for diagnostics. Use getClientMessage() when displaying a localized message to the customer.

canRetryBoolean

Whether this attempt permits another payment. The SDK must also be ready with no active interaction. False after acceptance, exhausted attempts, or an unknown outcome.

maxAttemptsReachedBoolean

The session's decline limit has been reached.

isRedirectingBoolean

A payment redirect is being presented.

pendingSurchargeSurchargenullable

Current surcharge confirmation, if any. Respond through events.confirmSurcharge.

Properties · Surcharge

Fee and revised payment amount presented for customer confirmation. All amounts are in minor units of the session currency.

paymentMethodTypeString: Payment-method type to which the surcharge applies.
paymentMethodSubTypeStringnullable: More specific payment-method type, such as the card scheme, when available.
originalAmountLong: Payment amount before applying the surcharge.
updatedAmountLong: Total payment amount including the surcharge.
feeLong: Surcharge added to the original amount.
minimumFeeLong: Minimum fee configured for the surcharge.
flatFeeLong: Fixed fee component of the surcharge.
percentageDouble: Percentage fee rate, for example 2.5 for 2.5%.

metadataPaymentAttemptMetadata

Additional information about the authorization history of this attempt.

Properties · PaymentAttemptMetadata

Additional authorization history for the payment attempt.

hadDeclinedAuthorizationBoolean: A wallet authorization was definitively declined during this attempt.

onUpdateCallback<PaymentAttempt>nullable

Receives the current attempt immediately, then subsequent updates on the UI thread.

createVippsMobilePayTransaction()

Start a Vipps MobilePay payment. Configure the app return URL on iOS so the customer can return to checkout.

Returns PaymentAttempt

Properties · PaymentAttempt

Observable result of starting a payment. Observe onUpdate for progress and outcomes; use server notifications to confirm fulfilment.

idString

Local correlation ID, distinct from the server transaction ID.

statePaymentAttemptState

Current payment progress or outcome. Read canRetry before offering another attempt.

Values · PaymentAttemptState

Current outcome of a payment attempt. Use these states to display progress and decide whether to offer another attempt.

Processingvalue: The payment is in progress or waiting for customer interaction. Show progress and prevent another payment.
Acceptedvalue: The transaction was accepted. Show confirmation and use server notifications for fulfilment.
Declinedvalue: The payment was declined. Offer another attempt only when canRetry is true.
Cancelledvalue: The flow was cancelled; check canRetry before offering another attempt.
Failedvalue: The attempt could not complete because of an error. Show the error and retry only when canRetry and SDK readiness permit it.
OutcomeUnknownvalue: The SDK cannot establish the outcome of a submitted payment. Show “Awaiting payment confirmation” and resolve status through your backend before offering another payment.

transactionIdStringnullable

Server transaction ID when available; may be absent.

errorSdkErrornullable

Structured error details when available.

Properties · SdkError

Error details supplied through SDK events or a payment attempt.

errorCodeString: Machine-readable error code for identifying the failure.
messageString: Description of the failure for diagnostics. Use getClientMessage() when displaying a localized message to the customer.

canRetryBoolean

Whether this attempt permits another payment. The SDK must also be ready with no active interaction. False after acceptance, exhausted attempts, or an unknown outcome.

maxAttemptsReachedBoolean

The session's decline limit has been reached.

isRedirectingBoolean

A payment redirect is being presented.

pendingSurchargeSurchargenullable

Current surcharge confirmation, if any. Respond through events.confirmSurcharge.

Properties · Surcharge

Fee and revised payment amount presented for customer confirmation. All amounts are in minor units of the session currency.

paymentMethodTypeString: Payment-method type to which the surcharge applies.
paymentMethodSubTypeStringnullable: More specific payment-method type, such as the card scheme, when available.
originalAmountLong: Payment amount before applying the surcharge.
updatedAmountLong: Total payment amount including the surcharge.
feeLong: Surcharge added to the original amount.
minimumFeeLong: Minimum fee configured for the surcharge.
flatFeeLong: Fixed fee component of the surcharge.
percentageDouble: Percentage fee rate, for example 2.5 for 2.5%.

metadataPaymentAttemptMetadata

Additional information about the authorization history of this attempt.

Properties · PaymentAttemptMetadata

Additional authorization history for the payment attempt.

hadDeclinedAuthorizationBoolean: A wallet authorization was definitively declined during this attempt.

onUpdateCallback<PaymentAttempt>nullable

Receives the current attempt immediately, then subsequent updates on the UI thread.

createTwintTransaction()

Start a TWINT payment using the current transaction options. The SDK presents the provider flow and reports progress through the returned attempt.

Returns PaymentAttempt

Properties · PaymentAttempt

Observable result of starting a payment. Observe onUpdate for progress and outcomes; use server notifications to confirm fulfilment.

idString

Local correlation ID, distinct from the server transaction ID.

statePaymentAttemptState

Current payment progress or outcome. Read canRetry before offering another attempt.

Values · PaymentAttemptState

Current outcome of a payment attempt. Use these states to display progress and decide whether to offer another attempt.

Processingvalue: The payment is in progress or waiting for customer interaction. Show progress and prevent another payment.
Acceptedvalue: The transaction was accepted. Show confirmation and use server notifications for fulfilment.
Declinedvalue: The payment was declined. Offer another attempt only when canRetry is true.
Cancelledvalue: The flow was cancelled; check canRetry before offering another attempt.
Failedvalue: The attempt could not complete because of an error. Show the error and retry only when canRetry and SDK readiness permit it.
OutcomeUnknownvalue: The SDK cannot establish the outcome of a submitted payment. Show “Awaiting payment confirmation” and resolve status through your backend before offering another payment.

transactionIdStringnullable

Server transaction ID when available; may be absent.

errorSdkErrornullable

Structured error details when available.

Properties · SdkError

Error details supplied through SDK events or a payment attempt.

errorCodeString: Machine-readable error code for identifying the failure.
messageString: Description of the failure for diagnostics. Use getClientMessage() when displaying a localized message to the customer.

canRetryBoolean

Whether this attempt permits another payment. The SDK must also be ready with no active interaction. False after acceptance, exhausted attempts, or an unknown outcome.

maxAttemptsReachedBoolean

The session's decline limit has been reached.

isRedirectingBoolean

A payment redirect is being presented.

pendingSurchargeSurchargenullable

Current surcharge confirmation, if any. Respond through events.confirmSurcharge.

Properties · Surcharge

Fee and revised payment amount presented for customer confirmation. All amounts are in minor units of the session currency.

paymentMethodTypeString: Payment-method type to which the surcharge applies.
paymentMethodSubTypeStringnullable: More specific payment-method type, such as the card scheme, when available.
originalAmountLong: Payment amount before applying the surcharge.
updatedAmountLong: Total payment amount including the surcharge.
feeLong: Surcharge added to the original amount.
minimumFeeLong: Minimum fee configured for the surcharge.
flatFeeLong: Fixed fee component of the surcharge.
percentageDouble: Percentage fee rate, for example 2.5 for 2.5%.

metadataPaymentAttemptMetadata

Additional information about the authorization history of this attempt.

Properties · PaymentAttemptMetadata

Additional authorization history for the payment attempt.

hadDeclinedAuthorizationBoolean: A wallet authorization was definitively declined during this attempt.

onUpdateCallback<PaymentAttempt>nullable

Receives the current attempt immediately, then subsequent updates on the UI thread.

createWeroTransaction()

Start a Wero payment using the current transaction options. The SDK presents the provider flow and reports progress through the returned attempt.

Returns PaymentAttempt

Properties · PaymentAttempt

Observable result of starting a payment. Observe onUpdate for progress and outcomes; use server notifications to confirm fulfilment.

idString

Local correlation ID, distinct from the server transaction ID.

statePaymentAttemptState

Current payment progress or outcome. Read canRetry before offering another attempt.

Values · PaymentAttemptState

Current outcome of a payment attempt. Use these states to display progress and decide whether to offer another attempt.

Processingvalue: The payment is in progress or waiting for customer interaction. Show progress and prevent another payment.
Acceptedvalue: The transaction was accepted. Show confirmation and use server notifications for fulfilment.
Declinedvalue: The payment was declined. Offer another attempt only when canRetry is true.
Cancelledvalue: The flow was cancelled; check canRetry before offering another attempt.
Failedvalue: The attempt could not complete because of an error. Show the error and retry only when canRetry and SDK readiness permit it.
OutcomeUnknownvalue: The SDK cannot establish the outcome of a submitted payment. Show “Awaiting payment confirmation” and resolve status through your backend before offering another payment.

transactionIdStringnullable

Server transaction ID when available; may be absent.

errorSdkErrornullable

Structured error details when available.

Properties · SdkError

Error details supplied through SDK events or a payment attempt.

errorCodeString: Machine-readable error code for identifying the failure.
messageString: Description of the failure for diagnostics. Use getClientMessage() when displaying a localized message to the customer.

canRetryBoolean

Whether this attempt permits another payment. The SDK must also be ready with no active interaction. False after acceptance, exhausted attempts, or an unknown outcome.

maxAttemptsReachedBoolean

The session's decline limit has been reached.

isRedirectingBoolean

A payment redirect is being presented.

pendingSurchargeSurchargenullable

Current surcharge confirmation, if any. Respond through events.confirmSurcharge.

Properties · Surcharge

Fee and revised payment amount presented for customer confirmation. All amounts are in minor units of the session currency.

paymentMethodTypeString: Payment-method type to which the surcharge applies.
paymentMethodSubTypeStringnullable: More specific payment-method type, such as the card scheme, when available.
originalAmountLong: Payment amount before applying the surcharge.
updatedAmountLong: Total payment amount including the surcharge.
feeLong: Surcharge added to the original amount.
minimumFeeLong: Minimum fee configured for the surcharge.
flatFeeLong: Fixed fee component of the surcharge.
percentageDouble: Percentage fee rate, for example 2.5 for 2.5%.

metadataPaymentAttemptMetadata

Additional information about the authorization history of this attempt.

Properties · PaymentAttemptMetadata

Additional authorization history for the payment attempt.

hadDeclinedAuthorizationBoolean: A wallet authorization was definitively declined during this attempt.

onUpdateCallback<PaymentAttempt>nullable

Receives the current attempt immediately, then subsequent updates on the UI thread.

createIdealTransaction()

Start a iDEAL payment using the current transaction options. The SDK presents the provider flow and reports progress through the returned attempt.

Returns PaymentAttempt

Properties · PaymentAttempt

Observable result of starting a payment. Observe onUpdate for progress and outcomes; use server notifications to confirm fulfilment.

idString

Local correlation ID, distinct from the server transaction ID.

statePaymentAttemptState

Current payment progress or outcome. Read canRetry before offering another attempt.

Values · PaymentAttemptState

Current outcome of a payment attempt. Use these states to display progress and decide whether to offer another attempt.

Processingvalue: The payment is in progress or waiting for customer interaction. Show progress and prevent another payment.
Acceptedvalue: The transaction was accepted. Show confirmation and use server notifications for fulfilment.
Declinedvalue: The payment was declined. Offer another attempt only when canRetry is true.
Cancelledvalue: The flow was cancelled; check canRetry before offering another attempt.
Failedvalue: The attempt could not complete because of an error. Show the error and retry only when canRetry and SDK readiness permit it.
OutcomeUnknownvalue: The SDK cannot establish the outcome of a submitted payment. Show “Awaiting payment confirmation” and resolve status through your backend before offering another payment.

transactionIdStringnullable

Server transaction ID when available; may be absent.

errorSdkErrornullable

Structured error details when available.

Properties · SdkError

Error details supplied through SDK events or a payment attempt.

errorCodeString: Machine-readable error code for identifying the failure.
messageString: Description of the failure for diagnostics. Use getClientMessage() when displaying a localized message to the customer.

canRetryBoolean

Whether this attempt permits another payment. The SDK must also be ready with no active interaction. False after acceptance, exhausted attempts, or an unknown outcome.

maxAttemptsReachedBoolean

The session's decline limit has been reached.

isRedirectingBoolean

A payment redirect is being presented.

pendingSurchargeSurchargenullable

Current surcharge confirmation, if any. Respond through events.confirmSurcharge.

Properties · Surcharge

Fee and revised payment amount presented for customer confirmation. All amounts are in minor units of the session currency.

paymentMethodTypeString: Payment-method type to which the surcharge applies.
paymentMethodSubTypeStringnullable: More specific payment-method type, such as the card scheme, when available.
originalAmountLong: Payment amount before applying the surcharge.
updatedAmountLong: Total payment amount including the surcharge.
feeLong: Surcharge added to the original amount.
minimumFeeLong: Minimum fee configured for the surcharge.
flatFeeLong: Fixed fee component of the surcharge.
percentageDouble: Percentage fee rate, for example 2.5 for 2.5%.

metadataPaymentAttemptMetadata

Additional information about the authorization history of this attempt.

Properties · PaymentAttemptMetadata

Additional authorization history for the payment attempt.

hadDeclinedAuthorizationBoolean: A wallet authorization was definitively declined during this attempt.

onUpdateCallback<PaymentAttempt>nullable

Receives the current attempt immediately, then subsequent updates on the UI thread.

createSwishTransaction()

Start a Swish payment using the current transaction options. The SDK presents the provider flow and reports progress through the returned attempt.

Returns PaymentAttempt

Properties · PaymentAttempt

Observable result of starting a payment. Observe onUpdate for progress and outcomes; use server notifications to confirm fulfilment.

idString

Local correlation ID, distinct from the server transaction ID.

statePaymentAttemptState

Current payment progress or outcome. Read canRetry before offering another attempt.

Values · PaymentAttemptState

Current outcome of a payment attempt. Use these states to display progress and decide whether to offer another attempt.

Processingvalue: The payment is in progress or waiting for customer interaction. Show progress and prevent another payment.
Acceptedvalue: The transaction was accepted. Show confirmation and use server notifications for fulfilment.
Declinedvalue: The payment was declined. Offer another attempt only when canRetry is true.
Cancelledvalue: The flow was cancelled; check canRetry before offering another attempt.
Failedvalue: The attempt could not complete because of an error. Show the error and retry only when canRetry and SDK readiness permit it.
OutcomeUnknownvalue: The SDK cannot establish the outcome of a submitted payment. Show “Awaiting payment confirmation” and resolve status through your backend before offering another payment.

transactionIdStringnullable

Server transaction ID when available; may be absent.

errorSdkErrornullable

Structured error details when available.

Properties · SdkError

Error details supplied through SDK events or a payment attempt.

errorCodeString: Machine-readable error code for identifying the failure.
messageString: Description of the failure for diagnostics. Use getClientMessage() when displaying a localized message to the customer.

canRetryBoolean

Whether this attempt permits another payment. The SDK must also be ready with no active interaction. False after acceptance, exhausted attempts, or an unknown outcome.

maxAttemptsReachedBoolean

The session's decline limit has been reached.

isRedirectingBoolean

A payment redirect is being presented.

pendingSurchargeSurchargenullable

Current surcharge confirmation, if any. Respond through events.confirmSurcharge.

Properties · Surcharge

Fee and revised payment amount presented for customer confirmation. All amounts are in minor units of the session currency.

paymentMethodTypeString: Payment-method type to which the surcharge applies.
paymentMethodSubTypeStringnullable: More specific payment-method type, such as the card scheme, when available.
originalAmountLong: Payment amount before applying the surcharge.
updatedAmountLong: Total payment amount including the surcharge.
feeLong: Surcharge added to the original amount.
minimumFeeLong: Minimum fee configured for the surcharge.
flatFeeLong: Fixed fee component of the surcharge.
percentageDouble: Percentage fee rate, for example 2.5 for 2.5%.

metadataPaymentAttemptMetadata

Additional information about the authorization history of this attempt.

Properties · PaymentAttemptMetadata

Additional authorization history for the payment attempt.

hadDeclinedAuthorizationBoolean: A wallet authorization was definitively declined during this attempt.

onUpdateCallback<PaymentAttempt>nullable

Receives the current attempt immediately, then subsequent updates on the UI thread.

createAnydayTransaction()

Start a Anyday payment using the current transaction options. The SDK presents the provider flow and reports progress through the returned attempt.

Returns PaymentAttempt

Properties · PaymentAttempt

Observable result of starting a payment. Observe onUpdate for progress and outcomes; use server notifications to confirm fulfilment.

idString

Local correlation ID, distinct from the server transaction ID.

statePaymentAttemptState

Current payment progress or outcome. Read canRetry before offering another attempt.

Values · PaymentAttemptState

Current outcome of a payment attempt. Use these states to display progress and decide whether to offer another attempt.

Processingvalue: The payment is in progress or waiting for customer interaction. Show progress and prevent another payment.
Acceptedvalue: The transaction was accepted. Show confirmation and use server notifications for fulfilment.
Declinedvalue: The payment was declined. Offer another attempt only when canRetry is true.
Cancelledvalue: The flow was cancelled; check canRetry before offering another attempt.
Failedvalue: The attempt could not complete because of an error. Show the error and retry only when canRetry and SDK readiness permit it.
OutcomeUnknownvalue: The SDK cannot establish the outcome of a submitted payment. Show “Awaiting payment confirmation” and resolve status through your backend before offering another payment.

transactionIdStringnullable

Server transaction ID when available; may be absent.

errorSdkErrornullable

Structured error details when available.

Properties · SdkError

Error details supplied through SDK events or a payment attempt.

errorCodeString: Machine-readable error code for identifying the failure.
messageString: Description of the failure for diagnostics. Use getClientMessage() when displaying a localized message to the customer.

canRetryBoolean

Whether this attempt permits another payment. The SDK must also be ready with no active interaction. False after acceptance, exhausted attempts, or an unknown outcome.

maxAttemptsReachedBoolean

The session's decline limit has been reached.

isRedirectingBoolean

A payment redirect is being presented.

pendingSurchargeSurchargenullable

Current surcharge confirmation, if any. Respond through events.confirmSurcharge.

Properties · Surcharge

Fee and revised payment amount presented for customer confirmation. All amounts are in minor units of the session currency.

paymentMethodTypeString: Payment-method type to which the surcharge applies.
paymentMethodSubTypeStringnullable: More specific payment-method type, such as the card scheme, when available.
originalAmountLong: Payment amount before applying the surcharge.
updatedAmountLong: Total payment amount including the surcharge.
feeLong: Surcharge added to the original amount.
minimumFeeLong: Minimum fee configured for the surcharge.
flatFeeLong: Fixed fee component of the surcharge.
percentageDouble: Percentage fee rate, for example 2.5 for 2.5%.

metadataPaymentAttemptMetadata

Additional information about the authorization history of this attempt.

Properties · PaymentAttemptMetadata

Additional authorization history for the payment attempt.

hadDeclinedAuthorizationBoolean: A wallet authorization was definitively declined during this attempt.

onUpdateCallback<PaymentAttempt>nullable

Receives the current attempt immediately, then subsequent updates on the UI thread.

createViabillTransaction()

Start a ViaBill payment using the current transaction options. The SDK presents the provider flow and reports progress through the returned attempt.

Returns PaymentAttempt

Properties · PaymentAttempt

Observable result of starting a payment. Observe onUpdate for progress and outcomes; use server notifications to confirm fulfilment.

idString

Local correlation ID, distinct from the server transaction ID.

statePaymentAttemptState

Current payment progress or outcome. Read canRetry before offering another attempt.

Values · PaymentAttemptState

Current outcome of a payment attempt. Use these states to display progress and decide whether to offer another attempt.

Processingvalue: The payment is in progress or waiting for customer interaction. Show progress and prevent another payment.
Acceptedvalue: The transaction was accepted. Show confirmation and use server notifications for fulfilment.
Declinedvalue: The payment was declined. Offer another attempt only when canRetry is true.
Cancelledvalue: The flow was cancelled; check canRetry before offering another attempt.
Failedvalue: The attempt could not complete because of an error. Show the error and retry only when canRetry and SDK readiness permit it.
OutcomeUnknownvalue: The SDK cannot establish the outcome of a submitted payment. Show “Awaiting payment confirmation” and resolve status through your backend before offering another payment.

transactionIdStringnullable

Server transaction ID when available; may be absent.

errorSdkErrornullable

Structured error details when available.

Properties · SdkError

Error details supplied through SDK events or a payment attempt.

errorCodeString: Machine-readable error code for identifying the failure.
messageString: Description of the failure for diagnostics. Use getClientMessage() when displaying a localized message to the customer.

canRetryBoolean

Whether this attempt permits another payment. The SDK must also be ready with no active interaction. False after acceptance, exhausted attempts, or an unknown outcome.

maxAttemptsReachedBoolean

The session's decline limit has been reached.

isRedirectingBoolean

A payment redirect is being presented.

pendingSurchargeSurchargenullable

Current surcharge confirmation, if any. Respond through events.confirmSurcharge.

Properties · Surcharge

Fee and revised payment amount presented for customer confirmation. All amounts are in minor units of the session currency.

paymentMethodTypeString: Payment-method type to which the surcharge applies.
paymentMethodSubTypeStringnullable: More specific payment-method type, such as the card scheme, when available.
originalAmountLong: Payment amount before applying the surcharge.
updatedAmountLong: Total payment amount including the surcharge.
feeLong: Surcharge added to the original amount.
minimumFeeLong: Minimum fee configured for the surcharge.
flatFeeLong: Fixed fee component of the surcharge.
percentageDouble: Percentage fee rate, for example 2.5 for 2.5%.

metadataPaymentAttemptMetadata

Additional information about the authorization history of this attempt.

Properties · PaymentAttemptMetadata

Additional authorization history for the payment attempt.

hadDeclinedAuthorizationBoolean: A wallet authorization was definitively declined during this attempt.

onUpdateCallback<PaymentAttempt>nullable

Receives the current attempt immediately, then subsequent updates on the UI thread.

createKlarnaTransaction()

Start a Klarna payment using the current transaction options. The SDK presents the provider flow and reports progress through the returned attempt.

Returns PaymentAttempt

Properties · PaymentAttempt

Observable result of starting a payment. Observe onUpdate for progress and outcomes; use server notifications to confirm fulfilment.

idString

Local correlation ID, distinct from the server transaction ID.

statePaymentAttemptState

Current payment progress or outcome. Read canRetry before offering another attempt.

Values · PaymentAttemptState

Current outcome of a payment attempt. Use these states to display progress and decide whether to offer another attempt.

Processingvalue: The payment is in progress or waiting for customer interaction. Show progress and prevent another payment.
Acceptedvalue: The transaction was accepted. Show confirmation and use server notifications for fulfilment.
Declinedvalue: The payment was declined. Offer another attempt only when canRetry is true.
Cancelledvalue: The flow was cancelled; check canRetry before offering another attempt.
Failedvalue: The attempt could not complete because of an error. Show the error and retry only when canRetry and SDK readiness permit it.
OutcomeUnknownvalue: The SDK cannot establish the outcome of a submitted payment. Show “Awaiting payment confirmation” and resolve status through your backend before offering another payment.

transactionIdStringnullable

Server transaction ID when available; may be absent.

errorSdkErrornullable

Structured error details when available.

Properties · SdkError

Error details supplied through SDK events or a payment attempt.

errorCodeString: Machine-readable error code for identifying the failure.
messageString: Description of the failure for diagnostics. Use getClientMessage() when displaying a localized message to the customer.

canRetryBoolean

Whether this attempt permits another payment. The SDK must also be ready with no active interaction. False after acceptance, exhausted attempts, or an unknown outcome.

maxAttemptsReachedBoolean

The session's decline limit has been reached.

isRedirectingBoolean

A payment redirect is being presented.

pendingSurchargeSurchargenullable

Current surcharge confirmation, if any. Respond through events.confirmSurcharge.

Properties · Surcharge

Fee and revised payment amount presented for customer confirmation. All amounts are in minor units of the session currency.

paymentMethodTypeString: Payment-method type to which the surcharge applies.
paymentMethodSubTypeStringnullable: More specific payment-method type, such as the card scheme, when available.
originalAmountLong: Payment amount before applying the surcharge.
updatedAmountLong: Total payment amount including the surcharge.
feeLong: Surcharge added to the original amount.
minimumFeeLong: Minimum fee configured for the surcharge.
flatFeeLong: Fixed fee component of the surcharge.
percentageDouble: Percentage fee rate, for example 2.5 for 2.5%.

metadataPaymentAttemptMetadata

Additional information about the authorization history of this attempt.

Properties · PaymentAttemptMetadata

Additional authorization history for the payment attempt.

hadDeclinedAuthorizationBoolean: A wallet authorization was definitively declined during this attempt.

onUpdateCallback<PaymentAttempt>nullable

Receives the current attempt immediately, then subsequent updates on the UI thread.

createPayPalTransaction()

Start a PayPal payment using the platform payment host. Complete the PayPal platform setup before offering this method.

Returns PaymentAttempt

Properties · PaymentAttempt

Observable result of starting a payment. Observe onUpdate for progress and outcomes; use server notifications to confirm fulfilment.

idString

Local correlation ID, distinct from the server transaction ID.

statePaymentAttemptState

Current payment progress or outcome. Read canRetry before offering another attempt.

Values · PaymentAttemptState

Current outcome of a payment attempt. Use these states to display progress and decide whether to offer another attempt.

Processingvalue: The payment is in progress or waiting for customer interaction. Show progress and prevent another payment.
Acceptedvalue: The transaction was accepted. Show confirmation and use server notifications for fulfilment.
Declinedvalue: The payment was declined. Offer another attempt only when canRetry is true.
Cancelledvalue: The flow was cancelled; check canRetry before offering another attempt.
Failedvalue: The attempt could not complete because of an error. Show the error and retry only when canRetry and SDK readiness permit it.
OutcomeUnknownvalue: The SDK cannot establish the outcome of a submitted payment. Show “Awaiting payment confirmation” and resolve status through your backend before offering another payment.

transactionIdStringnullable

Server transaction ID when available; may be absent.

errorSdkErrornullable

Structured error details when available.

Properties · SdkError

Error details supplied through SDK events or a payment attempt.

errorCodeString: Machine-readable error code for identifying the failure.
messageString: Description of the failure for diagnostics. Use getClientMessage() when displaying a localized message to the customer.

canRetryBoolean

Whether this attempt permits another payment. The SDK must also be ready with no active interaction. False after acceptance, exhausted attempts, or an unknown outcome.

maxAttemptsReachedBoolean

The session's decline limit has been reached.

isRedirectingBoolean

A payment redirect is being presented.

pendingSurchargeSurchargenullable

Current surcharge confirmation, if any. Respond through events.confirmSurcharge.

Properties · Surcharge

Fee and revised payment amount presented for customer confirmation. All amounts are in minor units of the session currency.

paymentMethodTypeString: Payment-method type to which the surcharge applies.
paymentMethodSubTypeStringnullable: More specific payment-method type, such as the card scheme, when available.
originalAmountLong: Payment amount before applying the surcharge.
updatedAmountLong: Total payment amount including the surcharge.
feeLong: Surcharge added to the original amount.
minimumFeeLong: Minimum fee configured for the surcharge.
flatFeeLong: Fixed fee component of the surcharge.
percentageDouble: Percentage fee rate, for example 2.5 for 2.5%.

metadataPaymentAttemptMetadata

Additional information about the authorization history of this attempt.

Properties · PaymentAttemptMetadata

Additional authorization history for the payment attempt.

hadDeclinedAuthorizationBoolean: A wallet authorization was definitively declined during this attempt.

onUpdateCallback<PaymentAttempt>nullable

Receives the current attempt immediately, then subsequent updates on the UI thread.

createGooglePayTransaction()

Start a Google Pay payment on Android. Check availability for the current session and device before offering the button.

Returns PaymentAttempt

Properties · PaymentAttempt

Observable result of starting a payment. Observe onUpdate for progress and outcomes; use server notifications to confirm fulfilment.

idString

Local correlation ID, distinct from the server transaction ID.

statePaymentAttemptState

Current payment progress or outcome. Read canRetry before offering another attempt.

Values · PaymentAttemptState

Current outcome of a payment attempt. Use these states to display progress and decide whether to offer another attempt.

Processingvalue: The payment is in progress or waiting for customer interaction. Show progress and prevent another payment.
Acceptedvalue: The transaction was accepted. Show confirmation and use server notifications for fulfilment.
Declinedvalue: The payment was declined. Offer another attempt only when canRetry is true.
Cancelledvalue: The flow was cancelled; check canRetry before offering another attempt.
Failedvalue: The attempt could not complete because of an error. Show the error and retry only when canRetry and SDK readiness permit it.
OutcomeUnknownvalue: The SDK cannot establish the outcome of a submitted payment. Show “Awaiting payment confirmation” and resolve status through your backend before offering another payment.

transactionIdStringnullable

Server transaction ID when available; may be absent.

errorSdkErrornullable

Structured error details when available.

Properties · SdkError

Error details supplied through SDK events or a payment attempt.

errorCodeString: Machine-readable error code for identifying the failure.
messageString: Description of the failure for diagnostics. Use getClientMessage() when displaying a localized message to the customer.

canRetryBoolean

Whether this attempt permits another payment. The SDK must also be ready with no active interaction. False after acceptance, exhausted attempts, or an unknown outcome.

maxAttemptsReachedBoolean

The session's decline limit has been reached.

isRedirectingBoolean

A payment redirect is being presented.

pendingSurchargeSurchargenullable

Current surcharge confirmation, if any. Respond through events.confirmSurcharge.

Properties · Surcharge

Fee and revised payment amount presented for customer confirmation. All amounts are in minor units of the session currency.

paymentMethodTypeString: Payment-method type to which the surcharge applies.
paymentMethodSubTypeStringnullable: More specific payment-method type, such as the card scheme, when available.
originalAmountLong: Payment amount before applying the surcharge.
updatedAmountLong: Total payment amount including the surcharge.
feeLong: Surcharge added to the original amount.
minimumFeeLong: Minimum fee configured for the surcharge.
flatFeeLong: Fixed fee component of the surcharge.
percentageDouble: Percentage fee rate, for example 2.5 for 2.5%.

metadataPaymentAttemptMetadata

Additional information about the authorization history of this attempt.

Properties · PaymentAttemptMetadata

Additional authorization history for the payment attempt.

hadDeclinedAuthorizationBoolean: A wallet authorization was definitively declined during this attempt.

onUpdateCallback<PaymentAttempt>nullable

Receives the current attempt immediately, then subsequent updates on the UI thread.

createApplePayTransaction(data)

Start an Apple Pay payment on iOS. Check availability first and use a merchant identifier matching the app’s entitlement.

Parameters

dataApplePayPaymentDatarequired

Apple merchant identifier for this payment.

Properties · ApplePayPaymentData

Apple Pay merchant configuration for starting a payment.

merchantIdentifierString: Apple merchant identifier matching the app’s Apple Pay entitlement, for example merchant.com.example.shop.

Returns PaymentAttempt

Properties · PaymentAttempt

Observable result of starting a payment. Observe onUpdate for progress and outcomes; use server notifications to confirm fulfilment.

idString

Local correlation ID, distinct from the server transaction ID.

statePaymentAttemptState

Current payment progress or outcome. Read canRetry before offering another attempt.

Values · PaymentAttemptState

Current outcome of a payment attempt. Use these states to display progress and decide whether to offer another attempt.

Processingvalue: The payment is in progress or waiting for customer interaction. Show progress and prevent another payment.
Acceptedvalue: The transaction was accepted. Show confirmation and use server notifications for fulfilment.
Declinedvalue: The payment was declined. Offer another attempt only when canRetry is true.
Cancelledvalue: The flow was cancelled; check canRetry before offering another attempt.
Failedvalue: The attempt could not complete because of an error. Show the error and retry only when canRetry and SDK readiness permit it.
OutcomeUnknownvalue: The SDK cannot establish the outcome of a submitted payment. Show “Awaiting payment confirmation” and resolve status through your backend before offering another payment.

transactionIdStringnullable

Server transaction ID when available; may be absent.

errorSdkErrornullable

Structured error details when available.

Properties · SdkError

Error details supplied through SDK events or a payment attempt.

errorCodeString: Machine-readable error code for identifying the failure.
messageString: Description of the failure for diagnostics. Use getClientMessage() when displaying a localized message to the customer.

canRetryBoolean

Whether this attempt permits another payment. The SDK must also be ready with no active interaction. False after acceptance, exhausted attempts, or an unknown outcome.

maxAttemptsReachedBoolean

The session's decline limit has been reached.

isRedirectingBoolean

A payment redirect is being presented.

pendingSurchargeSurchargenullable

Current surcharge confirmation, if any. Respond through events.confirmSurcharge.

Properties · Surcharge

Fee and revised payment amount presented for customer confirmation. All amounts are in minor units of the session currency.

paymentMethodTypeString: Payment-method type to which the surcharge applies.
paymentMethodSubTypeStringnullable: More specific payment-method type, such as the card scheme, when available.
originalAmountLong: Payment amount before applying the surcharge.
updatedAmountLong: Total payment amount including the surcharge.
feeLong: Surcharge added to the original amount.
minimumFeeLong: Minimum fee configured for the surcharge.
flatFeeLong: Fixed fee component of the surcharge.
percentageDouble: Percentage fee rate, for example 2.5 for 2.5%.

metadataPaymentAttemptMetadata

Additional information about the authorization history of this attempt.

Properties · PaymentAttemptMetadata

Additional authorization history for the payment attempt.

hadDeclinedAuthorizationBoolean: A wallet authorization was definitively declined during this attempt.

onUpdateCallback<PaymentAttempt>nullable

Receives the current attempt immediately, then subsequent updates on the UI thread.

createStoredPaymentMethodTransaction(data)

Start a payment with a saved method belonging to the session’s customer.

Parameters

dataStoredPaymentMethodDatarequired

Stored payment method to use for this payment.

Properties · StoredPaymentMethodData

Identifies a stored payment method belonging to the session’s customer.

paymentMethodIdString: ID of the stored payment method returned by getStoredPaymentMethods().

Returns PaymentAttempt

Properties · PaymentAttempt

Observable result of starting a payment. Observe onUpdate for progress and outcomes; use server notifications to confirm fulfilment.

idString

Local correlation ID, distinct from the server transaction ID.

statePaymentAttemptState

Current payment progress or outcome. Read canRetry before offering another attempt.

Values · PaymentAttemptState

Current outcome of a payment attempt. Use these states to display progress and decide whether to offer another attempt.

Processingvalue: The payment is in progress or waiting for customer interaction. Show progress and prevent another payment.
Acceptedvalue: The transaction was accepted. Show confirmation and use server notifications for fulfilment.
Declinedvalue: The payment was declined. Offer another attempt only when canRetry is true.
Cancelledvalue: The flow was cancelled; check canRetry before offering another attempt.
Failedvalue: The attempt could not complete because of an error. Show the error and retry only when canRetry and SDK readiness permit it.
OutcomeUnknownvalue: The SDK cannot establish the outcome of a submitted payment. Show “Awaiting payment confirmation” and resolve status through your backend before offering another payment.

transactionIdStringnullable

Server transaction ID when available; may be absent.

errorSdkErrornullable

Structured error details when available.

Properties · SdkError

Error details supplied through SDK events or a payment attempt.

errorCodeString: Machine-readable error code for identifying the failure.
messageString: Description of the failure for diagnostics. Use getClientMessage() when displaying a localized message to the customer.

canRetryBoolean

Whether this attempt permits another payment. The SDK must also be ready with no active interaction. False after acceptance, exhausted attempts, or an unknown outcome.

maxAttemptsReachedBoolean

The session's decline limit has been reached.

isRedirectingBoolean

A payment redirect is being presented.

pendingSurchargeSurchargenullable

Current surcharge confirmation, if any. Respond through events.confirmSurcharge.

Properties · Surcharge

Fee and revised payment amount presented for customer confirmation. All amounts are in minor units of the session currency.

paymentMethodTypeString: Payment-method type to which the surcharge applies.
paymentMethodSubTypeStringnullable: More specific payment-method type, such as the card scheme, when available.
originalAmountLong: Payment amount before applying the surcharge.
updatedAmountLong: Total payment amount including the surcharge.
feeLong: Surcharge added to the original amount.
minimumFeeLong: Minimum fee configured for the surcharge.
flatFeeLong: Fixed fee component of the surcharge.
percentageDouble: Percentage fee rate, for example 2.5 for 2.5%.

metadataPaymentAttemptMetadata

Additional information about the authorization history of this attempt.

Properties · PaymentAttemptMetadata

Additional authorization history for the payment attempt.

hadDeclinedAuthorizationBoolean: A wallet authorization was definitively declined during this attempt.

onUpdateCallback<PaymentAttempt>nullable

Receives the current attempt immediately, then subsequent updates on the UI thread.

paymentAttemptPaymentAttemptnullable

Latest admitted payment attempt; rejected concurrent starts do not replace it.

Properties · PaymentAttempt

Observable result of starting a payment. Observe onUpdate for progress and outcomes; use server notifications to confirm fulfilment.

idString

Local correlation ID, distinct from the server transaction ID.

statePaymentAttemptState

Current payment progress or outcome. Read canRetry before offering another attempt.

Values · PaymentAttemptState

Current outcome of a payment attempt. Use these states to display progress and decide whether to offer another attempt.

Processingvalue: The payment is in progress or waiting for customer interaction. Show progress and prevent another payment.
Acceptedvalue: The transaction was accepted. Show confirmation and use server notifications for fulfilment.
Declinedvalue: The payment was declined. Offer another attempt only when canRetry is true.
Cancelledvalue: The flow was cancelled; check canRetry before offering another attempt.
Failedvalue: The attempt could not complete because of an error. Show the error and retry only when canRetry and SDK readiness permit it.
OutcomeUnknownvalue: The SDK cannot establish the outcome of a submitted payment. Show “Awaiting payment confirmation” and resolve status through your backend before offering another payment.

transactionIdStringnullable

Server transaction ID when available; may be absent.

errorSdkErrornullable

Structured error details when available.

Properties · SdkError

Error details supplied through SDK events or a payment attempt.

errorCodeString: Machine-readable error code for identifying the failure.
messageString: Description of the failure for diagnostics. Use getClientMessage() when displaying a localized message to the customer.

canRetryBoolean

Whether this attempt permits another payment. The SDK must also be ready with no active interaction. False after acceptance, exhausted attempts, or an unknown outcome.

maxAttemptsReachedBoolean

The session's decline limit has been reached.

isRedirectingBoolean

A payment redirect is being presented.

pendingSurchargeSurchargenullable

Current surcharge confirmation, if any. Respond through events.confirmSurcharge.

Properties · Surcharge

Fee and revised payment amount presented for customer confirmation. All amounts are in minor units of the session currency.

paymentMethodTypeString: Payment-method type to which the surcharge applies.
paymentMethodSubTypeStringnullable: More specific payment-method type, such as the card scheme, when available.
originalAmountLong: Payment amount before applying the surcharge.
updatedAmountLong: Total payment amount including the surcharge.
feeLong: Surcharge added to the original amount.
minimumFeeLong: Minimum fee configured for the surcharge.
flatFeeLong: Fixed fee component of the surcharge.
percentageDouble: Percentage fee rate, for example 2.5 for 2.5%.

metadataPaymentAttemptMetadata

Additional information about the authorization history of this attempt.

Properties · PaymentAttemptMetadata

Additional authorization history for the payment attempt.

hadDeclinedAuthorizationBoolean: A wallet authorization was definitively declined during this attempt.

onUpdateCallback<PaymentAttempt>nullable

Receives the current attempt immediately, then subsequent updates on the UI thread.

dispose()

Cancel pending SDK work and release screen resources and callbacks. This does not cancel a submitted payment. Safe to repeat; create a new instance and host for another checkout.

Returns Unit / Void

Ready means SDK actions are available. A later failure, including session expiry, can move the SDK to Failed. A query error alone does not imply lifecycle failure.

You may initialize an undisposed SDK again to replace a session. This cancels pending queries and invalidates session-bound fields and verification objects. It does not cancel an already submitted payment. Never replace a session to retry an uncertain payment; resolve the order status through your backend first.

Installation and requirementsCopy Anchor Link

Initialize a checkoutCopy Anchor Link

Lifecycle referenceCopy Anchor Link

On this page

Installation and requirements

Initialize a checkout

Lifecycle reference