Accept payments via Card pop-up

In this tutorial, we'll walk you through the implementation process of the Card pop-up instance, powered by the Revolut Checkout Widget. The Card pop-up provides an interactive and user-friendly way for customers to complete their payments on your website.

How it works​

From an implementation perspective, the Card pop-up widget works with the following components:

1. Server-side: create an order and get token, using the Merchant API: Create an order endpoint.
2. Client-side: the Revolut Checkout Widget uses the order data to initialise the payWithPopup instance. Then the widget collects card details and handles other actions like redirection or 3D Secure authentication.
3. 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.
2. Your server uses the information from your client to create an order.
3. Your client creates an instance of the payWithPopup using the data from the server.
4. The widget opens a pop-up window, collects customer's card details, handles additional actions, and presents the payment result to the customer.
5. Your server receives webhook notifications about each event you're subscribed to.

Implementation overview​

Check the following high-level overview on how to implement the Card field on your website:

1. Install Revolut Checkout Widget
2. Create an order and get token
3. Initialise widget
4. Configure and mount Card pop-up
5. (Optional) Add promotional banner to the widget

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 Card pop-up​

1. Install Revolut Checkout Widget​

Before you begin, ensure the Revolut Checkout Widget is installed in your project. This widget is a necessary component to create and manage the card pop-up. You can install the widget via your project's package manager.

npm install @revolut/checkout

2. Create an order and get token​

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 initialise the Card pop-up. 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"
}

3. Initialise widget​

Once you have the token, you can initialise the widget. Use the RevolutCheckout() function with the token to do this.

const orderToken = "<token>"

const { payWithPopup } = await RevolutCheckout(orderToken)

// Initialisation code will go here

4. Configure and mount Card pop-up​

In this step, you'll integrate the Card pop-up into your webpage and set up the necessary event listener for user interactions. To do this, you need to prepare two things:

• HTML structure: adding necessary HTML elements to your page where the Card pop-up can be mounted
• JavaScript integration: adding necessary configuration to mount the Card pop-up and set up event listening

4.1 HTML structure​

Before initialising the Card pop-up in JavaScript, you need to prepare your checkout page. You should define a dedicated HTML element or button where you can listen to events and open the pop-up when necessary

<...>

<button id="pay-button" type="button">Pay</button>

<...>

• The <button> element with id="pay-button" is used to open the Card pop-up when the user clicks on it. This is where you'll need to route event listening.

4.2 JavaScript integration​

After setting up your pay button, configure the Card pop-up by calling the payWithPopup method on the instance. You can pass various options to customise the behaviour of the pop-up. Here is a basic example, without any additional configuration:

const orderToken = "<token>"

const { payWithPopup } = await RevolutCheckout(orderToken)

const payButton = document.getElementById("pay-button")

// On click open payment pop-up
payButton.addEventListener("click", function () {
  const popUp = payWithPopup({
    onSuccess() {
      // Do something to handle successful payments
      window.alert("Thank you!")
    },
    onError(error) {
      // Do something to handle successful payments
      window.alert(`Something went wrong. ${error}`)
    }
  })
})

• <token> is the token passed as the parameter to call the widget instance. You can find the value of token in the response that the Merchant API returns when you create an order successfully.

• payButton is routed to your HTML page, this is the element where you need to listen to events.

• payWithPopup is a function that creates the pop-up instance.

• onSuccess is an event handler that triggers when the payment is successful. In this example it shows a "Thank you" alert. It's designed to execute custom actions as specified by the merchant. Any return value is ignored.

  For example, onSuccess might be used to redirect customers to a confirmation page or to display a custom success message.

• onError is an event handler that triggers in case of an error. In this example it displays an alert with the error message. Similar to the onSuccess, it's intended for implementing custom error handling logic based on the merchant's requirements. Any return value is ignored.

  For example, onError might be used to redirect customers to an error-specific page or to display a custom error message.

By following these steps, you have successfully integrated the Revolut Checkout Widget's Card pop-up into your website. This setup allows customers to enter their card details securely and handles the transaction process seamlessly.

Remember to test this setup thoroughly in the Sandbox environment before going live. To help with testing check the following implementation checklist.

4.3 Additional settings​

The payWithPopup function of the Revolut Checkout Widget offers a range of options that allow for enhanced customisation and functionality. Here are some key additional settings you can leverage:

1. Saving 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.
2. Event handlers:
   • onSuccess, onError, and onValidation are event handlers that you can define to manage the different states of the payment process - from successful transactions to validation errors.
   • onCancel can be used to handle scenarios where the payment process is interrupted or cancelled by the user.
3. Localization:
   • The locale option allows you to set the language for the card field, making it more accessible to users in different regions.
4. Customer data and address information:
   • The customer option allows you to provide further information about your customer.
   • The billingAddress and shippingAddress options allow you to provide further information about your customer's addresses.

Providing additional customer data​

In addition to handling card details, you can also provide additional information about your customer, such as the customer's name, email, phone, and addresses for billing and shipping.

This is done by directly adding the information to the payWithPopup instance. Here is an example:

instance.payWithPopup({
  name: "Customer Name",
  email: "customer@example.com",
  phone: "+441234567890",
  billingAddress: {
    countryCode: "US",
    region: "CA",
    city: "San Francisco",
    postcode: "94105",
    streetLine1: "123 Market St",
    streetLine2: "Suite 100"
  },
  shippingAddress: {
    countryCode: "US",
    region: "CA",
    city: "San Francisco",
    postcode: "94105",
    streetLine1: "123 Market St",
    streetLine2: "Suite 100"
  },
  onSuccess() {
    // Do something to handle successful payments
    window.alert("Thank you!")
  },
  onError(error) {
    // Do something to handle successful payments
    window.alert(`Something went wrong. ${error}`)
  },
});

This allows you to capture comprehensive customer information along with the card details for the transaction. You can route a form on your client-side page to pass this data to the widget.

5. (Optional) Add promotional banner to the widget​

Optionally, you can display the Revolut upsell widget during checkout and drive customers to join Revolut. Use the banner to offer rewards to customers who create a new Revolut account after checkout.

This section describes how you can display the upsell banner with the card pop-up.

For the payment pop-up window, you just need to pass the following parameter in the Instance.payWithPopup configuration:

const orderToken = "<token>"

const { payWithPopup } = await RevolutCheckout(orderToken)

const payButton = document.getElementById("pay-button")

// On click open payment pop-up
payButton.addEventListener("click", function () {
  const popUp = payWithPopup({
    onSuccess() {
      // Do something to handle successful payments
      window.alert("Thank you!")
    },
    onError(error) {
      // Do something to handle successful payments
      window.alert(`Something went wrong. ${error}`)
    },
    upsellBanner: true,
    ...
    // All other options should be the same as in your default implementation
  })
})

Examples​

Example with minimal required parameters​

const orderToken = "<token>"

const { payWithPopup } = await RevolutCheckout(orderToken)

const payButton = document.getElementById("pay-button")

// On click open payment pop-up
payButton.addEventListener("click", function () {
  const popUp = payWithPopup({
    onSuccess() {
      // Do something to handle successful payments
      window.alert("Thank you!")
    },
    onError(error) {
      // Do something to handle successful payments
      window.alert(`Something went wrong. ${error}`)
    }
  })
})

Example with additional parameters​

const orderToken = "<token>"

const { payWithPopup } = await RevolutCheckout(orderToken)

const payButton = document.getElementById("pay-button")

// On click open payment pop-up
payButton.addEventListener("click", function () {
  const popUp = payWithPopup({
    name: "Customer Name",
    email: "customer@example.com",
    phone: "+441234567890",
    savePaymentMethodFor: "customer",
    billingAddress: {
      countryCode: "US",
      region: "CA",
      city: "San Francisco",
      postcode: "94105",
      streetLine1: "123 Market St",
      streetLine2: "Suite 100"
    },
    shippingAddress: {
      countryCode: "US",
      region: "CA",
      city: "San Francisco",
      postcode: "94105",
      streetLine1: "123 Market St",
      streetLine2: "Suite 100"
    },
    onSuccess() {
      // Do something to handle successful payments
      window.alert("Thank you!")
    },
    onError(error) {
      // Do something to handle successful payments
      window.alert(`Something went wrong. ${error}`)
    },
    onCancel() {
      // Do something to handle successful payments
      window.alert("The payment was cancelled.")
    }
  })
})

Example with promotional banner​

const orderToken = "<token>"

const { payWithPopup } = await RevolutCheckout(orderToken)

const payButton = document.getElementById("pay-button")

// On click open payment pop-up
payButton.addEventListener("click", function () {
  const popUp = payWithPopup({
    onSuccess() {
      // Do something to handle successful payments
      window.alert("Thank you!")
    },
    onError(error) {
      // Do something to handle successful payments
      window.alert(`Something went wrong. ${error}`)
    },
    upsellBanner: true
  })
})

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 Revolut Checkout Widget in sandbox mode instance. To do this pass the following parameter at widget initialisation:

const orderToken = "<token>"

const { payWithPopup } = await RevolutCheckout(orderToken, "sandbox")

// Initialisation code will go here

• Setup webhook URLs for your website to receive order and payment updates.
• Check if the widget 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.
  • Check that the webhook is properly received and processed.
• Test for error scenarios using test cards.
  • (Optional) Check if the payment shows properly in your Merchant Account.
  • Check that the webhook is properly received and processed.
• (Optional) Check if the promotional banner is rendered correctly.

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​

• Check our integration example - Learn more about how to use the Revolut Checkout Widget with the Card pop-up
• 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