Accept payments via Revolut Pay - Android

Welcome to the implementation guide for Revolut Pay on Android! This page provides a comprehensive walkthrough for integrating Revolut Pay into your Android application.

How it works​

From an implementation perspective, integrating Revolut Pay into your Android app with the Revolut Pay SDK involves the following components:

1. Server-side: An endpoint on your server to securely create an order with the Revolut Merchant API.
2. Client-side: Your Android app uses the Revolut Pay SDK to display the Revolut Pay button, collect payment details, and handle the user flow.
3. Endpoint for webhooks: Optionally, you can set up an endpoint to receive webhook events from the Merchant API to track the payment lifecycle. For more information, see: Use webhooks to keep track of the payment lifecycle.

The SDK automatically adapts the user experience based on whether the customer has the Revolut app installed, either by switching to the app or by presenting a secure in-app web flow, requiring no conditional logic in your implementation.

1. The customer goes to the checkout screen in your app.
2. The customer taps the Revolut Pay button.
3. Your app uses your server endpoint to create an order and obtains the order token via the Merchant API: Create an order.
4. The Revolut Pay SDK opens the Revolut app, where they review and authorise the payment.
5. The SDK processes the payment and presents the payment result to the customer.
6. Once the payment is successful, your customer is redirected to your app.
7. Optionally, your server receives webhook notifications about each event you're subscribed to. For more information, see: Use webhooks to keep track of the payment lifecycle.

Implementation overview​

Check the following high-level procedure of implementing Revolut Pay in your Android app.

1. Set up an endpoint for creating orders
2. Configure your Android project
3. Initialise the SDK
4. Implement the payment flow
5. Verify payments on your backend

Before you begin​

Before you start this tutorial, ensure you have completed the following steps:

• Get started: 1. Apply for a Merchant account
• Get started: 2. Generate the API keys

Implement Revolut Pay on Android​

1. Set up an endpoint for creating orders​

When your customer enters the checkout screen, your app needs a unique, single-use token that represents the order. This token can only be created on your server by making a secure call to the Revolut Merchant API.

This server-side endpoint is a mandatory security requirement. Your secret API key must never be exposed in your Android application.

When your checkout screen loads, your app should call this endpoint to pre-fetch the order token. Your endpoint is responsible for:

1. Receiving the checkout details (e.g., amount, currency) from your client-side request.
2. Securely calling the Merchant API: Create an order endpoint with the checkout details.
3. Receiving the order object, including the public token, in the API response.
4. Returning the token from the response to your app.

Your app will then store this token. When the customer taps the Revolut Pay button, this token will be passed to the SDK to start the payment process, as shown in a later step.

Below is an example of the JSON response your endpoint will receive from the Merchant API after successfully creating an order. The crucial field to extract and return to your app is the token.

{
  "id": "6516e61c-d279-a454-a837-bc52ce55ed49",
  "token": "0adc0e3c-ab44-4f33-bcc0-534ded7354ce",
  "type": "payment",
  "state": "pending",
  "created_at": "2023-09-29T14:58:36.079398Z",
  "updated_at": "2023-09-29T14:58:36.079398Z",
  "amount": 1000,
  "currency": "GBP",
  "outstanding_amount": 1000,
  "capture_mode": "automatic",
  "checkout_url": "https://checkout.revolut.com/payment-link/0adc0e3c-ab44-4f33-bcc0-534ded7354ce",
  "enforce_challenge": "automatic"
}

2. Configure your Android project​

This section covers the one-time setup tasks required to prepare your Android project for the SDK.

2.1 Install the SDK​

1. Add the mavenCentral() repository to your project-level build.gradle file if it's not already there:

   allprojects {
       repositories {
           mavenCentral()
       }
   }
   

2. Add the Revolut Pay Lite SDK dependency to your module-level build.gradle file:

   implementation 'com.revolut.payments:revolutpaylite:3.0.0'
   

3. Sync your project with the Gradle files.

2.2 Configure the App Manifest​

You need to declare necessary permissions and app-querying capabilities in your AndroidManifest.xml.

1. Add internet permission: The SDK required network access.

   <uses-permission android:name="android.permission.INTERNET" />
   

2. Declare Revolut app query: To allow the SDK to check if the Revolut app is installed, add the <queries> element.

   <queries>
       <package android:name="com.revolut.revolut" />
   </queries>
   

2.3 Set up a deep link for redirection​

A deep link is required for the Revolut app to redirect the user back to your app after payment authorisation.

In your AndroidManifest.xml, add an <intent-filter> to the activity that will handle the result.

<activity
    android:name=".MainActivity"
    android:launchMode="singleTop">
    <intent-filter>
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <data
            android:host="payment-return"
            android:scheme="myapp" />
    </intent-filter>
</activity>

3. Initialise the SDK​

In your application's entry point (e.g., the onCreate method of your Application class), initialise the Revolut Pay SDK with your public API key.

import com.revolut.payments.RevolutPaymentsSDK

class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        RevolutPaymentsSDK.configure(
            RevolutPaymentsSDK.Configuration(
                merchantPublicKey = "<yourPublicApiKey>",
                environment = RevolutPaymentsSDK.Environment.SANDBOX // Or .PRODUCTION
            )
        )
    }
}

This configures the SDK with the environment for testing or live payments. The deep link URI will be provided later when creating payment orders.

4. Implement the payment flow​

Now, you will add the Revolut Pay button to your UI and connect it to your backend to handle payments.

4.1 Add the Revolut Pay button​

You can add the Revolut Pay button to your checkout screen either programmatically or via XML layout.

Create an instance of the button in your activity or fragment code.

import com.revolut.payments.RevolutPaymentsSDK
import com.revolut.revolutpay.api.revolutPay
import com.revolut.revolutpay.api.button.ButtonParams
import com.revolut.revolutpay.api.button.Radius
import com.revolut.revolutpay.api.button.Size
import com.revolut.revolutpay.api.button.Variant
import com.revolut.revolutpay.api.button.VariantModes
import com.revolut.revolutpay.api.button.BoxText

// ...

val buttonParams = ButtonParams(
    buttonSize = Size.LARGE,
    radius = Radius.MEDIUM,
    variantModes = VariantModes(lightMode = Variant.DARK, darkMode = Variant.LIGHT),
    boxText = BoxText.NONE
)

val revolutPayButton = RevolutPaymentsSDK.revolutPay.provideButton(
    context = this,
    params = buttonParams
)

// Add the button to your view hierarchy
your_layout.addView(revolutPayButton)

4.2 Set up payment controller and button interaction​

Now, let's wire everything up. You'll create a payment controller to manage the payment process and then configure your Revolut Pay button to use this controller when tapped.

Create the payment controller​

First, create an instance of the paymentController. This component is responsible for launching the payment flow and returning the final result (success, failure, or user cancellation) to your app.

import com.revolut.payments.RevolutPaymentsSDK
import com.revolut.revolutpay.api.PaymentResult
import com.revolut.revolutpay.api.order.OrderParams
import com.revolut.revolutpay.api.revolutPay
import androidx.core.net.toUri

// Create payment controller in your Activity or Fragment
private val paymentController = RevolutPaymentsSDK.revolutPay.createController(this) { paymentResult ->
    when (paymentResult) {
        is PaymentResult.Success -> {
            // Payment successful - update your UI
            showSuccessMessage()
        }
        is PaymentResult.UserAbandonedPayment -> {
            // User cancelled the payment
            showCancelledMessage()
        }
        is PaymentResult.Failure -> {
            // Payment failed - show error and log details
            showErrorMessage()
            Log.e("RevolutPay", "Payment failed", paymentResult.exception)
        }
    }
}

Configure the Revolut Pay button​

With the controller ready, you can configure the button's behaviour, also within onCreate() or onViewCreated(). This involves two main actions:

1. Binding the payment state: This links the button's appearance (e.g., showing a loading spinner) to the controller's current state automatically.
2. Setting a click listener: This defines the action to take when the user taps the button—fetching the order token from your backend and starting the payment.

// In your Activity/Fragment's onCreate() or onViewCreated()

// 1. Bind the button's loading state to payment controller's state
revolutPayButton.bindPaymentState(paymentController, this)

// 2. Set the button's click listener to start the payment
revolutPayButton.setOnClickListener {
    // Show a loading indicator on the button
    revolutPayButton.showBlockingLoading(true)
    
    viewLifecycleOwner.lifecycleScope.launch {
        try {
            // Call your backend to get the order token
            val orderToken = fetchOrderTokenFromBackend()
            
            // Start the payment with the token (and other order details)
            paymentController.pay(
                OrderParams(
                    orderToken = orderToken,
                    returnUri = "myapp://payment-return".toUri(), // Must match your deep link from step 2.3
                    requestShipping = false, // Set to true for Fast checkout
                    savePaymentMethodForMerchant = false, // Set to true for MIT
                    customer = null // Optional customer details
                )
            )
        } catch (e: Exception) {
            // Handle any errors during the token fetch
            revolutPayButton.showBlockingLoading(false)
            showErrorMessage()
        }
    }
}

Implement fetchOrderTokenFromBackend()​

In the code above, fetchOrderTokenFromBackend() is a placeholder for a function you must create. THis function's job is to make a network request to the server endpoint you built in Step 1. It sends the order details (like amount and currency) to your server and gets the unique order token in return.

Because this is a network operation it must performed off the main UI thread. The example uses lifecycleScope.launch (a Kotlin Coroutine) to handle this, which is the recommended approach.

4.3 Handle deep link redirect​

After the customer authorises the payment (either in the Revolut app or the web flow), they are redirected back to your app using the deep link you configured in Step 2.3.

You need to catch this redirect in the Activity you configured with the <intent-filter>. To do this, override the onNewIntent() method and pass the incoming URI to the Revolut Pay SDK for processing.

import com.revolut.payments.RevolutPaymentsSDK
import com.revolut.revolutpay.api.revolutPay

override fun onNewIntent(intent: Intent?) {
    super.onNewIntent(intent)
    intent?.data?.let { uri ->
        // Pass the deep link URI to the Revolut Pay SDK for processing
        RevolutPaymentsSDK.revolutPay.handle(uri)
    }
}

The SDK processes this URI internally. You don't need to parse it yourself. The final PaymentResult is automatically delivered to the paymentController callback you configured in Step 4.2.

5. Verify payments on your backend​

Set up a webhook listener on your server. Always wait for a successful payment event webhook (e.g., ORDER_COMPLETED) before capturing funds, shipping goods, or granting access to services.

Advanced features​

You can enable additional features to enhance the customer experience and boost your conversion rates.

Fast checkout and Merchant Initiated Transactions (MIT)​

You can configure the payment session to either collect customer shipping details or save their payment method future use. These options are configured in the OrderParams when you initiate the payment.

• Fast checkout: To collect shipping details via Revolut Pay, set requestShipping = true in your OrderParams. This requires your backend to support the Fast checkout flow. See the Fast Checkout guide for details.
• Merchant Initiated Transactions (MIT): To save a customer's payment method for future use (e.g., subscriptions), set savePaymentMethodForMerchant = true in your OrderParams. See our guide on charging a saved payment method for details.

Promotional banner​

You can add a promotional banner to your order confirmation or "thank you" screen to offer rewards to new customers who sign up for a Revolut account after checkout.

To add the banner, call the RevolutPaymentsSDK.revolutPay.providePromotionalBannerWidget(context: Context, params: PromoBannerParams) method. This requires PromoBannerParams, which includes the transactionId from your server.

// In your order confirmation Activity (e.g., OrderConfirmationActivity.kt)

import com.revolut.revolutpay.api.promobanner.Currency
import com.revolut.revolutpay.api.promobanner.Customer
import com.revolut.revolutpay.api.promobanner.DateOfBirth
import com.revolut.revolutpay.api.promobanner.PromoBannerParams
import com.revolut.revolutpay.api.promobanner.CountryCode
import com.revolut.payments.RevolutPaymentsSDK
import com.revolut.revolutpay.api.revolutPay

class OrderConfirmationActivity : AppCompatActivity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_order_confirmation)

        // 1. Get the order token you passed to this activity after a successful payment.
        // This is the `token` from the order object you received from your server in Step 1.
        val orderIdFromServer = intent.getStringExtra("ORDER_ID") ?: ""

        // 2. Define the parameters for the banner.
        val bannerParams = PromoBannerParams(
            transactionId = orderIdFromServer,
            paymentAmount = 1000, // Amount in the smallest currency unit (e.g., cents)
            currency = Currency.EUR,
            customer = Customer(
                name = "Example Customer",
                email = "example.customer@email.com",
                phone = "+441234567890",
                dateOfBirth = DateOfBirth(_day = 1, _month = 2, _year = 2000),
                country = CountryCode.GB,
            )
        )

        // 3. Create the banner widget.
        val promotionalBanner = RevolutPaymentsSDK.revolutPay.providePromotionalBannerWidget(
            context = this,
            params = bannerParams
        )

        // 4. Add the banner to your layout.
        // Assuming you have a LinearLayout with id 'banner_container' in your XML file.
        val bannerContainer = findViewById<LinearLayout>(R.id.banner_container)
        bannerContainer.addView(promotionalBanner)
    }
}

Customise the banner's appearance (Optional)​

To apply a custom theme to the banner, first define a style in a resource file:

<style name="RevolutPay_RevolutPayBanner">
    <item name="revolutPay_ColorAccent">#0666EB</item>
    <item name="revolutPay_ColorBackground">#F7F7F7</item>
    <item name="revolutPay_BannerCornerRadius">12dp</item>
    <item name="revolutPay_ComponentCornerRadius">12dp</item>
    <item name="revolutPay_StrokeWidth">0dp</item>
    <item name="revolutPay_StrokeColor">#BBC4CD</item>
</style>

Then, reference this theme when creating the widget:

val promotionalBanner = RevolutPaymentsSDK.revolutPay.providePromotionalBannerWidget(
    context = this,
    params = bannerParams,
    themeId = R.style.RevolutPay_RevolutPayBanner
)

Example​

For a complete, working implementation, please refer to the example app included in our public SDK repository.

To run the example app:

1. Clone the repository.
2. Open the project in Android Studio, or your preferred IDE.
3. Run the example app.

Implementation checklist​

Before going live, use this checklist to test your integration in both the SANDBOX and MAIN (production) environments.

Project setup​

• mavenCentral() is in build.gradle.
• Revolut Pay Lite SDK dependency is added.
• AndroidManifest.xml: INTERNET permission is present.
• AndroidManifest.xml: <queries> tag is present.
• AndroidManifest.xml: Deep link <intent-filter> is configured with a unique scheme/host.
• The deep link activity has launchMode="singleTop".
• SDK is initialised with the correct public API key and environment in your Application class.

Payment flow​

• The Revolut Pay button appears correctly on the checkout screen.
• Payment controller is created and configured with result handling.
• Tapping the button successfully calls your server to create an order and receives a token.
• Test case 1 (Revolut app not installed): The payment flow completes successfully within the in-app web flow.
• Test case 2 (Revolut app installed): The payment flow correctly redirects to the Revolut app and back.
• A successful payment shows a success message in the UI via the PaymentResult.Success callback.
• A failed payment shows an appropriate error message in the UI via the PaymentResult.Failure callback.
• The user cancelling the payment flow is handled gracefully via the PaymentResult.UserAbandonedPayment callback.
• Deep link handling is correctly implemented in your main activity's onNewIntent method.

Backend verification​

• Webhook endpoint is created and subscribed to events.
• Order fulfillment is triggered only by a ORDER_COMPLETED webhook.

What's next​

• SDK reference
• Sandbox test flows
• Using webhooks
• Revolut Pay button guidelines
• Revolut Pay marketing assets and guidelines