Wallets and app returns
Set up Apple Pay, Google Pay, PayPal, and returns from payment apps.
Offer wallets only after SDK initialization and a successful device availability check. Keep the owning SDK and screen alive throughout authorization and app switching.
Native wallets
Google Pay
Google Play services and a suitable account/device are required. No Activity-result forwarding is required with the standard host.
val payment = sdk.payment().apply { handlers.onUpdate = { attempt -> renderPayment(attempt) }}lifecycleScope.launch { try { val availability = sdk.checkGooglePayAvailability(GooglePayData(payment.options)) googlePayButton.isVisible = availability.isAvailable } catch (error: EpayException) { googlePayButton.isVisible = false showError(error.message) }}googlePayButton.setOnClickListener { payment.createGooglePayTransaction() }checkGooglePayAvailability(data) returns WalletAvailability.isAvailable. Availability permits adding a card and remains advisory: launching payment can still fail. Google Pay is unavailable on iOS.
The payment environment is determined by ePay's configuration; there is no app-side environment override. Test-mode processing requires the corresponding test configuration with ePay.
Do not cache availability across sessions. Recheck if payment configuration changes. Authorization, wallet dismissal, and approval are not payment success; continue observing the payment attempt. Authorization can time out after 25 seconds, and an unresolved submission must not be retried automatically.
App returns
The SDK resumes a matching payment when the shopper returns to your app. Do not start another payment or infer success from the return URL.
The standard host registers an app-specific return scheme and forwards returns automatically. No Activity intent forwarding is needed with the default configuration.
If you override PaymentHostConfig.appReturnUrl or supply an HTTPS appUniversalLink, register the matching scheme or App Link in your application and forward incoming URLs to sdk.handleReturnUrl(url) on the UI thread.
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
#RRGGBBstring; defaults to#FFFFFF. Invalid formats throw immediately.
Set return configuration before creating the host. handleReturnUrl returns true for a consumed return and false for unrelated, stale, or duplicate URLs. Forward both supported return mechanisms to the same retained SDK instance.
Redirect screens are presented and closed by the SDK. Do not open URLs received through events.clientRedirect yourself. Shoppers complete these flows using their presented controls; there is no SDK-provided close, back, or swipe dismissal.
If the app process or checkout is destroyed, automatic payment recovery is not available. Retrieve your backend order status before allowing another payment.
PayPal
Android includes the PayPal adapter. After initialization, start payment from your PayPal button:
val payment = sdk.payment().apply { handlers.onUpdate = { attempt -> renderPayment(attempt) }}val attempt = payment.createPayPalTransaction()The default host supplies return handling automatically. For custom HTTPS returns, register and forward App Links for the /paypal/* descendants. For a custom-scheme appReturnUrl, also register and forward ://x-callback-url/paypal-sdk/paypal-checkout and descendant paths for that scheme.
PayPal approval may open the PayPal app or its browser experience. Both purchases and subscription setup without a purchase are supported. Approval alone leaves the attempt processing until an ePay outcome is reported. Closing approval may require an outcome check; pending or unresolvable submitted payments remain OutcomeUnknown. Keep observing the attempt and never retry solely because the approval screen closed.