SDK Schema

The SDK contract for Android and iOS. Expand a type to inspect its nested properties. For a working integration, start with the Native SDK guide.

Download the schema definition. Types use Kotlin names; the guides show Swift usage and platform differences.

SDK and lifecycle

Epay

Epay reference

Entry point for app checkout. Create an instance for the checkout screen, initialize it with a payment session, and dispose it when the screen is released.

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

sessionData()

Return the session snapshot loaded during initialization. Requires the SDK to be ready.

Returns SessionData

Properties · SessionData

Payment session and checkout configuration loaded during SDK initialization. This is a snapshot; use payment attempts to observe payment progress.

sessionSessionInfo

Payment details and restrictions set when your server created the session.

Properties · SessionInfo

Details of the payment session created by your server. Amounts use the session currency.

idString

Unique ID of the payment session.

pointOfSaleIdString

ID of the point of sale associated with the session.

timeoutInt

Session lifetime in minutes, as configured when the session was created.

instantCaptureString

Instant-capture mode configured for the session: OFF, VOID, or NO_VOID.

referenceStringnullable

Your transaction reference, typically an order ID. Null when none was supplied.

hasSubscriptionBoolean

Whether the session is associated with a subscription.

amountLong

Transaction amount in minor units, for example 1095 for 10.95 DKK.

currencyString

Three-letter ISO 4217 currency code, for example DKK.

textOnStatementStringnullable

Text requested for the cardholder’s bank statement. Null when no custom text was supplied.

descriptorStringnullable

Merchant descriptor supplied for this session. Overrides the point-of-sale descriptor unless an acquirer agreement supplies an override.

stateString

Session state at initialization, such as PENDING, PROCESSING, COMPLETED, or EXPIRED. This property does not track subsequent payment progress.

dynamicAmountBoolean

Whether the app may override the session amount through TransactionOptions.amount.

minimumAgeInt

Minimum required customer age in years. Zero means no age requirement was configured.

ageVerifiedBoolean

Whether the customer had been verified as meeting the minimum age when this snapshot was loaded.

createdAtSessionTimestamp

Time the payment session was created. Uses kotlin.time.Instant on Android and Foundation Date in Swift.

expiresAtSessionTimestamp

Time after which the session can no longer be used. Create a new session to continue checkout after expiry.

customerInfoSessionCustomerInfonullable

Customer contact and address details supplied for the session, or null when none were supplied.

Properties · SessionCustomerInfo

Customer details supplied by your server for authentication and payment-provider requirements.

firstNameStringnullable

Customer’s given name.

lastNameStringnullable

Customer’s family name.

emailStringnullable

Customer’s email address.

phoneNumberStringnullable

Customer’s phone number in E.164 format with a space after the country calling code, for example +45 12345678.

shippingAddressSessionCustomerAddressnullable

Address to which purchased goods will be delivered.

Properties · SessionCustomerAddress

Postal address supplied for billing or shipping. Unspecified address fields are null.

countryCodeStringnullable: Two-letter ISO 3166-1 alpha-2 country code, for example DK.
postalCodeStringnullable: Postal or ZIP code.
cityStringnullable: City or locality.
line1Stringnullable: First address line, usually the street name and building number.
line2Stringnullable: Additional address details, such as an apartment or suite.
line3Stringnullable: Further address details when two lines are insufficient.

billingAddressSessionCustomerAddressnullable

Customer’s personal or business billing address.

Properties · SessionCustomerAddress

Postal address supplied for billing or shipping. Unspecified address fields are null.

countryCodeStringnullable: Two-letter ISO 3166-1 alpha-2 country code, for example DK.
postalCodeStringnullable: Postal or ZIP code.
cityStringnullable: City or locality.
line1Stringnullable: First address line, usually the street name and building number.
line2Stringnullable: Additional address details, such as an apartment or suite.
line3Stringnullable: Further address details when two lines are insufficient.

allowedPaymentMethodsList<String>nullable

Payment-method restrictions supplied for the session. Null means no session-specific list was supplied; use getSupportedPaymentMethodTypes() for available methods.

pointOfSaleSessionPointOfSale

Point-of-sale settings associated with this session.

Properties · SessionPointOfSale

Point-of-sale settings used by the payment session.

descriptorString: Default merchant descriptor for the point of sale.
domainsList<String>nullable: Domains configured for the point of sale, or null when none are supplied.

countryCodeString

Merchant account country as an ISO 3166-1 alpha-2 code, for example DK.

supportedSchemesList<String>nullable

Card schemes supported for this session, for example VISA and MASTERCARD. Null when no list is supplied.

canStorePaymentMethodBoolean

Whether the session has a customer ID and can store a payment method for that customer. Use this to decide whether to offer a save-payment-method option.

subscriptionSessionSubscriptionnullable

Subscription configuration associated with the session, or null when there is no subscription.

Properties · SessionSubscription

Recurring-payment agreement configured for this session.

typeString

Agreement type: SCHEDULED for payments at a fixed interval or UNSCHEDULED for payments as needed.

intervalSessionSubscriptionIntervalnullable

Billing interval for a scheduled subscription. Null when no interval was supplied.

Properties · SessionSubscriptionInterval

Frequency of scheduled subscription payments.

periodString: Billing unit: DAY, WEEK, MONTH, or YEAR.
frequencyInt: Number of billing units between payments, from 1 to 31. For example, 3 with MONTH means every three months.

expiryDateSessionDatenullable

Agreement expiry date supplied for authentication. ePay does not reject later payments solely because this date has passed.

Properties · SessionDate

Calendar date without a time or time zone.

yearInt: Four-digit calendar year, for example 2030.
monthInt: Month of the year, from 1 to 12.
dayInt: Day of the month, from 1 to 31 as permitted by the month.

amountLongnullable

Recurring amount in minor units. When null, the transaction amount is used.

Throws EpayException. See error handling.

getSupportedPaymentMethodTypes()

List payment methods available for the initialized session. Check Apple Pay or Google Pay device availability separately before displaying those wallet buttons.

Kotlin suspend · Swift async throws

Returns List<SupportedPaymentMethod>

Properties · SupportedPaymentMethod

Payment method enabled for the current session. Device wallet availability requires a separate availability check.

typeString: Payment-method identifier used to choose the corresponding payment method, for example CARD or APPLE_PAY.
nameString: Display name of the payment method.
urlString: URL of the payment-method image for your checkout UI.

Throws EpayException. See error handling.

getStoredPaymentMethods()

List payment methods saved for the session’s customer. Returns an empty list when none are available.

Kotlin suspend · Swift async throws

Returns List<StoredPaymentMethod>

Properties · StoredPaymentMethod

Saved payment method available to the session’s customer.

idString: Unique ID used to pay with, delete, or calculate a fee for this stored method.
displayTextString: Shopper-friendly identification, such as a masked card number.
typeString: Payment-method type, for example CARD.
subTypeStringnullable: More specific payment-method type, such as the card scheme. Null when not supplied.
customerIdStringnullable: Your customer ID associated with the stored payment method.
expiryStringnullable: Expiry date in YYYY-MM-DD format. For a card, this is the last day of its expiration month.
createdAtString: Timestamp when the payment method was stored.
accountUpdatesEnabledBoolean: Whether the payment method is enrolled in account updates to keep stored card details current when a replacement is issued.
feeLong: Calculated fee for the session amount, in minor units of the session currency.

Throws EpayException. See error handling.

deleteStoredPaymentMethod(data)

Delete a saved payment method belonging to the session’s customer. Completes when deletion succeeds.

Kotlin suspend · Swift async throws

Parameters

dataStoredPaymentMethodDatarequired

Stored payment method to delete.

Properties · StoredPaymentMethodData

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

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

Returns Unit / Void

Throws EpayException. See error handling.

calculateStoredPaymentMethodFee(data)

Calculate the fee for a saved payment method and base amount. This query does not change the payment amount or emit a fee-update event.

Kotlin suspend · Swift async throws

Parameters

dataStoredPaymentMethodFeeDatarequired

Stored payment method and optional base amount for the fee calculation.

Properties · StoredPaymentMethodFeeData

Stored payment method and base amount for a fee calculation.

paymentMethodIdString: ID of the stored payment method whose fee should be calculated.
amountLongoptionalnullable: Base amount in minor units of the session currency. Uses the session amount when omitted or null.

Returns StoredPaymentMethodFee

Properties · StoredPaymentMethodFee

Result of calculating a stored payment method’s fee.

feeLong: Fee in minor units of the session currency for the requested base amount. Zero means no fee.

Throws EpayException. See error handling.

getClientMessage(data)

Get a localized shopper-facing message for an ePay code. Omit the input to use the latest code and language retained by the SDK.

Kotlin suspend · Swift async throws

Parameters

dataClientMessageDataoptional

Optional result code and language to use instead of the SDK’s retained values.

Properties · ClientMessageData

Optional code and language overrides when requesting a shopper-facing message.

ePayCodeStringoptionalnullable: ePay result or error code to translate. When omitted, uses the latest code retained by the SDK.
langStringoptionalnullable: Language code, for example da or en. When omitted, uses the language retained from field configuration or a previous language selection.

Returns ClientMessage

Properties · ClientMessage

Localized message associated with an ePay result or error code.

textString: Shopper-facing message. May be empty when no message is available and may contain newlines and **bold** markers.

Throws EpayException. See error handling.

ageVerification()

Get the age-verification flow for the initialized session. Requires the SDK to be ready.

Returns AgeVerification

Properties · AgeVerification

Age-verification flow for the initialized session. Reinitializing the SDK invalidates this object.

minimumAgeInt

Required age in years. Zero means the session has no configured age requirement.

statusAgeVerificationStatus

Latest known verification status for this session.

Values · AgeVerificationStatus

Known age-verification status for the session.

NotRequestedvalue: No minimum age was configured for the session and verification has not been requested.
NotVerifiedvalue: The customer has not been verified as meeting the required age.
Verifiedvalue: The customer has been verified as meeting the required age.

start()

Start age verification and wait for its result, even if a previous check was verified. The SDK must be ready and no payment or other verification flow may be active.

Kotlin suspend · Swift async throws

Returns AgeVerificationResult

Properties · AgeVerificationResult

Outcome returned when an age-verification flow finishes.

statusAgeVerificationStatus

Verified when the customer meets the required age; otherwise NotVerified.

Values · AgeVerificationStatus

Known age-verification status for the session.

NotRequestedvalue: No minimum age was configured for the session and verification has not been requested.
NotVerifiedvalue: The customer has not been verified as meeting the required age.
Verifiedvalue: The customer has been verified as meeting the required age.

Throws EpayException. See error handling.

Epay(host)

Create an SDK instance for the owning checkout screen.

Parameters

hostAndroidPaymentHost / IosPaymentHostrequired: Platform host responsible for presenting payment and authentication flows from the checkout screen.

Returns Epay

Epay reference

mountFields(host, config)

Mount card fields in the supplied platform view after SDK initialization. Observe field status before enabling payment.

Parameters

hostAndroidHostedFields / IosHostedFieldsrequired

Platform card-field view added to your checkout layout.

configHostedFieldsConfigrequired

Appearance, initial height, and callbacks for the card fields.

Properties · HostedFieldsConfig

Appearance, initial layout, and callbacks supplied when mounting card fields.

appearanceFieldsAppearanceoptional

Language and visual configuration for the fields. Uses the mobile theme by default.

Properties · FieldsAppearance

Language, theme, and appearance of the card fields. Unspecified styling values use the selected theme.

languageStringoptionalnullable

Language code for field labels and messages, for example da or en.

themeStringoptionalnullabledefault: "mobile"

Base appearance theme. Defaults to mobile, which is designed for app checkout.

variablesFieldsVariablesoptionalnullable

Individual colors, spacing, and typography settings that override the theme.

Properties · FieldsVariables

Card-field style overrides expressed as CSS value strings, such as #222222, 16px, or 0. Omit a value to keep the theme setting.

colorTextStringoptionalnullable: Default text color for labels and input content.
borderRadiusStringoptionalnullable: Default corner radius for inputs and the field container.
borderColorStringoptionalnullable: Default border color for inputs and the field container.
fontFamilyStringoptionalnullable: Font family used for labels, entered values, and placeholders.
gridColumnSpacingStringoptionalnullable: Horizontal space between fields, for example 12px.
gridRowSpacingStringoptionalnullable: Vertical space between fields, for example 16px.
gridTemplateColumnsStringoptionalnullable: Column sizes for the field grid, for example 1fr 1fr for two equal columns.
iconDisplayStringoptionalnullable: Display behavior for field icons, for example block or none.
cardBrandDisplayStringoptionalnullable: Display behavior for card-brand icons, for example block or none.
supportedSchemesDisplayStringoptionalnullable: Display behavior for supported card-scheme icons, for example flex or none.
labelColorStringoptionalnullable: Text color of field labels.
labelFontSizeStringoptionalnullable: Font size of field labels, for example 14px.
labelFontWeightStringoptionalnullable: Font weight of field labels, for example 400 or 600.
labelMarginBottomStringoptionalnullable: Space between a label and its input.
inputColorStringoptionalnullable: Text color of entered values.
inputBorderRadiusStringoptionalnullable: Corner radius of input fields.
inputBorderColorStringoptionalnullable: Border color of input fields.
inputFontSizeStringoptionalnullable: Font size of entered values.
inputPaddingStringoptionalnullable: Space inside each input border, for example 12px.
inputPlaceholderColorStringoptionalnullable: Text color of input placeholders.
inputBackgroundColorStringoptionalnullable: Background color of input fields.
inputBoxShadowStringoptionalnullable: Shadow around input fields, or none to remove it.
inputFocusBorderColorStringoptionalnullable: Input border color while the field has focus.
inputFocusBoxShadowStringoptionalnullable: Input shadow while the field has focus.
windowPaddingStringoptionalnullable: Space around the fields inside their container.
windowBackgroundColorStringoptionalnullable: Background color of the field container.
windowBorderStyleStringoptionalnullable: Border style of the field container, for example solid or none.
windowBorderRadiusStringoptionalnullable: Corner radius of the field container.
windowBorderColorStringoptionalnullable: Border color of the field container.
colorDangerStringoptionalnullable: Color used for validation errors and other field problems.
colorPrimaryStringoptionalnullable: Primary accent color of the card fields.

fieldsFieldsConfigurationoptionalnullable

Visibility and initial behavior of the cardholder-name and card-number fields.

Properties · FieldsConfiguration

Options for individual card fields.

nameFieldsNameoptionalnullable

Cardholder-name field settings.

Properties · FieldsName

Visibility and initial value of the optional cardholder-name field.

enabledBooleanoptionalnullable: Show the cardholder-name field when true. It is hidden by default.
valueStringoptionalnullable: Initial cardholder name to prefill when the name field is enabled.

panFieldsPanoptionalnullable

Card-number field settings.

Properties · FieldsPan

Card-number field behavior and card-brand controls.

focusBooleanoptionalnullable: Focus the card-number field when it mounts. Defaults to true.
showSupportedSchemesBooleanoptionalnullable: Show the supported card-scheme icons. Defaults to true.
showBrandSelectorBooleanoptionalnullable: Show the brand selector for cards supporting multiple brands. Defaults to true.

fontSelectionFieldsFontoptionalnullable

Font source and family selection. Supply source, family, category, and stack together.

Properties · FieldsFont

Font selection for the card fields. Provide all four values together.

sourceStringoptionalnullable: Font source: system for an available system font or google for a Google Font.
familyStringoptionalnullable: Name of the selected font family, for example Roboto.
categoryStringoptionalnullable: Generic font category, for example sans-serif.
stackStringoptionalnullable: Ordered font-family list including fallbacks, for example Roboto, sans-serif.

loaderFieldsLoaderoptionalnullable

Appearance of the loading placeholder shown while fields initialize.

Properties · FieldsLoader

Style of the placeholder displayed while card fields load.

heightStringoptionalnullable: Placeholder height as a CSS length, for example 150px.
backgroundColorStringoptionalnullable: Placeholder background color, for example transparent.
borderStyleStringoptionalnullable: Placeholder border style, for example solid or none.

initialHeightDoubleoptionaldefault: 190.0

Space reserved before the fields report their height, in Android density-independent pixels or iOS points. Must be finite and greater than zero.

onReadinessChangedCallback<SdkState>optionalnullable

Called when the fields change between loading, ready, and failed states.

onUpdateCallback<HostedFieldsStatus>optionalnullable

Receives the current combined field status and subsequent updates. Use its payment-button recommendation to update your checkout button.

Properties · HostedFieldsStatus

Combined snapshot of field readiness, validity, and recommended payment-button state.

stateSdkState

Readiness of the mounted card fields.

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.

paymentButtonStatePaymentButtonState

Recommended visibility and enabled state of the payment button. Active means ready to pay; processing a payment makes the button disabled.

Values · PaymentButtonState

Recommended visibility and enabled state of your card-payment button. The recommendation accounts for field readiness and whether another payment can start.

Hidden / Swift .hiddenvalue: Hide the pay button (or deliberately show it disabled).
Disabled / Swift .disabledvalue: Show it disabled while inputs are invalid, payment is processing, or another payment cannot start.
Active / Swift .activevalue: Enable the payment action. The fields are ready and valid, and the SDK can start a payment.

isValidBoolean

Whether the entered card details pass field validation. This does not guarantee that the payment will be authorized.

onSubmitCallbackoptionalnullable

Called when the customer submits the ready fields, for example using the keyboard. Start a card payment from this callback when the payment button is active.

Returns HostedFields

Properties · HostedFields

Mounted card-entry component returned by mountFields(). Control methods require the fields to be ready.

stateSdkState

Current field readiness, independent of the SDK’s session readiness.

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.

isValidBoolean

Whether the entered card details pass field validation. Use status.paymentButtonState to decide when payment is available.

statusHostedFieldsStatus

Latest combined readiness, validity, and payment-button recommendation.

Properties · HostedFieldsStatus

Combined snapshot of field readiness, validity, and recommended payment-button state.

stateSdkState

Readiness of the mounted card fields.

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.

paymentButtonStatePaymentButtonState

Recommended visibility and enabled state of the payment button. Active means ready to pay; processing a payment makes the button disabled.

Values · PaymentButtonState

Recommended visibility and enabled state of your card-payment button. The recommendation accounts for field readiness and whether another payment can start.

Hidden / Swift .hiddenvalue: Hide the pay button (or deliberately show it disabled).
Disabled / Swift .disabledvalue: Show it disabled while inputs are invalid, payment is processing, or another payment cannot start.
Active / Swift .activevalue: Enable the payment action. The fields are ready and valid, and the SDK can start a payment.

isValidBoolean

Whether the entered card details pass field validation. This does not guarantee that the payment will be authorized.

onReadinessChangedCallback<SdkState>nullable

Called on the UI thread when field readiness changes.

onValidityChangedCallback<HostedFieldsValidity>nullable

Called on the UI thread when the validity of entered card details changes.

Properties · HostedFieldsValidity

Validity update for the entered card details.

isValidBoolean: True when the card details pass field validation. This does not establish that the card can be charged.

onUpdateCallback<HostedFieldsStatus>nullable

Receives the current status immediately when assigned, then subsequent status updates on the UI thread.

Properties · HostedFieldsStatus

Combined snapshot of field readiness, validity, and recommended payment-button state.

stateSdkState

Readiness of the mounted card fields.

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.

paymentButtonStatePaymentButtonState

Recommended visibility and enabled state of the payment button. Active means ready to pay; processing a payment makes the button disabled.

Values · PaymentButtonState

Recommended visibility and enabled state of your card-payment button. The recommendation accounts for field readiness and whether another payment can start.

Hidden / Swift .hiddenvalue: Hide the pay button (or deliberately show it disabled).
Disabled / Swift .disabledvalue: Show it disabled while inputs are invalid, payment is processing, or another payment cannot start.
Active / Swift .activevalue: Enable the payment action. The fields are ready and valid, and the SDK can start a payment.

isValidBoolean

Whether the entered card details pass field validation. This does not guarantee that the payment will be authorized.

onSubmitCallbacknullable

Called when the customer submits the ready fields, for example using the keyboard. Start payment when the payment-button state is active.

clear()

Clear the entered card details without unmounting the fields.

Kotlin suspend · Swift async throws

Returns Unit / Void

Throws EpayException. See error handling.

focus(data)

Move input focus to the selected card field. The cardholder-name field must be enabled before it can receive focus.

Kotlin suspend · Swift async throws

Parameters

dataHostedFieldFocusDatarequired

Card field that should receive focus.

Properties · HostedFieldFocusData

Identifies the card field that should receive input focus.

fieldHostedFieldoptionaldefault: Pan

Field to focus. Defaults to HostedField.Pan; the name field must be enabled before focusing HostedField.Name.

Values · HostedField

Card field that can be selected for input focus.

Panvalue: Card-number field.
Expiryvalue: Card expiration month and year field.
Cvcvalue: Card security-code field.
Namevalue: Cardholder-name field, available when enabled in the field configuration.

Returns Unit / Void

Throws EpayException. See error handling.

setLanguage(data)

Change the language of mounted fields. After success, the SDK also uses this language for shopper-facing messages.

Kotlin suspend · Swift async throws

Parameters

dataHostedFieldsLanguageDatarequired

Language to apply to field labels and messages.

Properties · HostedFieldsLanguageData

Language selection for already-mounted card fields.

languageString: Language code for field labels and messages, for example da or en.

Returns Unit / Void

Throws EpayException. See error handling.

insertTestCard(data)

Fill the fields with test card values. Only applies in TEST or PREVIEW mode; ignored in other modes.

Kotlin suspend · Swift async throws

Parameters

dataHostedFieldsTestCardDatarequired

Test card values to insert into the mounted fields.

Properties · HostedFieldsTestCardData

Test card values to insert into the fields in TEST or PREVIEW mode. Never supply real card details.

panString: Test card number as a string of digits.
expiryString: Test card expiry in MMYY format, for example 1230 for December 2030.
cvcString: Test card security code as a string.
nameStringoptionalnullable: Optional cardholder name for the enabled name field.
brandStringoptionalnullable: Optional card brand to select for the test card.

Returns Unit / Void

Throws EpayException. See error handling.

dispose()

Release the component and callbacks. Safe to repeat; remount with a new platform view.

Returns Unit / Void

handleReturnUrl(url)

Pass an incoming app-return URL to the SDK. Returns true when consumed, or false for unrelated, stale, or duplicate returns. A consumed URL does not establish payment success.

Parameters

urlStringrequired: Complete incoming URL received by the app’s URL or app-link handler.

Returns Boolean

checkGooglePayAvailability(data)

Check whether Google Pay can be offered for this session, device, and transaction options on Android.

Kotlin suspend · Swift async throws

Parameters

dataGooglePayDatarequired

Transaction options to use when checking Google Pay availability.

Properties · GooglePayData

Options for checking Google Pay availability on Android.

optionsTransactionOptionsoptional

Transaction options for the payment you intend to offer. Omit to use the session’s default payment options.

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

Returns WalletAvailability

Properties · WalletAvailability

Result of checking whether a device wallet can be offered for the current session.

isAvailableBoolean: Whether this wallet is available for the current session and device.

Throws EpayException. See error handling.

checkApplePayAvailability(data)

Check whether Apple Pay can be offered for this session, device, and merchant identifier on iOS.

Kotlin suspend · Swift async throws

Parameters

dataApplePayDatarequired

Apple merchant identifier and transaction options to use for the availability check.

Properties · ApplePayData

Merchant configuration and options for checking Apple Pay availability on iOS.

merchantIdentifierString

Apple merchant identifier matching the app’s Apple Pay entitlement.

optionsTransactionOptionsoptional

Transaction options for the payment you intend to offer. Omit to use the session’s default payment options.

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

Returns WalletAvailability

Properties · WalletAvailability

Result of checking whether a device wallet can be offered for the current session.

isAvailableBoolean: Whether this wallet is available for the current session and device.

Throws EpayException. See error handling.

SdkState

SdkState reference

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.

PaymentHostConfig

PaymentHostConfig reference

App-return routing and presentation settings. Configure these before creating the payment host.

appReturnUrlStringoptionalnullable: Optional HTTPS or custom-scheme URL for payment processing returns. No query, fragment, credentials, or port.
appUniversalLinkStringoptionalnullable: Optional registered HTTPS Universal Link / Android App Link. Required for iOS PayPal approval. Same URL restrictions apply.
systemBarColorStringoptionaldefault: "#FFFFFF": Background color used for system bars during payment presentation. Must be an opaque #RRGGBB string; defaults to #FFFFFF. Invalid formats throw immediately.

EpayException

EpayException reference

Exception thrown when an SDK operation cannot complete. In Swift, use EpayErrors to extract SDK details from the caught error.

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.

EpayErrors

EpayErrors reference

Swift helper for extracting structured SDK details from a caught error.

details(error)

Swift: EpayErrors.shared.details(error:). Returns nil for errors without SDK details.

Parameters

errorNSErrorrequired: Caught error converted to NSError. Returns nil when it does not contain SDK error details.

Returns EpayErrorDetails?

Properties · EpayErrorDetails

Structured SDK error details extracted from a Swift error.

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.

AndroidPaymentHost

AndroidPaymentHost reference

Android presentation host for payment, wallet, and authentication flows.

AndroidPaymentHost(activity, config)

Create a payment host owned by the checkout activity.

Parameters

activityActivityrequired

Activity from which payment and authentication screens are presented.

configPaymentHostConfigoptional

Optional app-return and presentation settings. Omit to use the platform defaults.

Properties · PaymentHostConfig

App-return routing and presentation settings. Configure these before creating the payment host.

appReturnUrlStringoptionalnullable: Optional HTTPS or custom-scheme URL for payment processing returns. No query, fragment, credentials, or port.
appUniversalLinkStringoptionalnullable: Optional registered HTTPS Universal Link / Android App Link. Required for iOS PayPal approval. Same URL restrictions apply.
systemBarColorStringoptionaldefault: "#FFFFFF": Background color used for system bars during payment presentation. Must be an opaque #RRGGBB string; defaults to #FFFFFF. Invalid formats throw immediately.

Returns AndroidPaymentHost

AndroidPaymentHost reference

IosPaymentHost

IosPaymentHost reference

iOS presentation host for payment, wallet, and authentication flows.

IosPaymentHost(viewController:config:)

Create a payment host using the standard Swift initializer from EpayPayPal.

Parameters

viewControllerUIViewControllerrequired

View controller from which payment and authentication screens are presented.

configPaymentHostConfigoptional

Optional app-return and presentation settings. Configure the URLs required by the payment methods you offer.

Properties · PaymentHostConfig

App-return routing and presentation settings. Configure these before creating the payment host.

appReturnUrlStringoptionalnullable: Optional HTTPS or custom-scheme URL for payment processing returns. No query, fragment, credentials, or port.
appUniversalLinkStringoptionalnullable: Optional registered HTTPS Universal Link / Android App Link. Required for iOS PayPal approval. Same URL restrictions apply.
systemBarColorStringoptionaldefault: "#FFFFFF": Background color used for system bars during payment presentation. Must be an opaque #RRGGBB string; defaults to #FFFFFF. Invalid formats throw immediately.

Returns IosPaymentHost

IosPaymentHost reference

EpayErrorDetails

EpayErrorDetails reference

Structured SDK error details extracted from a Swift error.

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.

Payments and outcomes

Payment

Payment reference

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.

TransactionOptions

TransactionOptions reference

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

PaymentAttemptHandlers

PaymentAttemptHandlers reference

Callbacks copied to each attempt created by a payment object.

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

PaymentAttempt

PaymentAttempt reference

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.

PaymentAttemptMetadata

PaymentAttemptMetadata reference

Additional authorization history for the payment attempt.

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

PaymentAttemptState

PaymentAttemptState reference

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.

Card fields

HostedFields

HostedFields reference

Mounted card-entry component returned by mountFields(). Control methods require the fields to be ready.

stateSdkState

Current field readiness, independent of the SDK’s session readiness.

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.

isValidBoolean

Whether the entered card details pass field validation. Use status.paymentButtonState to decide when payment is available.

statusHostedFieldsStatus

Latest combined readiness, validity, and payment-button recommendation.

Properties · HostedFieldsStatus

Combined snapshot of field readiness, validity, and recommended payment-button state.

stateSdkState

Readiness of the mounted card fields.

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.

paymentButtonStatePaymentButtonState

Recommended visibility and enabled state of the payment button. Active means ready to pay; processing a payment makes the button disabled.

Values · PaymentButtonState

Recommended visibility and enabled state of your card-payment button. The recommendation accounts for field readiness and whether another payment can start.

Hidden / Swift .hiddenvalue: Hide the pay button (or deliberately show it disabled).
Disabled / Swift .disabledvalue: Show it disabled while inputs are invalid, payment is processing, or another payment cannot start.
Active / Swift .activevalue: Enable the payment action. The fields are ready and valid, and the SDK can start a payment.

isValidBoolean

Whether the entered card details pass field validation. This does not guarantee that the payment will be authorized.

onReadinessChangedCallback<SdkState>nullable

Called on the UI thread when field readiness changes.

onValidityChangedCallback<HostedFieldsValidity>nullable

Called on the UI thread when the validity of entered card details changes.

Properties · HostedFieldsValidity

Validity update for the entered card details.

isValidBoolean: True when the card details pass field validation. This does not establish that the card can be charged.

onUpdateCallback<HostedFieldsStatus>nullable

Receives the current status immediately when assigned, then subsequent status updates on the UI thread.

Properties · HostedFieldsStatus

Combined snapshot of field readiness, validity, and recommended payment-button state.

stateSdkState

Readiness of the mounted card fields.

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.

paymentButtonStatePaymentButtonState

Recommended visibility and enabled state of the payment button. Active means ready to pay; processing a payment makes the button disabled.

Values · PaymentButtonState

Recommended visibility and enabled state of your card-payment button. The recommendation accounts for field readiness and whether another payment can start.

Hidden / Swift .hiddenvalue: Hide the pay button (or deliberately show it disabled).
Disabled / Swift .disabledvalue: Show it disabled while inputs are invalid, payment is processing, or another payment cannot start.
Active / Swift .activevalue: Enable the payment action. The fields are ready and valid, and the SDK can start a payment.

isValidBoolean

Whether the entered card details pass field validation. This does not guarantee that the payment will be authorized.

onSubmitCallbacknullable

Called when the customer submits the ready fields, for example using the keyboard. Start payment when the payment-button state is active.

clear()

Clear the entered card details without unmounting the fields.

Kotlin suspend · Swift async throws

Returns Unit / Void

Throws EpayException. See error handling.

focus(data)

Move input focus to the selected card field. The cardholder-name field must be enabled before it can receive focus.

Kotlin suspend · Swift async throws

Parameters

dataHostedFieldFocusDatarequired

Card field that should receive focus.

Properties · HostedFieldFocusData

Identifies the card field that should receive input focus.

fieldHostedFieldoptionaldefault: Pan

Field to focus. Defaults to HostedField.Pan; the name field must be enabled before focusing HostedField.Name.

Values · HostedField

Card field that can be selected for input focus.

Panvalue: Card-number field.
Expiryvalue: Card expiration month and year field.
Cvcvalue: Card security-code field.
Namevalue: Cardholder-name field, available when enabled in the field configuration.

Returns Unit / Void

Throws EpayException. See error handling.

setLanguage(data)

Change the language of mounted fields. After success, the SDK also uses this language for shopper-facing messages.

Kotlin suspend · Swift async throws

Parameters

dataHostedFieldsLanguageDatarequired

Language to apply to field labels and messages.

Properties · HostedFieldsLanguageData

Language selection for already-mounted card fields.

languageString: Language code for field labels and messages, for example da or en.

Returns Unit / Void

Throws EpayException. See error handling.

insertTestCard(data)

Fill the fields with test card values. Only applies in TEST or PREVIEW mode; ignored in other modes.

Kotlin suspend · Swift async throws

Parameters

dataHostedFieldsTestCardDatarequired

Test card values to insert into the mounted fields.

Properties · HostedFieldsTestCardData

Test card values to insert into the fields in TEST or PREVIEW mode. Never supply real card details.

panString: Test card number as a string of digits.
expiryString: Test card expiry in MMYY format, for example 1230 for December 2030.
cvcString: Test card security code as a string.
nameStringoptionalnullable: Optional cardholder name for the enabled name field.
brandStringoptionalnullable: Optional card brand to select for the test card.

Returns Unit / Void

Throws EpayException. See error handling.

dispose()

Release the component and callbacks. Safe to repeat; remount with a new platform view.

Returns Unit / Void

HostedFieldsConfig

HostedFieldsConfig reference

Appearance, initial layout, and callbacks supplied when mounting card fields.

appearanceFieldsAppearanceoptional

Language and visual configuration for the fields. Uses the mobile theme by default.

Properties · FieldsAppearance

Language, theme, and appearance of the card fields. Unspecified styling values use the selected theme.

languageStringoptionalnullable

Language code for field labels and messages, for example da or en.

themeStringoptionalnullabledefault: "mobile"

Base appearance theme. Defaults to mobile, which is designed for app checkout.

variablesFieldsVariablesoptionalnullable

Individual colors, spacing, and typography settings that override the theme.

Properties · FieldsVariables

Card-field style overrides expressed as CSS value strings, such as #222222, 16px, or 0. Omit a value to keep the theme setting.

colorTextStringoptionalnullable: Default text color for labels and input content.
borderRadiusStringoptionalnullable: Default corner radius for inputs and the field container.
borderColorStringoptionalnullable: Default border color for inputs and the field container.
fontFamilyStringoptionalnullable: Font family used for labels, entered values, and placeholders.
gridColumnSpacingStringoptionalnullable: Horizontal space between fields, for example 12px.
gridRowSpacingStringoptionalnullable: Vertical space between fields, for example 16px.
gridTemplateColumnsStringoptionalnullable: Column sizes for the field grid, for example 1fr 1fr for two equal columns.
iconDisplayStringoptionalnullable: Display behavior for field icons, for example block or none.
cardBrandDisplayStringoptionalnullable: Display behavior for card-brand icons, for example block or none.
supportedSchemesDisplayStringoptionalnullable: Display behavior for supported card-scheme icons, for example flex or none.
labelColorStringoptionalnullable: Text color of field labels.
labelFontSizeStringoptionalnullable: Font size of field labels, for example 14px.
labelFontWeightStringoptionalnullable: Font weight of field labels, for example 400 or 600.
labelMarginBottomStringoptionalnullable: Space between a label and its input.
inputColorStringoptionalnullable: Text color of entered values.
inputBorderRadiusStringoptionalnullable: Corner radius of input fields.
inputBorderColorStringoptionalnullable: Border color of input fields.
inputFontSizeStringoptionalnullable: Font size of entered values.
inputPaddingStringoptionalnullable: Space inside each input border, for example 12px.
inputPlaceholderColorStringoptionalnullable: Text color of input placeholders.
inputBackgroundColorStringoptionalnullable: Background color of input fields.
inputBoxShadowStringoptionalnullable: Shadow around input fields, or none to remove it.
inputFocusBorderColorStringoptionalnullable: Input border color while the field has focus.
inputFocusBoxShadowStringoptionalnullable: Input shadow while the field has focus.
windowPaddingStringoptionalnullable: Space around the fields inside their container.
windowBackgroundColorStringoptionalnullable: Background color of the field container.
windowBorderStyleStringoptionalnullable: Border style of the field container, for example solid or none.
windowBorderRadiusStringoptionalnullable: Corner radius of the field container.
windowBorderColorStringoptionalnullable: Border color of the field container.
colorDangerStringoptionalnullable: Color used for validation errors and other field problems.
colorPrimaryStringoptionalnullable: Primary accent color of the card fields.

fieldsFieldsConfigurationoptionalnullable

Visibility and initial behavior of the cardholder-name and card-number fields.

Properties · FieldsConfiguration

Options for individual card fields.

nameFieldsNameoptionalnullable

Cardholder-name field settings.

Properties · FieldsName

Visibility and initial value of the optional cardholder-name field.

enabledBooleanoptionalnullable: Show the cardholder-name field when true. It is hidden by default.
valueStringoptionalnullable: Initial cardholder name to prefill when the name field is enabled.

panFieldsPanoptionalnullable

Card-number field settings.

Properties · FieldsPan

Card-number field behavior and card-brand controls.

focusBooleanoptionalnullable: Focus the card-number field when it mounts. Defaults to true.
showSupportedSchemesBooleanoptionalnullable: Show the supported card-scheme icons. Defaults to true.
showBrandSelectorBooleanoptionalnullable: Show the brand selector for cards supporting multiple brands. Defaults to true.

fontSelectionFieldsFontoptionalnullable

Font source and family selection. Supply source, family, category, and stack together.

Properties · FieldsFont

Font selection for the card fields. Provide all four values together.

sourceStringoptionalnullable: Font source: system for an available system font or google for a Google Font.
familyStringoptionalnullable: Name of the selected font family, for example Roboto.
categoryStringoptionalnullable: Generic font category, for example sans-serif.
stackStringoptionalnullable: Ordered font-family list including fallbacks, for example Roboto, sans-serif.

loaderFieldsLoaderoptionalnullable

Appearance of the loading placeholder shown while fields initialize.

Properties · FieldsLoader

Style of the placeholder displayed while card fields load.

heightStringoptionalnullable: Placeholder height as a CSS length, for example 150px.
backgroundColorStringoptionalnullable: Placeholder background color, for example transparent.
borderStyleStringoptionalnullable: Placeholder border style, for example solid or none.

initialHeightDoubleoptionaldefault: 190.0

Space reserved before the fields report their height, in Android density-independent pixels or iOS points. Must be finite and greater than zero.

onReadinessChangedCallback<SdkState>optionalnullable

Called when the fields change between loading, ready, and failed states.

onUpdateCallback<HostedFieldsStatus>optionalnullable

Receives the current combined field status and subsequent updates. Use its payment-button recommendation to update your checkout button.

Properties · HostedFieldsStatus

Combined snapshot of field readiness, validity, and recommended payment-button state.

stateSdkState

Readiness of the mounted card fields.

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.

paymentButtonStatePaymentButtonState

Recommended visibility and enabled state of the payment button. Active means ready to pay; processing a payment makes the button disabled.

Values · PaymentButtonState

Recommended visibility and enabled state of your card-payment button. The recommendation accounts for field readiness and whether another payment can start.

Hidden / Swift .hiddenvalue: Hide the pay button (or deliberately show it disabled).
Disabled / Swift .disabledvalue: Show it disabled while inputs are invalid, payment is processing, or another payment cannot start.
Active / Swift .activevalue: Enable the payment action. The fields are ready and valid, and the SDK can start a payment.

isValidBoolean

Whether the entered card details pass field validation. This does not guarantee that the payment will be authorized.

onSubmitCallbackoptionalnullable

Called when the customer submits the ready fields, for example using the keyboard. Start a card payment from this callback when the payment button is active.

HostedFieldsStatus

HostedFieldsStatus reference

Combined snapshot of field readiness, validity, and recommended payment-button state.

stateSdkState

Readiness of the mounted card fields.

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.

paymentButtonStatePaymentButtonState

Recommended visibility and enabled state of the payment button. Active means ready to pay; processing a payment makes the button disabled.

Values · PaymentButtonState

Recommended visibility and enabled state of your card-payment button. The recommendation accounts for field readiness and whether another payment can start.

Hidden / Swift .hiddenvalue: Hide the pay button (or deliberately show it disabled).
Disabled / Swift .disabledvalue: Show it disabled while inputs are invalid, payment is processing, or another payment cannot start.
Active / Swift .activevalue: Enable the payment action. The fields are ready and valid, and the SDK can start a payment.

isValidBoolean

Whether the entered card details pass field validation. This does not guarantee that the payment will be authorized.

HostedFieldsValidity

HostedFieldsValidity reference

Validity update for the entered card details.

isValidBoolean: True when the card details pass field validation. This does not establish that the card can be charged.

PaymentButtonState

PaymentButtonState reference

Recommended visibility and enabled state of your card-payment button. The recommendation accounts for field readiness and whether another payment can start.

Hidden / Swift .hiddenvalue: Hide the pay button (or deliberately show it disabled).
Disabled / Swift .disabledvalue: Show it disabled while inputs are invalid, payment is processing, or another payment cannot start.
Active / Swift .activevalue: Enable the payment action. The fields are ready and valid, and the SDK can start a payment.

HostedField

HostedField reference

Card field that can be selected for input focus.

Panvalue: Card-number field.
Expiryvalue: Card expiration month and year field.
Cvcvalue: Card security-code field.
Namevalue: Cardholder-name field, available when enabled in the field configuration.

HostedFieldFocusData

HostedFieldFocusData reference

Identifies the card field that should receive input focus.

fieldHostedFieldoptionaldefault: Pan

Field to focus. Defaults to HostedField.Pan; the name field must be enabled before focusing HostedField.Name.

Values · HostedField

Card field that can be selected for input focus.

Panvalue: Card-number field.
Expiryvalue: Card expiration month and year field.
Cvcvalue: Card security-code field.
Namevalue: Cardholder-name field, available when enabled in the field configuration.

HostedFieldsLanguageData

HostedFieldsLanguageData reference

Language selection for already-mounted card fields.

languageString: Language code for field labels and messages, for example da or en.

HostedFieldsTestCardData

HostedFieldsTestCardData reference

Test card values to insert into the fields in TEST or PREVIEW mode. Never supply real card details.

panString: Test card number as a string of digits.
expiryString: Test card expiry in MMYY format, for example 1230 for December 2030.
cvcString: Test card security code as a string.
nameStringoptionalnullable: Optional cardholder name for the enabled name field.
brandStringoptionalnullable: Optional card brand to select for the test card.

FieldsAppearance

FieldsAppearance reference

Language, theme, and appearance of the card fields. Unspecified styling values use the selected theme.

languageStringoptionalnullable

Language code for field labels and messages, for example da or en.

themeStringoptionalnullabledefault: "mobile"

Base appearance theme. Defaults to mobile, which is designed for app checkout.

variablesFieldsVariablesoptionalnullable

Individual colors, spacing, and typography settings that override the theme.

Properties · FieldsVariables

Card-field style overrides expressed as CSS value strings, such as #222222, 16px, or 0. Omit a value to keep the theme setting.

colorTextStringoptionalnullable: Default text color for labels and input content.
borderRadiusStringoptionalnullable: Default corner radius for inputs and the field container.
borderColorStringoptionalnullable: Default border color for inputs and the field container.
fontFamilyStringoptionalnullable: Font family used for labels, entered values, and placeholders.
gridColumnSpacingStringoptionalnullable: Horizontal space between fields, for example 12px.
gridRowSpacingStringoptionalnullable: Vertical space between fields, for example 16px.
gridTemplateColumnsStringoptionalnullable: Column sizes for the field grid, for example 1fr 1fr for two equal columns.
iconDisplayStringoptionalnullable: Display behavior for field icons, for example block or none.
cardBrandDisplayStringoptionalnullable: Display behavior for card-brand icons, for example block or none.
supportedSchemesDisplayStringoptionalnullable: Display behavior for supported card-scheme icons, for example flex or none.
labelColorStringoptionalnullable: Text color of field labels.
labelFontSizeStringoptionalnullable: Font size of field labels, for example 14px.
labelFontWeightStringoptionalnullable: Font weight of field labels, for example 400 or 600.
labelMarginBottomStringoptionalnullable: Space between a label and its input.
inputColorStringoptionalnullable: Text color of entered values.
inputBorderRadiusStringoptionalnullable: Corner radius of input fields.
inputBorderColorStringoptionalnullable: Border color of input fields.
inputFontSizeStringoptionalnullable: Font size of entered values.
inputPaddingStringoptionalnullable: Space inside each input border, for example 12px.
inputPlaceholderColorStringoptionalnullable: Text color of input placeholders.
inputBackgroundColorStringoptionalnullable: Background color of input fields.
inputBoxShadowStringoptionalnullable: Shadow around input fields, or none to remove it.
inputFocusBorderColorStringoptionalnullable: Input border color while the field has focus.
inputFocusBoxShadowStringoptionalnullable: Input shadow while the field has focus.
windowPaddingStringoptionalnullable: Space around the fields inside their container.
windowBackgroundColorStringoptionalnullable: Background color of the field container.
windowBorderStyleStringoptionalnullable: Border style of the field container, for example solid or none.
windowBorderRadiusStringoptionalnullable: Corner radius of the field container.
windowBorderColorStringoptionalnullable: Border color of the field container.
colorDangerStringoptionalnullable: Color used for validation errors and other field problems.
colorPrimaryStringoptionalnullable: Primary accent color of the card fields.

fieldsFieldsConfigurationoptionalnullable

Visibility and initial behavior of the cardholder-name and card-number fields.

Properties · FieldsConfiguration

Options for individual card fields.

nameFieldsNameoptionalnullable

Cardholder-name field settings.

Properties · FieldsName

Visibility and initial value of the optional cardholder-name field.

enabledBooleanoptionalnullable: Show the cardholder-name field when true. It is hidden by default.
valueStringoptionalnullable: Initial cardholder name to prefill when the name field is enabled.

panFieldsPanoptionalnullable

Card-number field settings.

Properties · FieldsPan

Card-number field behavior and card-brand controls.

focusBooleanoptionalnullable: Focus the card-number field when it mounts. Defaults to true.
showSupportedSchemesBooleanoptionalnullable: Show the supported card-scheme icons. Defaults to true.
showBrandSelectorBooleanoptionalnullable: Show the brand selector for cards supporting multiple brands. Defaults to true.

fontSelectionFieldsFontoptionalnullable

Font source and family selection. Supply source, family, category, and stack together.

Properties · FieldsFont

Font selection for the card fields. Provide all four values together.

sourceStringoptionalnullable: Font source: system for an available system font or google for a Google Font.
familyStringoptionalnullable: Name of the selected font family, for example Roboto.
categoryStringoptionalnullable: Generic font category, for example sans-serif.
stackStringoptionalnullable: Ordered font-family list including fallbacks, for example Roboto, sans-serif.

loaderFieldsLoaderoptionalnullable

Appearance of the loading placeholder shown while fields initialize.

Properties · FieldsLoader

Style of the placeholder displayed while card fields load.

heightStringoptionalnullable: Placeholder height as a CSS length, for example 150px.
backgroundColorStringoptionalnullable: Placeholder background color, for example transparent.
borderStyleStringoptionalnullable: Placeholder border style, for example solid or none.

FieldsVariables

FieldsVariables reference

Card-field style overrides expressed as CSS value strings, such as #222222, 16px, or 0. Omit a value to keep the theme setting.

colorTextStringoptionalnullable: Default text color for labels and input content.
borderRadiusStringoptionalnullable: Default corner radius for inputs and the field container.
borderColorStringoptionalnullable: Default border color for inputs and the field container.
fontFamilyStringoptionalnullable: Font family used for labels, entered values, and placeholders.
gridColumnSpacingStringoptionalnullable: Horizontal space between fields, for example 12px.
gridRowSpacingStringoptionalnullable: Vertical space between fields, for example 16px.
gridTemplateColumnsStringoptionalnullable: Column sizes for the field grid, for example 1fr 1fr for two equal columns.
iconDisplayStringoptionalnullable: Display behavior for field icons, for example block or none.
cardBrandDisplayStringoptionalnullable: Display behavior for card-brand icons, for example block or none.
supportedSchemesDisplayStringoptionalnullable: Display behavior for supported card-scheme icons, for example flex or none.
labelColorStringoptionalnullable: Text color of field labels.
labelFontSizeStringoptionalnullable: Font size of field labels, for example 14px.
labelFontWeightStringoptionalnullable: Font weight of field labels, for example 400 or 600.
labelMarginBottomStringoptionalnullable: Space between a label and its input.
inputColorStringoptionalnullable: Text color of entered values.
inputBorderRadiusStringoptionalnullable: Corner radius of input fields.
inputBorderColorStringoptionalnullable: Border color of input fields.
inputFontSizeStringoptionalnullable: Font size of entered values.
inputPaddingStringoptionalnullable: Space inside each input border, for example 12px.
inputPlaceholderColorStringoptionalnullable: Text color of input placeholders.
inputBackgroundColorStringoptionalnullable: Background color of input fields.
inputBoxShadowStringoptionalnullable: Shadow around input fields, or none to remove it.
inputFocusBorderColorStringoptionalnullable: Input border color while the field has focus.
inputFocusBoxShadowStringoptionalnullable: Input shadow while the field has focus.
windowPaddingStringoptionalnullable: Space around the fields inside their container.
windowBackgroundColorStringoptionalnullable: Background color of the field container.
windowBorderStyleStringoptionalnullable: Border style of the field container, for example solid or none.
windowBorderRadiusStringoptionalnullable: Corner radius of the field container.
windowBorderColorStringoptionalnullable: Border color of the field container.
colorDangerStringoptionalnullable: Color used for validation errors and other field problems.
colorPrimaryStringoptionalnullable: Primary accent color of the card fields.

FieldsConfiguration

FieldsConfiguration reference

Options for individual card fields.

nameFieldsNameoptionalnullable

Cardholder-name field settings.

Properties · FieldsName

Visibility and initial value of the optional cardholder-name field.

enabledBooleanoptionalnullable: Show the cardholder-name field when true. It is hidden by default.
valueStringoptionalnullable: Initial cardholder name to prefill when the name field is enabled.

panFieldsPanoptionalnullable

Card-number field settings.

Properties · FieldsPan

Card-number field behavior and card-brand controls.

focusBooleanoptionalnullable: Focus the card-number field when it mounts. Defaults to true.
showSupportedSchemesBooleanoptionalnullable: Show the supported card-scheme icons. Defaults to true.
showBrandSelectorBooleanoptionalnullable: Show the brand selector for cards supporting multiple brands. Defaults to true.

FieldsName

FieldsName reference

Visibility and initial value of the optional cardholder-name field.

enabledBooleanoptionalnullable: Show the cardholder-name field when true. It is hidden by default.
valueStringoptionalnullable: Initial cardholder name to prefill when the name field is enabled.

FieldsPan

FieldsPan reference

Card-number field behavior and card-brand controls.

focusBooleanoptionalnullable: Focus the card-number field when it mounts. Defaults to true.
showSupportedSchemesBooleanoptionalnullable: Show the supported card-scheme icons. Defaults to true.
showBrandSelectorBooleanoptionalnullable: Show the brand selector for cards supporting multiple brands. Defaults to true.

FieldsFont

FieldsFont reference

Font selection for the card fields. Provide all four values together.

sourceStringoptionalnullable: Font source: system for an available system font or google for a Google Font.
familyStringoptionalnullable: Name of the selected font family, for example Roboto.
categoryStringoptionalnullable: Generic font category, for example sans-serif.
stackStringoptionalnullable: Ordered font-family list including fallbacks, for example Roboto, sans-serif.

FieldsLoader

FieldsLoader reference

Style of the placeholder displayed while card fields load.

heightStringoptionalnullable: Placeholder height as a CSS length, for example 150px.
backgroundColorStringoptionalnullable: Placeholder background color, for example transparent.
borderStyleStringoptionalnullable: Placeholder border style, for example solid or none.

AndroidHostedFields

AndroidHostedFields reference

Android view that contains the card-entry fields.

AndroidHostedFields(context)

Create the field view and add it to your checkout layout before calling mountFields().

Parameters

contextContextrequired: Android UI context used to create the field view, normally the checkout activity.

Returns AndroidHostedFields

AndroidHostedFields reference

IosHostedFields

IosHostedFields reference

iOS card-entry container exposing a view for your checkout layout.

IosHostedFields(): Create a field container. Add its view to your layout before calling mountFields().
Returns IosHostedFields
IosHostedFields reference
viewUIView: Add to your layout and constrain its width and position; the SDK manages height.

Session services

SessionData

SessionData reference

Payment session and checkout configuration loaded during SDK initialization. This is a snapshot; use payment attempts to observe payment progress.

sessionSessionInfo

Payment details and restrictions set when your server created the session.

Properties · SessionInfo

Details of the payment session created by your server. Amounts use the session currency.

idString

Unique ID of the payment session.

pointOfSaleIdString

ID of the point of sale associated with the session.

timeoutInt

Session lifetime in minutes, as configured when the session was created.

instantCaptureString

Instant-capture mode configured for the session: OFF, VOID, or NO_VOID.

referenceStringnullable

Your transaction reference, typically an order ID. Null when none was supplied.

hasSubscriptionBoolean

Whether the session is associated with a subscription.

amountLong

Transaction amount in minor units, for example 1095 for 10.95 DKK.

currencyString

Three-letter ISO 4217 currency code, for example DKK.

textOnStatementStringnullable

Text requested for the cardholder’s bank statement. Null when no custom text was supplied.

descriptorStringnullable

Merchant descriptor supplied for this session. Overrides the point-of-sale descriptor unless an acquirer agreement supplies an override.

stateString

Session state at initialization, such as PENDING, PROCESSING, COMPLETED, or EXPIRED. This property does not track subsequent payment progress.

dynamicAmountBoolean

Whether the app may override the session amount through TransactionOptions.amount.

minimumAgeInt

Minimum required customer age in years. Zero means no age requirement was configured.

ageVerifiedBoolean

Whether the customer had been verified as meeting the minimum age when this snapshot was loaded.

createdAtSessionTimestamp

Time the payment session was created. Uses kotlin.time.Instant on Android and Foundation Date in Swift.

expiresAtSessionTimestamp

Time after which the session can no longer be used. Create a new session to continue checkout after expiry.

customerInfoSessionCustomerInfonullable

Customer contact and address details supplied for the session, or null when none were supplied.

Properties · SessionCustomerInfo

Customer details supplied by your server for authentication and payment-provider requirements.

firstNameStringnullable

Customer’s given name.

lastNameStringnullable

Customer’s family name.

emailStringnullable

Customer’s email address.

phoneNumberStringnullable

Customer’s phone number in E.164 format with a space after the country calling code, for example +45 12345678.

shippingAddressSessionCustomerAddressnullable

Address to which purchased goods will be delivered.

Properties · SessionCustomerAddress

Postal address supplied for billing or shipping. Unspecified address fields are null.

countryCodeStringnullable: Two-letter ISO 3166-1 alpha-2 country code, for example DK.
postalCodeStringnullable: Postal or ZIP code.
cityStringnullable: City or locality.
line1Stringnullable: First address line, usually the street name and building number.
line2Stringnullable: Additional address details, such as an apartment or suite.
line3Stringnullable: Further address details when two lines are insufficient.

billingAddressSessionCustomerAddressnullable

Customer’s personal or business billing address.

Properties · SessionCustomerAddress

Postal address supplied for billing or shipping. Unspecified address fields are null.

countryCodeStringnullable: Two-letter ISO 3166-1 alpha-2 country code, for example DK.
postalCodeStringnullable: Postal or ZIP code.
cityStringnullable: City or locality.
line1Stringnullable: First address line, usually the street name and building number.
line2Stringnullable: Additional address details, such as an apartment or suite.
line3Stringnullable: Further address details when two lines are insufficient.

allowedPaymentMethodsList<String>nullable

Payment-method restrictions supplied for the session. Null means no session-specific list was supplied; use getSupportedPaymentMethodTypes() for available methods.

pointOfSaleSessionPointOfSale

Point-of-sale settings associated with this session.

Properties · SessionPointOfSale

Point-of-sale settings used by the payment session.

descriptorString: Default merchant descriptor for the point of sale.
domainsList<String>nullable: Domains configured for the point of sale, or null when none are supplied.

countryCodeString

Merchant account country as an ISO 3166-1 alpha-2 code, for example DK.

supportedSchemesList<String>nullable

Card schemes supported for this session, for example VISA and MASTERCARD. Null when no list is supplied.

canStorePaymentMethodBoolean

Whether the session has a customer ID and can store a payment method for that customer. Use this to decide whether to offer a save-payment-method option.

subscriptionSessionSubscriptionnullable

Subscription configuration associated with the session, or null when there is no subscription.

Properties · SessionSubscription

Recurring-payment agreement configured for this session.

typeString

Agreement type: SCHEDULED for payments at a fixed interval or UNSCHEDULED for payments as needed.

intervalSessionSubscriptionIntervalnullable

Billing interval for a scheduled subscription. Null when no interval was supplied.

Properties · SessionSubscriptionInterval

Frequency of scheduled subscription payments.

periodString: Billing unit: DAY, WEEK, MONTH, or YEAR.
frequencyInt: Number of billing units between payments, from 1 to 31. For example, 3 with MONTH means every three months.

expiryDateSessionDatenullable

Agreement expiry date supplied for authentication. ePay does not reject later payments solely because this date has passed.

Properties · SessionDate

Calendar date without a time or time zone.

yearInt: Four-digit calendar year, for example 2030.
monthInt: Month of the year, from 1 to 12.
dayInt: Day of the month, from 1 to 31 as permitted by the month.

amountLongnullable

Recurring amount in minor units. When null, the transaction amount is used.

SessionInfo

SessionInfo reference

Details of the payment session created by your server. Amounts use the session currency.

idString

Unique ID of the payment session.

pointOfSaleIdString

ID of the point of sale associated with the session.

timeoutInt

Session lifetime in minutes, as configured when the session was created.

instantCaptureString

Instant-capture mode configured for the session: OFF, VOID, or NO_VOID.

referenceStringnullable

Your transaction reference, typically an order ID. Null when none was supplied.

hasSubscriptionBoolean

Whether the session is associated with a subscription.

amountLong

Transaction amount in minor units, for example 1095 for 10.95 DKK.

currencyString

Three-letter ISO 4217 currency code, for example DKK.

textOnStatementStringnullable

Text requested for the cardholder’s bank statement. Null when no custom text was supplied.

descriptorStringnullable

Merchant descriptor supplied for this session. Overrides the point-of-sale descriptor unless an acquirer agreement supplies an override.

stateString

Session state at initialization, such as PENDING, PROCESSING, COMPLETED, or EXPIRED. This property does not track subsequent payment progress.

dynamicAmountBoolean

Whether the app may override the session amount through TransactionOptions.amount.

minimumAgeInt

Minimum required customer age in years. Zero means no age requirement was configured.

ageVerifiedBoolean

Whether the customer had been verified as meeting the minimum age when this snapshot was loaded.

createdAtSessionTimestamp

Time the payment session was created. Uses kotlin.time.Instant on Android and Foundation Date in Swift.

expiresAtSessionTimestamp

Time after which the session can no longer be used. Create a new session to continue checkout after expiry.

customerInfoSessionCustomerInfonullable

Customer contact and address details supplied for the session, or null when none were supplied.

Properties · SessionCustomerInfo

Customer details supplied by your server for authentication and payment-provider requirements.

firstNameStringnullable

Customer’s given name.

lastNameStringnullable

Customer’s family name.

emailStringnullable

Customer’s email address.

phoneNumberStringnullable

Customer’s phone number in E.164 format with a space after the country calling code, for example +45 12345678.

shippingAddressSessionCustomerAddressnullable

Address to which purchased goods will be delivered.

Properties · SessionCustomerAddress

Postal address supplied for billing or shipping. Unspecified address fields are null.

countryCodeStringnullable: Two-letter ISO 3166-1 alpha-2 country code, for example DK.
postalCodeStringnullable: Postal or ZIP code.
cityStringnullable: City or locality.
line1Stringnullable: First address line, usually the street name and building number.
line2Stringnullable: Additional address details, such as an apartment or suite.
line3Stringnullable: Further address details when two lines are insufficient.

billingAddressSessionCustomerAddressnullable

Customer’s personal or business billing address.

Properties · SessionCustomerAddress

Postal address supplied for billing or shipping. Unspecified address fields are null.

countryCodeStringnullable: Two-letter ISO 3166-1 alpha-2 country code, for example DK.
postalCodeStringnullable: Postal or ZIP code.
cityStringnullable: City or locality.
line1Stringnullable: First address line, usually the street name and building number.
line2Stringnullable: Additional address details, such as an apartment or suite.
line3Stringnullable: Further address details when two lines are insufficient.

allowedPaymentMethodsList<String>nullable

Payment-method restrictions supplied for the session. Null means no session-specific list was supplied; use getSupportedPaymentMethodTypes() for available methods.

SessionPointOfSale

SessionPointOfSale reference

Point-of-sale settings used by the payment session.

descriptorString: Default merchant descriptor for the point of sale.
domainsList<String>nullable: Domains configured for the point of sale, or null when none are supplied.

SessionSubscription

SessionSubscription reference

Recurring-payment agreement configured for this session.

typeString

Agreement type: SCHEDULED for payments at a fixed interval or UNSCHEDULED for payments as needed.

intervalSessionSubscriptionIntervalnullable

Billing interval for a scheduled subscription. Null when no interval was supplied.

Properties · SessionSubscriptionInterval

Frequency of scheduled subscription payments.

periodString: Billing unit: DAY, WEEK, MONTH, or YEAR.
frequencyInt: Number of billing units between payments, from 1 to 31. For example, 3 with MONTH means every three months.

expiryDateSessionDatenullable

Agreement expiry date supplied for authentication. ePay does not reject later payments solely because this date has passed.

Properties · SessionDate

Calendar date without a time or time zone.

yearInt: Four-digit calendar year, for example 2030.
monthInt: Month of the year, from 1 to 12.
dayInt: Day of the month, from 1 to 31 as permitted by the month.

amountLongnullable

Recurring amount in minor units. When null, the transaction amount is used.

SessionSubscriptionInterval

SessionSubscriptionInterval reference

Frequency of scheduled subscription payments.

periodString: Billing unit: DAY, WEEK, MONTH, or YEAR.
frequencyInt: Number of billing units between payments, from 1 to 31. For example, 3 with MONTH means every three months.

SessionCustomerInfo

SessionCustomerInfo reference

Customer details supplied by your server for authentication and payment-provider requirements.

firstNameStringnullable

Customer’s given name.

lastNameStringnullable

Customer’s family name.

emailStringnullable

Customer’s email address.

phoneNumberStringnullable

Customer’s phone number in E.164 format with a space after the country calling code, for example +45 12345678.

shippingAddressSessionCustomerAddressnullable

Address to which purchased goods will be delivered.

Properties · SessionCustomerAddress

Postal address supplied for billing or shipping. Unspecified address fields are null.

countryCodeStringnullable: Two-letter ISO 3166-1 alpha-2 country code, for example DK.
postalCodeStringnullable: Postal or ZIP code.
cityStringnullable: City or locality.
line1Stringnullable: First address line, usually the street name and building number.
line2Stringnullable: Additional address details, such as an apartment or suite.
line3Stringnullable: Further address details when two lines are insufficient.

billingAddressSessionCustomerAddressnullable

Customer’s personal or business billing address.

Properties · SessionCustomerAddress

Postal address supplied for billing or shipping. Unspecified address fields are null.

countryCodeStringnullable: Two-letter ISO 3166-1 alpha-2 country code, for example DK.
postalCodeStringnullable: Postal or ZIP code.
cityStringnullable: City or locality.
line1Stringnullable: First address line, usually the street name and building number.
line2Stringnullable: Additional address details, such as an apartment or suite.
line3Stringnullable: Further address details when two lines are insufficient.

SessionCustomerAddress

SessionCustomerAddress reference

Postal address supplied for billing or shipping. Unspecified address fields are null.

countryCodeStringnullable: Two-letter ISO 3166-1 alpha-2 country code, for example DK.
postalCodeStringnullable: Postal or ZIP code.
cityStringnullable: City or locality.
line1Stringnullable: First address line, usually the street name and building number.
line2Stringnullable: Additional address details, such as an apartment or suite.
line3Stringnullable: Further address details when two lines are insufficient.

SessionDate

SessionDate reference

Calendar date without a time or time zone.

yearInt: Four-digit calendar year, for example 2030.
monthInt: Month of the year, from 1 to 12.
dayInt: Day of the month, from 1 to 31 as permitted by the month.

SessionTimestamp

SessionTimestamp reference

Instant / Date

Type alias: kotlin.time.Instant on Android; Foundation Date in Swift.

SupportedPaymentMethod

SupportedPaymentMethod reference

Payment method enabled for the current session. Device wallet availability requires a separate availability check.

typeString: Payment-method identifier used to choose the corresponding payment method, for example CARD or APPLE_PAY.
nameString: Display name of the payment method.
urlString: URL of the payment-method image for your checkout UI.

StoredPaymentMethod

StoredPaymentMethod reference

Saved payment method available to the session’s customer.

idString: Unique ID used to pay with, delete, or calculate a fee for this stored method.
displayTextString: Shopper-friendly identification, such as a masked card number.
typeString: Payment-method type, for example CARD.
subTypeStringnullable: More specific payment-method type, such as the card scheme. Null when not supplied.
customerIdStringnullable: Your customer ID associated with the stored payment method.
expiryStringnullable: Expiry date in YYYY-MM-DD format. For a card, this is the last day of its expiration month.
createdAtString: Timestamp when the payment method was stored.
accountUpdatesEnabledBoolean: Whether the payment method is enrolled in account updates to keep stored card details current when a replacement is issued.
feeLong: Calculated fee for the session amount, in minor units of the session currency.

StoredPaymentMethodData

StoredPaymentMethodData reference

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

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

StoredPaymentMethodFeeData

StoredPaymentMethodFeeData reference

Stored payment method and base amount for a fee calculation.

paymentMethodIdString: ID of the stored payment method whose fee should be calculated.
amountLongoptionalnullable: Base amount in minor units of the session currency. Uses the session amount when omitted or null.

StoredPaymentMethodFee

StoredPaymentMethodFee reference

Result of calculating a stored payment method’s fee.

feeLong: Fee in minor units of the session currency for the requested base amount. Zero means no fee.

ClientMessageData

ClientMessageData reference

Optional code and language overrides when requesting a shopper-facing message.

ePayCodeStringoptionalnullable: ePay result or error code to translate. When omitted, uses the latest code retained by the SDK.
langStringoptionalnullable: Language code, for example da or en. When omitted, uses the language retained from field configuration or a previous language selection.

ClientMessage

ClientMessage reference

Localized message associated with an ePay result or error code.

textString: Shopper-facing message. May be empty when no message is available and may contain newlines and **bold** markers.

AgeVerification

AgeVerification reference

Age-verification flow for the initialized session. Reinitializing the SDK invalidates this object.

minimumAgeInt

Required age in years. Zero means the session has no configured age requirement.

statusAgeVerificationStatus

Latest known verification status for this session.

Values · AgeVerificationStatus

Known age-verification status for the session.

NotRequestedvalue: No minimum age was configured for the session and verification has not been requested.
NotVerifiedvalue: The customer has not been verified as meeting the required age.
Verifiedvalue: The customer has been verified as meeting the required age.

start()

Start age verification and wait for its result, even if a previous check was verified. The SDK must be ready and no payment or other verification flow may be active.

Kotlin suspend · Swift async throws

Returns AgeVerificationResult

Properties · AgeVerificationResult

Outcome returned when an age-verification flow finishes.

statusAgeVerificationStatus

Verified when the customer meets the required age; otherwise NotVerified.

Values · AgeVerificationStatus

Known age-verification status for the session.

NotRequestedvalue: No minimum age was configured for the session and verification has not been requested.
NotVerifiedvalue: The customer has not been verified as meeting the required age.
Verifiedvalue: The customer has been verified as meeting the required age.

Throws EpayException. See error handling.

AgeVerificationResult

AgeVerificationResult reference

Outcome returned when an age-verification flow finishes.

statusAgeVerificationStatus

Verified when the customer meets the required age; otherwise NotVerified.

Values · AgeVerificationStatus

Known age-verification status for the session.

NotRequestedvalue: No minimum age was configured for the session and verification has not been requested.
NotVerifiedvalue: The customer has not been verified as meeting the required age.
Verifiedvalue: The customer has been verified as meeting the required age.

AgeVerificationStatus

AgeVerificationStatus reference

Known age-verification status for the session.

NotRequestedvalue: No minimum age was configured for the session and verification has not been requested.
NotVerifiedvalue: The customer has not been verified as meeting the required age.
Verifiedvalue: The customer has been verified as meeting the required age.

Wallets

GooglePayData

GooglePayData reference

Options for checking Google Pay availability on Android.

optionsTransactionOptionsoptional

Transaction options for the payment you intend to offer. Omit to use the session’s default payment options.

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

ApplePayData

ApplePayData reference

Merchant configuration and options for checking Apple Pay availability on iOS.

merchantIdentifierString

Apple merchant identifier matching the app’s Apple Pay entitlement.

optionsTransactionOptionsoptional

Transaction options for the payment you intend to offer. Omit to use the session’s default payment options.

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

ApplePayPaymentData

ApplePayPaymentData reference

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.

WalletAvailability

WalletAvailability reference

Result of checking whether a device wallet can be offered for the current session.

isAvailableBoolean: Whether this wallet is available for the current session and device.

Events and decisions

SdkEvents

SdkEvents reference

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.

TransactionAccepted

TransactionAccepted reference

Notification that a transaction was accepted.

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

TransactionDeclined

TransactionDeclined reference

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.

FeeUpdated

FeeUpdated reference

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.

PaymentCancel

PaymentCancel reference

Notification that a payment flow was cancelled.

paymentMethodTypeString: Type of payment method whose flow was cancelled.

ClientRedirect

ClientRedirect reference

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.

SdkError

SdkError reference

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.

Surcharge

Surcharge reference

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%.

SurchargeDecision

SurchargeDecision reference

Response to a surcharge-confirmation callback. Call either method on the UI thread; only the first decision applies.

confirm(): Accept the surcharge on the UI thread.
Returns Unit / Void
cancel(): Request cancellation on the UI thread. Wait for the SDK outcome. Only the first decision applies.
Returns Unit / Void

SDK and lifecycleCopy Anchor Link

Payments and outcomesCopy Anchor Link

Card fieldsCopy Anchor Link

Session servicesCopy Anchor Link

WalletsCopy Anchor Link

Events and decisionsCopy Anchor Link

On this page

SDK and lifecycle

Payments and outcomes

Card fields

Session services

Wallets

Events and decisions