Accept payments via Revolut Merchant Card Form SDK - Android

The Revolut Merchant Card Form SDK for Android allows merchants to accept card payments within their mobile applications. This guide provides step-by-step instructions for integrating a prebuilt payment form using the SDK.

How it works​

From an implementation perspective, the SDK works with the following components:

1. Client-side: initialise the SDK by providing your Merchant Public API key and selecting the preferred environment to prepare for accepting payments.
2. Server-side: create an order and get token, using the Merchant API: Create an order endpoint.
3. Client-side: the SDK uses the order data to invoke the RevolutPaymentApi.buildCardPaymentIntent() method. This returns an intent for launching a UI activity for gathering payment details and confirming the payment.
4. Client-side: after the payment is completed the result is received by the onActivityResult() method, providing the status of the payment.
5. Endpoint for webhooks: optionally, you can set up an endpoint which receives 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 order and payment flow is similar to all card payment solutions:

1. The customer goes to the checkout page in your app, reviews their order details and decides to proceed with the payment.
2. Your server uses the information from your client to create an order.
3. Your client uses the SDK to initiate the payment process using the order data from the server.
4. The SDK opens an activity to collect the customer's card details, handles additional actions such as 3D Secure authentication, and presents the payment result to the customer.
5. Your server receives webhook notifications about each event you're subscribed to.

Implementation overview​

1. Install the SDK
2. Initialise the SDK
3. Create an order
4. Start the payment process
5. Handle the payment results

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 key

Implement the Revolut Card Payments SDK​

1. Install the SDK​

1. Since the SDK is hosted on mavenCentral, to fetch the dependency add the following lines to your project-level build.gradle file:

   allprojects {
       repositories {
           mavenCentral()
       }
   }
   

2. To install the SDK, add the merchantcardform to the dependencies block of your module-level build.gradle file:

   dependencies {
       // ...
   
       // Revolut Card Payments SDK
       implementation 'com.revolut.payments:merchantcardform:1.3'
   }
   

3. Sync your project.

2. Initialise the SDK​

Before accepting payments, initalise the SDK by calling the following method:

RevolutPaymentApi.init(
    Environment.PRODUCTION,
    "<merchantPublicKey>" // Your Production API Public key
)

3. Create an order​

When a customer decides to make a purchase on your website, using the Merchant API: Create an order endpoint, you'll need to create an order based on your customer's checkout and obtain a token.

This token represents the order and is used to invoke the buildCardPaymentIntent() method. The process of creating an order and receiving a token will vary based on your backend setup. See an example response of an order created with minimal required parameters:

{
  "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": 5,
  "currency": "GBP",
  "outstanding_amount": 5,
  "capture_mode": "automatic",
  "checkout_url": "https://checkout.revolut.com/payment-link/0adc0e3c-ab44-4f33-bcc0-534ded7354ce",
  "enforce_challenge": "automatic"
}

4. Start the payment process​

To accept a payment from your customer, you'll need to initiate the payment process by invoking the RevolutPaymentApi.buildCardPaymentIntent() method. This will return an intent for launching an activity. The activity provides the necessary UI for collecting the user's card details and confirming the payment.

The method requires several parameters, including the application context, the unique order token obtained from your server. Optionally, the customer's email, billing and shipping address. The intent created is then launched using the startActivityForResult() method.

Here's an example of how you can start the payment process:

startActivityForResult(
    RevolutPaymentApi.buildCardPaymentIntent(
        context = context,
        orderId = "<token>",
        RevolutPaymentApi.Configuration.CardPayment(
            email = "example.customer@example.com", 
            billingAddress = AddressParams( 
                streetLine1 = "1 Canada Square",
                streetLine2 = "Sample street",
                city = "London",
                region = "Greater London",
                country = "GB",
                postcode = "12345"
            ),
            shippingAddress = null, 
            savePaymentMethodFor = null
        )
    ), 0
)

Save payment methods​

The savePaymentMethodFor parameter allows you to save a customer's payment method used in the current payment session. You have the option to save a payment method either for the customer or the merchant. To learn more about customer and merchant initiated payments, see: Charge a customer's saved payment method.

5. Handle the payment results​

To handle the payment result, you need to implement onActivityResult() in your activity or fragment, which is invoked when the payment operation is completed. This method allows you to capture the payment result and perform various actions within your application.

onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
    super.onActivityResult(requestCode, resultCode, data)
    val result = RevolutPaymentApi.mapIntentToResult(resultCode, data)
    result?.let { handleResult(it) }
}

The mapIntentToResult() method is critical because it abstracts the complexity of interpreting the result of the payment activity. This allows you to focus on the logic for handling the result, such as:

• Logging: Capture payment results in your logging system to track transactions and identify any issues that may arise.
• User notifications: Notify users of the outcome of their payment, providing a success message for completed payments or error details for failed ones.
• Order confirmation emails: Send an order confirmation email to the customer, including the details of their purchase and the payment status.
• Start a shipping workflow: If the payment is successful, initiate the shipping workflow to prepare the order for dispatch to the customer.
• Analytics and reporting: Record payment results for business analytics and reporting purposes, helping you understand sales performance and customer behaviour.

Using webhooks​

In addition to handling payment results directly in your app, you can also set up webhooks to receive notifications about different events. Webhooks provide a reliable way to track the entire order and payment lifecycle, allowing your server to react to changes.

To implement webhooks, refer to the Use webhooks to track order and payment lifecycle tutorial for detailed instructions on setting up and managing webhooks with the Merchant API.

By utilizing both in-app payment result handling and webhooks, you can create a robust and responsive payment processing system that enhances the user experience and streamlines your business operations.

Example app​

The SDK's public repository contains a fully functional example app designed to demonstrate how to integrate the Revolut Merchant Card Form SDK into your mobile application. This app serves as a practical reference for developers, showcasing a working implementation of the SDK's features.

Run the example application​

Follow these steps to set up and run the example app:

1. Clone the repository:

   git clone https://bitbucket.org/revolut/revolut-card-payments-android.git
   

2. Open the project in Android Studio, or your preferred IDE.

3. Update the following line in the demo/app/build.gradle file:

   implementation 'com.revolut:cardpayments:1.0.0' // Change this line
   
   implementation 'com.revolut.payments:merchantcardform:1.3' // To this line
   

4. Now you can run the example app.

Implementation checklist​

Before deploying your implementation to your production environment, complete the checklist below to see if everything works as expected, using Merchant API's Sandbox environment.

To test in Sandbox environment, set the base URL of your API calls to: sandbox-merchant.revolut.com/ and initialise the SDK in sandbox:

RevolutPaymentApi.init(
    Environment.SANDBOX,
    "<merchantPublicKey>" // Your Sandbox API Public key
)

• Check if the card form is displayed correctly using the order token. The order must be created in the same environment where the widget is loaded, in this case the Sandbox environment.
• Make a test payment using test cards to simulate a successful payment.
  • (Optional) Check if the payment shows properly in your Merchant Account.
• Test for error scenarios using test cards.
  • (Optional) Check if the payment shows properly in your Merchant Account.
• (Optional) Setup webhook URLs for your website to receive order and payment updates.
  • Check that the webhooks (for successful and failed payments) are properly received and processed.

If your implementation handles all these cases as you expect in Sandbox, it is advised you also test your implementation in production before going live. Once your implementation passes all the checks in both environments, you can safely go live with your implementation.

These checks only cover the implementation path described in this tutorial, if your application handles more features of the Merchant API, see the Merchant API: Implementation checklists.

What's next​

• Learn more about the SDK - Explore our public SDK repository for more information on integration
• Learn more about the order and payment lifecycle
• Learn more about webhooks - Check our guide about how you can track payment lifecycle with the Merchant API's webhook service
• Learn more about refunds - Check our guide about how you can refund your orders
• Learn more about saving payment methods - Check our guides about different use-cases with saved payment methods
• Learn more about order management - Explore the full capabilities of our Orders API
• Learn more about customer management - Explore the full capabilities of our Customers API