Session services
Read checkout data, use stored payment methods, show client messages, and verify age.
Call session services after initialize completes. Query failures throw EpayException; handle them at the UI boundary. Kotlin examples run inside a coroutine and Swift asynchronous examples inside an async context.
Session data
sdk.sessionData() returns the read-only initialization snapshot. It is available after initialization and inside the Ready callback. Before readiness, after failure, or after disposal it throws SDK_NOT_READY. Reinitialization replaces the snapshot.
val data = sdk.sessionData()showTotal(data.session.amount, data.session.currency)showSaveCard(data.canStorePaymentMethod)Session data reference
- 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, orNO_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
1095for 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, orEXPIRED. 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.Instanton Android and FoundationDatein 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
VISAandMASTERCARD. 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:
SCHEDULEDfor payments at a fixed interval orUNSCHEDULEDfor payments as needed. - intervalSessionSubscriptionIntervalnullable
- Billing interval for a scheduled subscription. Null when no interval was supplied.
- expiryDateSessionDatenullable
- Agreement expiry date supplied for authentication. ePay does not reject later payments solely because this date has passed.
- amountLongnullable
- Recurring amount in minor units. When null, the transaction amount is used.
Throws EpayException. See error handling.
Session reference, textOnStatement, descriptor, customerInfo, and allowedPaymentMethods may be absent. Amounts use minor units. Session timestamps are kotlin.time.Instant on Android and Foundation Date in Swift. Subscription expiryDate is an optional SessionDate with integer year, month, and day, without a timezone.
This snapshot is not a live payment status or fee total. Observe attempts, fee events, and the age-verification object for changes. Setting payment options does not change the snapshot's session amount.
Available payment methods
getSupportedPaymentMethodTypes() returns a list of SupportedPaymentMethod, each with type (such as CARD), name, and url for its image. An empty list is valid.
val methods = sdk.getSupportedPaymentMethodTypes()showPaymentMethods(methods)Available payment methods reference
- 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.
Throws EpayException. See error handling.
Render only methods supported by your checkout. Identifiers are strings and may include future values. Check wallet availability separately.
Stored payment methods
Stored methods belong to the session's customer. Card-entry fields are not required to list or pay with them.
StoredPaymentMethod exposes id, displayText, type, nullable subType, customerId, and expiry, plus createdAt, accountUpdatesEnabled, and fee. expiry is a date string and createdAt a timestamp string. Types and subtypes are extensible strings. The initial fee uses the session amount.
Checkout with a saved method
List the methods, let the shopper select one, calculate its fee, and update the displayed total. When the shopper confirms, start payment using the selected ID. Leave the transaction amount unset for an ordinary session.
val methods = sdk.getStoredPaymentMethods()showMethods(methods)// After selection:val fee = sdk.calculateStoredPaymentMethodFee(StoredPaymentMethodFeeData(selectedId))updateTotal(baseAmount + fee.fee)val payment = sdk.payment().apply { handlers.onUpdate = { attempt -> renderPayment(attempt) }}// In the pay-button handler:payment.createStoredPaymentMethodTransaction(StoredPaymentMethodData(selectedId))// Separate delete action; only remove from the UI after success:sdk.deleteStoredPaymentMethod(StoredPaymentMethodData(selectedId))removeMethod(selectedId)Stored payment method operations reference
- 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-DDformat. 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.
- 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
onUpdatefor 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
canRetrybefore 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
canRetryis true. - Cancelledvalue
- The flow was cancelled; check
canRetrybefore offering another attempt. - Failedvalue
- The attempt could not complete because of an error. Show the error and retry only when
canRetryand 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.
- 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.5for 2.5%.
- metadataPaymentAttemptMetadata
- Additional information about the authorization history of this attempt.
Properties · PaymentAttemptMetadata
Additional authorization history for the payment attempt.
- onUpdateCallback<PaymentAttempt>nullable
- Receives the current attempt immediately, then subsequent updates on the UI thread.
For a dynamic-amount session, pass the same base amount to StoredPaymentMethodFeeData(paymentMethodId, amount) and the payment options. Do not add the fee to the submitted amount. Recalculate when selection or amount changes. Fee calculation neither changes the transaction amount nor emits feeUpdated.
Shopper-facing messages
getClientMessage() returns ClientMessage.text for the current session. Use getClientMessage(data) with optional ClientMessageData.ePayCode and lang to select a particular message or language.
val message = sdk.getClientMessage(ClientMessageData().apply { lang = "da"})showMessage(message.text)Shopper-facing messages reference
- 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.
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.
The text may be empty and may contain newlines and **bold** markers. Render it in your app's UI. An omitted language uses the latest preference from fields configuration, a successful setLanguage, or an explicit message query. An omitted code uses the latest SDK return code when available. A new attempt clears the return code; reinitialization clears both defaults. Messages do not change payment state.
Age verification
sdk.ageVerification() returns a session-bound AgeVerification object while ready. Its minimumAge is the session requirement (zero means no verification requested). Its current status is NotRequested, NotVerified, or Verified.
start() presents the verification flow and returns AgeVerificationResult.status. Calling it starts a flow even when status is already verified or verification was not requested, so decide whether it is needed before offering the action.
val verification = sdk.ageVerification()val result = verification.start()showVerificationStatus(result.status, verification.minimumAge)Age verification reference
- 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
Verifiedwhen the customer meets the required age; otherwiseNotVerified.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.
Throws EpayException. See error handling.
A successful return reports Verified; an unsuccessful return reports NotVerified. Start or presentation failures throw without replacing the previous status. Verification cannot overlap another verification or active payment flow.
Reinitialization invalidates old verification objects. Cancelling the caller's await does not dismiss an active verification flow; its eventual result still updates the object. Verification does not emit payment accepted/declined events or update the sessionData snapshot. Server-side processing continues to enforce age requirements.