Mobile: Android

First, you should obtain and set up the ProcessOut Android SDK in your project by following the instructions for Android.

Add dependencies to your build.gradle configuration:

// Prebuilt customizable UI to handle payment flows.
implementation("com.processout:processout-android-ui:<version>")

// (Optional) Integration with Checkout 3DS SDK.
// Alternatively you can use your own implementation of PO3DSService.
implementation("com.processout:processout-android-checkout-3ds:<version>")

SDK provides PODynamicCheckoutLauncher to start the activity.

// 1) Initialize the launcher in the onCreate() method of your Activity or Fragment.

private lateinit var launcher: PODynamicCheckoutLauncher

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    launcher = PODynamicCheckoutLauncher.create(
        from = this,
        threeDSService = object : PO3DSService {},
        delegate = object : PODynamicCheckoutDelegate {},
        callback = { result ->
            // Handle payment result.
        }
    )
}

// 2) Launch the activity.

launcher.launch(
    PODynamicCheckoutConfiguration(
        invoiceRequest = POInvoiceRequest(
            invoiceId = "iv_xyz",
            clientSecret = "secret_xyz"
        )
    )
)

Follow Checkout 3DS SDK integration guide for Android to initialize threeDSService or alternatively provide your own implementation of PO3DSService using preferred 3DS SDK.

Configuration

The launcher accepts a configuration object PODynamicCheckoutConfiguration that allows you to customize the displayed information and the behavior of the checkout screen.

The only mandatory parameter is the Invoice Request that includes Invoice ID you wish to authorize and Client Secret if you want customer's saved payment methods to be included. Other optional parameters include:

• Card payment configuration.
• Google Pay configuration.
• Alternative payment configuration.
• Buttons customization.
• Success screen customization.
• Style customization.

Example usage:

launcher.launch(
    PODynamicCheckoutConfiguration(
        invoiceRequest = POInvoiceRequest(
            invoiceId = "iv_xyz",
            clientSecret = "secret_xyz"
        ),
        googlePay = GooglePayConfiguration(
            environment = Environment.TEST,
            merchantName = "Example"
        ),
        alternativePayment = AlternativePaymentConfiguration(
            returnUrl = "your.application.id://processout/return"
        ),
        submitButtonText = "Pay"
    )
)

Card payment configuration

Card payment settings are primarily set via the ProcessOut dashboard when creating a dynamic checkout configuration. Additional settings within the SDK include:

• defaultAddress: Set this if you know the customer's billing address in advance.

• attachDefaultsToPaymentMethod: Property can be set to true if you want the implementation to fill in any fields the user didn't enter with defaults. This is especially useful in combination with the never collection mode (configured in dashboard) to set an address during card payment without allowing the user to change it.

Example usage:

val cardConfiguration = CardConfiguration(
    billingAddress = BillingAddressConfiguration(
        defaultAddress = POContact(
            zip = "M44 5YN",
            countryCode = "GB"
        ),
        attachDefaultsToPaymentMethod = false
    ),
    metadata = emptyMap()
)

PODynamicCheckoutConfiguration(card = cardConfiguration)

Google Pay configuration

Google Pay settings are set via the ProcessOut dashboard when creating a dynamic checkout configuration. Additional settings within the SDK are corresponding to PaymentDataRequest of the Google Pay API.

Example usage:

val googlePayConfiguration = GooglePayConfiguration(
    environment = Environment.TEST,
    merchantName = "Example",
    totalPriceLabel = "Total price",
    totalPriceStatus = TotalPriceStatus.FINAL,
    checkoutOption = CheckoutOption.DEFAULT,
    emailRequired = false,
    billingAddress = null,
    shippingAddress = null
)

PODynamicCheckoutConfiguration(googlePay = googlePayConfiguration)

Alternative payment configuration

With web-based alternative payment methods (APMs) the SDK handles a deep link to return back to your app after authorization in the following format: your.application.id://processout/return. It is required to provide this deep link on the backend as return_url when creating invoice and pass the same value to dynamic checkout configuration.

Other options for native APMs include:

• Limiting the number of options displayed inline for single-choice parameters.
• Changing the maximum duration the implementation will wait for payment capture.
• Showing progress indicator after specified delay.
• Enabling the confirmation button that will start payment capture when pressed.
• Modifying the visual and behavioral properties of the cancel button.
• Specifying configuration for barcode customer action.

Example usage:

val alternativePaymentConfiguration = AlternativePaymentConfiguration(
    returnUrl = "your.application.id://processout/return",
    inlineSingleSelectValuesLimit = 5,
    barcode = POBarcodeConfiguration(
        saveActionText = "Save QR Code"
    ),
    paymentConfirmation = PaymentConfirmationConfiguration(
        timeoutSeconds = 3 * 60,
        showProgressIndicatorAfterSeconds = 10,
        confirmButton = ConfirmButton(
            text = "I've paid"
        ),
        cancelButton = CancelButton(
            text = "Cancel",
            disabledForSeconds = 10
        )
    )
)

PODynamicCheckoutConfiguration(alternativePayment = alternativePaymentConfiguration)

Style customization

You can pass a custom style to the dynamic checkout configuration. Customizing the UI allows you to match the checkout experience with your app's design guidelines and user expectations effectively. Check documentation for customization options.

Example usage:

val customStyle = PODynamicCheckoutConfiguration.Style(
    backgroundColorResId = R.color.background,
    ...
)

PODynamicCheckoutConfiguration(style = customStyle)

Delegate

PODynamicCheckoutDelegate is a mandatory parameter when creating PODynamicCheckoutLauncher that facilitates interaction and decision-making throughout the checkout process. Please provide your own implementation of a delegate interface to utilize the following features:

• Events: Monitor events such as payment method selection and other interactions within the checkout flow, card tokenization and native alternative payments.
• Failure Recovery: Implementation may ask to create a new invoice when the current one has been invalidated due to the payment failure or invalid state.
• Invoice Authorization: Allows to alter POInvoiceAuthorizationRequest before authorization.
• Preferred Card Scheme: When both scheme and co-scheme are available, determine which one to prefer for card tokenization.
• Default Parameter Values: Provide default values for parameters that the user is expected to fill in during the checkout process.

API bindings

For a highly customizable approach, you can leverage our API bindings directly. Dynamic checkout payment methods are included in the invoice, here's how to access them:

coroutineScope.launch {
    ProcessOut.instance.invoices.invoice(
        request = POInvoiceRequest(invoiceId = "iv_xyz")
    ).onSuccess { invoice ->
        // Inspect `invoice.paymentMethods`.
    }.onFailure { failure ->
        // Handle failure.
    }
}

This approach gives you flexibility in how you integrate and display payment methods based on the specific requirements of your checkout process, enhancing user experience and customization capabilities.

Check PODynamicCheckoutPaymentMethod for the comprehensive list of all possible payment methods supported by ProcessOut for dynamic checkout.