Payments and outcomes

After initialization, create a Payment using sdk.payment(). Retain it for the checkout and configure its options and handlers before the shopper starts a payment.

Start a payment

val payment = sdk.payment().apply {    options.note = "Order 123"    options.setStorageConsent(saveCard)    handlers.onUpdate = { attempt -> renderPayment(attempt) }}// In the pay-button handler, after card fields are ready and valid:val attempt = payment.createCardTransaction()

Android demo checkout with a saved Visa card, other payment methods, and a total including the selected card’s fee — Payment selection in the Android demo. Your app controls the layout and displays the SDK’s available methods and fees.

Each creation method returns a PaymentAttempt. Configure options and handlers before starting, and use the callback’s attempt argument to read updates.

Only one attempt can be active. Card fields update paymentButtonState automatically during processing and after outcomes. Disable other payment actions while processing. Recreate Payment for another checkout so previous shopper choices are not carried over.

Transaction options

// For a dynamic-amount session, set the base amount in minor units.payment.options.amount = 12500payment.options.note = "Order 123"payment.options.setStorageConsent(saveCard)

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

Unset values preserve session defaults; explicit zero and false remain explicit values. In Swift, use KotlinLong(value: baseAmount) when assigning a dynamic amount. Supply the base amount without adding a surcharge.

Observe the outcome

Set payment.handlers.onUpdate before starting, or use attempt.onUpdate to observe an existing attempt. Clear it with null / nil to stop observing.

payment.handlers.onUpdate = { attempt ->    // Render progress or the outcome from the latest state.    showPaymentState(attempt.state)    // Other payment methods use the attempt to decide whether to offer retry.    retryButton.isVisible = attempt.canRetry}

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.

OutcomeUnknown means retry safety cannot be established. It is neither confirmation of submission nor a decline. A later correlated outcome can resolve it; there is no automatic general-purpose status polling or replay. Accepted payments, exhausted declines, and uncertain outcomes block new starts in the session.

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.

A shopper can retry authorization within an open wallet. Closing it after a retryable decline reports Cancelled with hadDeclinedAuthorization = true. An unresolved submission still reports OutcomeUnknown. Disposing the SDK stops observation; it does not establish server cancellation.

Fees and surcharge confirmation

Register fee callbacks before starting payments. Amounts are in session-currency minor units. feeUpdated.fee is added to your base total; zero clears the fee. A surcharge's updatedAmount already includes its fee.

sdk.events.feeUpdated = { event -> updateTotal(baseAmount + event.fee) }sdk.events.confirmSurcharge = { surcharge, decision ->    showFeeDialog(        surcharge.updatedAmount,        onConfirm = { decision.confirm() },        onCancel = { decision.cancel() }    )}

Without a confirmation handler, surcharges are automatically accepted. With a handler, processing waits for your decision. Call confirm() or cancel() on the UI thread; only the first response applies. Cancellation is complete only when reported by the SDK. A decision failure is not permission to retry.

Surcharge includes paymentMethodType, optional paymentMethodSubType, originalAmount, updatedAmount, fee, minimumFee, flatFee, and percentage (for example, 2.5 means 2.5%).

Event reference

Use attempt updates for the payment-result UI and events for supplementary behavior.

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.

Callbacks run on the UI thread. Redirect load errors do not prove a payment failed. Keep observing the attempt and use your backend if status remains uncertain.

Query errors

Initialization and query methods throw EpayException, with errorCode and message. Payment creation instead reports errors on the returned attempt.

Catch EpayException at the UI boundary.

try {    val methods = sdk.getStoredPaymentMethods()    showMethods(methods)} catch (error: EpayException) {    showError(error.message)}

Session replacement or disposal cancels pending queries.

Payment method reference

All methods below belong to Payment, return PaymentAttempt, and use its shared options and handlers. Offer methods enabled for the session and supported by your integration; session availability is not a guarantee of device readiness.

Payment methods reference

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.

Swift uses the data: argument label for methods with a data object. The SDK presents redirects and authorization screens; observe the attempt for the outcome.

Start a paymentCopy Anchor Link

Transaction optionsCopy Anchor Link

Observe the outcomeCopy Anchor Link

Fees and surcharge confirmationCopy Anchor Link

Event referenceCopy Anchor Link

Query errorsCopy Anchor Link

Payment method referenceCopy Anchor Link

On this page

Start a payment

Transaction options

Observe the outcome

Fees and surcharge confirmation

Event reference

Query errors

Payment method reference