Accept payments via Card field

In this tutorial, we'll walk you through the implementation process of the Card field instance, powered by the Revolut Checkout Widget. The Card field allows your customers to enter their card details directly within your site, providing a seamless and secure checkout experience.

How it works​

From an implementation perspective, the Card field 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 createCardField 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 createCardField using the data from the server.
4. The widget shows the card field, 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 field
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 field​

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 field. 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 field. 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 { createCardField } = await RevolutCheckout(orderToken)

// Initialisation code will go here

4. Configure and mount Card field​

In this step, you'll integrate the Card field 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 field will be rendered
• JavaScript integration: adding necessary configuration to mount the Card field and set up event listening

4.1 HTML structure​

Before initialising the Card field in JavaScript, you need to prepare your checkout page. You should define a dedicated HTML container where the Card field will be mounted.

You have multiple options to submit the card data. In this example we will use a submit button routed to the card field's submit() method. Here's an example:

<...>

<div id="card-field"></div>
<button id="button-submit" type="button">Submit</button>

<...>

• The <div> element with id="card-field" serves as the container for the card field on your page. This is where the card input form provided by the Revolut Checkout Widget will be dynamically inserted.
• The <button> element with id="button-submit" is used to submit the card details entered by the user. This is where you'll need to route event listening.

4.2 JavaScript integration​

After setting up your HTML, use JavaScript to mount the card field into the specified container, configure its behaviour, and add additional settings. Here is an example with minimal required parameters:

const orderToken = "<token>"

const { createCardField } = await RevolutCheckout(orderToken)

const cardField = createCardField({
  target: document.getElementById("card-field"),
  onSuccess() {
    // Do something to handle successful payments
    window.alert("Thank you!")
  },
  onError(error) {
    // Do something to handle payment errors
    window.alert(`Something went wrong. ${error}`)
  }
})

document.getElementById("button-submit").addEventListener("click", function () {
  cardField.submit()
})

• <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.

• createCardField is a function that creates the card field and mounts it inside the designated <div> element based on the target parameter.

• 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.

• Finally, the submit button is linked to the cardField.submit() method, which initiates the payment process when clicked.

By following these steps, you have successfully integrated the Revolut Checkout Widget's Card field 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 createCardField 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. Custom styling and classes:
   • You can apply custom styles to various states of the card field (like default, focused, invalid, etc.) using the styles property in the options object.
   • Similarly, custom classes can be assigned to these states using the classes property. This allows for greater control over the look and feel of the card input fields, making it easier to align with your website's design.
2. 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.
3. 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.
4. Localization:
   • The locale option allows you to set the language for the card field, making it more accessible to users in different regions.
5. 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, addresses for billing and shipping, and the cardholder name if it differs from the customer name.

This is done using the submit method of the card field instance, where you can pass a Meta object containing this information. Here is an example using the Meta object:

document.getElementById("button-submit").addEventListener("click", function () {
  var meta = {
    name: "Customer Name",
    email: "customer@example.com",
    phone: "+441234567890",
    cardholderName: "Cardholder Name",
    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"
    }
  }

  card.submit(meta)
})

In this example, when the submit button is clicked, the submit method is called with a meta object containing the customer's name, email, phone, cardholder name, and address details. 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.

By leveraging these additional settings and the ability to provide extended customer data, the Revolut Checkout Widget's createCardField instance becomes a powerful tool in creating a highly customisable and functional checkout experience on your website.

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

Optionally, you can use the RevolutCheckout.upsell module to display the Revolut upsell widget during checkout and drive customers to join Revolut. Use the banners 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 field.

For the card field, you need to separately initialise and mount the upsell banner widget as part of your Instance.createCardField implementation:

const orderToken = "<token>"

const { createCardField } = await RevolutCheckout(orderToken)

const cardField = createCardField({
  target: document.getElementById("card-field"),
  onSuccess() {
    // Do something to handle successful payments
    window.alert("Thank you!")
  },
  onError(error) {
    // Do something to handle payment errors
    window.alert(`Something went wrong. ${error}`)
  }
})

document.getElementById("button-submit").addEventListener("click", function () {
  cardField.submit()
})

const { cardGatewayBanner } = await RevolutCheckout.upsell({
  publicToken: "<yourPublicApiKey>",
  locale: "auto"
})

cardGatewayBanner.mount(document.getElementById("card-gateway-banner"), {
  orderToken
})

• <token> is the token taken from the response of order creation request.
• <yourPublicApiKey> is the Production Public API key that you generated from your Merchant account.
• card-field and card-gateway-banner parameters refer to DOM elements, where the card field and the promotional banner will be rendered on your checkout page.

Examples​

Example with minimal required parameters​

const orderToken = "<token>"

const { createCardField } = await RevolutCheckout(orderToken)

const cardField = createCardField({
  target: document.getElementById("card-field"),
  onSuccess() {
    // Do something to handle successful payments
    window.alert("Thank you!")
  },
  onError(error) {
    // Do something to handle payment errors
    window.alert(`Something went wrong. ${error}`)
  }
})

document.getElementById("button-submit").addEventListener("click", function () {
  cardField.submit()
})

Example with additional parameters​

const orderToken = "<token>"

const { createCardField } = await RevolutCheckout(orderToken)

const cardField = createCardField({
  target: document.getElementById("card-field"),
  onSuccess() {
    // Do something to handle successful payments
    window.alert("Thank you!")
  },
  onError(error) {
    // Do something to handle payment errors
    window.alert(`Something went wrong. ${error}`)
  },
  onCancel() {
    // Do something to handle payment cancellation
    window.alert("The payment was cancelled.")
  },
  locale: "en-US",
  theme: "dark", 
  styles: {
    default: {
      color: "#fff",
      "::placeholder": {
        color: "#666"
      }
    },
    autofilled: {
      color: "#fff"
    }
  }
})

document.getElementById("button-submit").addEventListener("click", function () {
  var meta = {
    name: "Customer Name",
    email: "customer@example.com",
    phone: "+441234567890",
    savePaymentMethodFor: "customer",
    cardholderName: "Cardholder Name",
    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"
    }
  }

  cardField.submit()
})

Example with promotional banner​

const orderToken = "<token>"

const { createCardField } = await RevolutCheckout(orderToken)

const cardField = createCardField({
  target: document.getElementById("card-field"),
  onSuccess() {
    // Do something to handle successful payments
    window.alert("Thank you!")
  },
  onError(error) {
    // Do something to handle payment errors
    window.alert(`Something went wrong. ${error}`)
  }
})

document.getElementById("button-submit").addEventListener("click", function () {
  cardField.submit()
})

const { cardGatewayBanner } = await RevolutCheckout.upsell({
  publicToken: "<yourPublicApiKey>",
  locale: "auto"
})

cardGatewayBanner.mount(document.getElementById("card-gateway-banner"), {
  orderToken
})

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 { createCardField } = 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 field
• 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