Guides • Accept Payments
Card payments

Accept your first card payment

tip

If your website runs on WooCommerce, Prestashop, Adobe Commerce (Magento 2), OpenCart, or Shopify e-commerce platform, you need to install and configure Revolut plugins.

This tutorial walks you through the steps to accept the first payment. The tutorial assumes that you run your own e-commerce website and manage its code and files.

Check the following high-level procedure to integrate the Revolut Checkout Widget (widget) with the Merchant API:

  1. Server side: Create an order via the Merchant API: Create order endpoint.
  2. Client side: Install the widget by adding RevolutCheckout to your application.
  3. Client side: Choose the option to collect card details and call the widget instance.

0. Prerequisites​

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

1. Create an order​

When a user decides to make a purchase on your e-commerce website, you must create an order on the server side by sending a POST request to https://merchant.revolut.com/api/1.0/orders. Include the authorization HTTP header in the request, in the following format:

"Authorization: Bearer <yourSecretApiKey>"

Where <yourSecretApiKey> is the Production Secret API key that you generated from your Merchant account.

note

You must create an order object for each purchase.

Create an order with this request.

Once the order is created successfully, the Merchant API returns a JSON object in the response that looks like this:

{
  "id": "<id>",
  "public_id": "<public_id>",
  "type": "PAYMENT",
  "state": "PENDING",
  "created_date": "2020-10-15T07:46:40.648108Z",
  "updated_date": "2020-10-15T07:46:40.648108Z",
  "order_amount": {
    "value": 100,
    "currency": "GBP"
  },
  "checkout_url": "<checkout_url>"
}
tip

Save the public_id from the response. It is a temporary token generated for every order a customer initiates on the website. It's also the identifier to pass when calling the widget instance.

Once the order is paid, the public_id expires.

note

The checkout_url contains a link to the widget-based checkout page, hosted by Revolut.

After the order is paid, the checkout_url becomes unavailable.

2. Install the widget​

Once the order is successfully created, install the widget on the client side.

To install the Revolut Checkout Widget, you need to add RevolutCheckout to your checkout page in one of the following ways:

  • Adding the embedded script to the checkout HTML page. This adds RevolutCheckout to the browser's global window.
  • Installing the widget's NPM package. This uses JavaScript modules to access the widget instance.
note

The script is requested asynchronously, so you don't need to worry about the contents of your page being blocked.

Add the embed script​

Add the embed script to the document head of your checkout HTML page.

<head><title>Shop</title><script>!function(e,o,t){var n={sandbox:"https://sandbox-merchant.revolut.com/embed.js",prod:"https://merchant.revolut.com/embed.js",dev:"https://merchant.revolut.codes/embed.js"},r={sandbox:"https://sandbox-merchant.revolut.com/upsell/embed.js",prod:"https://merchant.revolut.com/upsell/embed.js",dev:"https://merchant.revolut.codes/upsell/embed.js"},l=function(e){var n=function(e){var t=o.createElement("script");return t.id="revolut-checkout",t.src=e,t.async=!0,o.head.appendChild(t),t}(e);return new Promise((function(e,r){n.onload=function(){return e()},n.onerror=function(){o.head.removeChild(n),r(new Error(t+" failed to load"))}}))},u=function(){if(window.RevolutCheckout===i||!window.RevolutCheckout)throw new Error(t+" failed to load")},c={},d={},i=function o(r,d){return c[d=d||"prod"]?Promise.resolve(c[d](r)):l(n[d]).then((function(){return u(),c[d]=window.RevolutCheckout,e[t]=o,c[d](r)}))};i.payments=function(o){var r=o.mode||"prod",d={locale:o.locale||"auto",publicToken:o.publicToken||null};return c[r]?Promise.resolve(c[r].payments(d)):l(n[r]).then((function(){return u(),c[r]=window.RevolutCheckout,e[t]=i,c[r].payments(d)}))},i.upsell=function(e){var o=e.mode||"prod",n={locale:e.locale||"auto",publicToken:e.publicToken||null};return d[o]?Promise.resolve(d[o](n)):l(r[o]).then((function(){if(!window.RevolutUpsell)throw new Error(t+" failed to load");return d[o]=window.RevolutUpsell,delete window.RevolutUpsell,d[o](n)}))},e[t]=i}(window,document,"RevolutCheckout");
</script></head>

3. Call the widget instance​

Choose one of the following options to integrate with the widget to collect card details:

A payment pop-up window, which appears over the page that is currently opened and requests the user's card information. This is easy and fast to implement. In this tutorial, you use this option. For more information, see: Merchant Web SDK: Instance.payWithPopup.

Pay with pop-up

Design your implementation to call the widget instance as follows:

  1. When the user clicks Pay, the payment pop-up window opens. To achieve this, you create a button and attach a click event listener to it that triggers RC.payWithPopup(options).
  2. The user enters the required card details and the optional personal details, and then moves to the payment processing.
  3. After the payment is processed, you can redirect the user to the appropriate page to handle the success or failed status of the order.

Implement the following code snippet, where:

  • RevolutCheckout is the widget instance.
  • <public_id> is the public_id passed as the parameter to call the widget instance. You can find the value of public_id in the response that the Merchant API returns when you create an order successfully.
tip
  • email parameter is required if the order that is being paid does not contain an email
  • name parameter is required when using Instance.createCardField. For Instance.payWithPopup, the name will be asked dynamically if not passed in the options.
<button id="pay-button">Pay</button>
<script>
  RevolutCheckout("<public_id>").then(function (RC) {
    var payButton = document.getElementById("pay-button");
    // On click open payment pop-up
    payButton.addEventListener("click", function () {
      RC.payWithPopup({
        name: "First Last",  // (mandatory!) name of the cardholder
        email: "customer@example.com", // (optional) email of the customer
        phone: "+447950630319", // (optional) phone of the customer
        billingAddress: {    // (optional) billing address of the customer
          countryCode: "GB", // if sending billing address, this field is mandatory
          postcode: "EC2V 6DN", // if sending billing address, this field is mandatory
          region: "Greater London",
          city: "London",
          streetLine1: "Revolut",
          streetLine2: "1 Canada Square",
        },
        shippingAddress: {   // (optional) shipping address of the customer
          countryCode: "GB", // if sending shipping address, this field is mandatory
          postcode: "EC2V 6DN", // if sending shipping address, this field is mandatory
          region: "Greater London",
          city: "London",
          streetLine1: "Revolut",
          streetLine2: "1 Canada Square",
        },
        onSuccess() {  // Callback called when payment finished successfully
          window.alert("Thank you!");
        },
        onError(message) {  // Callback in case some error happened
          window.alert("Oh no :(");
        },
        onCancel() {  // (optional) Callback in case user cancelled a transaction
          window.alert("Payment cancelled!");
        },
      });
    });
  });
</script>

(Optional) 4. 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.

For more information about the upsell module, see: Merchant Web SDK: The upsell object.

This section describes how you can display the upsell banner for card payments collected with the Revolut Checkout Widget.

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

RevolutCheckout("<public_id>").then(function (RC) {
  var payButton = document.getElementById("pay-button");
  // On click open payment pop-up
  payButton.addEventListener("click", function () {
    RC.payWithPopup({
      ...
      upsellBanner: true,
      ...
      // All other options should be the same as in your default implementation
    })
  }
}

Where <public_id> is the public_id taken from the response of order creation request.

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/api/1.0.

  • Setup webhook URLs for your website to receive order and payment updates.
  • Check if the widget is displayed correctly using the order public_id. 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.
  • 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.
  • 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.

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.

success

Congratulations! You've successfully integrated the widget with the Merchant API to the checkout page and accepted your first payment for the order.

What's next​

PreviousImplement Revolut Pay with Fast checkout
NextApple Pay and Google Pay
Was this page helpful?