NAV Navbar

RevolutCheckout.js reference

Install the widget

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

Embed script

<script>!function(e,o,t){e[t]=function(n,r){var c={sandbox:"https://sandbox-merchant.revolut.com/embed.js",prod:"https://merchant.revolut.com/embed.js",dev:"https://merchant.revolut.codes/embed.js"},d=o.createElement("script");d.id="revolut-checkout",d.src=c[r]||c.prod,d.async=!0,o.head.appendChild(d);var s={then:function(r,c){d.onload=function(){r(e[t](n))},d.onerror=function(){o.head.removeChild(d),c&&c(new Error(t+" is failed to load"))}}};return"function"==typeof Promise?Promise.resolve(s):s}}(window,document,"RevolutCheckout");</script>

Add the embed script to all the pages that you want to use RevolutCheckout on.

Note: The script should be inserted before the code that calls RevolutCheckout.

Npm package

Install npm package and import the ES module later to your code.

npm install @revolut/checkout
import RevolutCheckout from "@revolut/checkout"

RevolutCheckout("XXX", "prod").then((instance) => {
  // work with instance
})

RevolutCheckout

type RevolutCheckout = (
  `public_id`: string,
  mode?: 'prod' | 'sandbox' = 'prod'
) => Promise<Instance>;

Load the embed script and create an instance for the order token.

Parameters

Script load example

RevolutCheckout("<PUBLIC_ID>", "prod").then(function (instance) {
  // Work with instance:
  // instance.payWithPopup()
  // instance.createCardField()
  // ...
});

Returns Promise with an order Instance.

Instance

type Instance = {
  payWithPopup: InstancePayWithPopup;
  createCardField: InstanceCreateCardField;
  destroy: () => void;
};

Instance is passed as an argument to the consuming function of the RevolutCheckout promise (i.e. registered using .then). It’s used to open a payment pop-up window or to create a card field.

Instance usage example

RevolutCheckout("<PUBLIC_ID>").then(function (instance) {
  instance.payWithPopup({
    onSuccess() {
      window.alert("Thank you!");
    },
    onError(message) {
      window.alert("Oh no :(");
    }
  });
});

Instance.payWithPopup

Open a payment pop-up window, which is available on the Instance.

Open a payment pop-up window

type InstancePayWithPopup = (
  options: Options
) => {
  destroy: () => void;
};


type Options = {
  onSuccess?: () => void;
  onError?: (message: string) => void;
  onCancel?: () => void;
  name: string;
  email?: string;
  phone?: string;
  locale?: string;
  savePaymentMethodFor?: string;
  billingAddress?: {
    countryCode: string;
    region?: string;
    city?: string;
    postcode: string;
    streetLine1?: string;
    streetLine2?: string;
  };
  shippingAddress?: {
    countryCode: string;
    region?: string;
    city?: string;
    postcode: string;
    streetLine1?: string;
    streetLine2?: string;
  };
};

Use the Options object to specify the pages where the customer should be redirected and any additional information related to the payment of the customer:

Option Description Format
onSuccess Callback when the payment is successfully completed. Function
onError Callback if the transaction fails to complete. The reason for the failure is available in the message parameter. Function
onCancel Callback if a user did not complete the transaction and cancelled the authorisation or closed the payment pop-up window. Function
locale Controls the language of the text in the widget. Possible values are: en (English), es (Spanish), de (German), fr (French), it (Italian), nl (Dutch), pl (Polish), pt (Portuguese) String
name Cardholder’s name in the format of FirstName LastName. This value is required. String
email Customer's email. This is required if not set on the order via API. String
phone Customer's phone number if available String
savePaymentMethodFor Indicates in which case this saved payment method can be used for payments.

Possible values:
- customer: This method is used only when the customer is on the checkout page.
- merchant: This method can be used without the customer being on the checkout page, and the merchant can initiate transactions (e.g. take payments for recurring transactions). This method is saved as the new default payment method for merchant initiated transactions, regardless of the number of saved payment methods stored against the customer.
Enum
billingAddress Customer's billing address, which is required if not set on order via API. Object
billingAddress.countryCode Country code (e.g. GB). If sending the billingAddress, this is required. String
billingAddress.region State, county or region String
billingAddress.city Name of the city (e.g. London) String
billingAddress.postcode Postal code (e.g. EC2V 6DN). If sending the billingAddress, this is required. String
billingAddress.streetLine1 Address line 1 (e.g. 1 Canada Square) String
billingAddress.streetLine2 Address line 2 (optional) String
shippingAddress The same object as the billingAddress object. However, it is displayed only in the order details on the merchant dashboard. Object

Returns

Methods object:

Field Description Format
methods.destroy Manually destroy payment pop-up if needed Function

Examples

Example with minimal required parameters

Example with minimal required parameters

RevolutCheckout("<PUBLIC_ID>").then(function (instance) {
  instance.payWithPopup({
    onSuccess() {
      window.alert("Thank you!");
    },
    onError(message) {
      window.alert("Oh no :(");
    }
  });
});

Example with minimal required parameters, assuming that the billingAddress object is not sent via API.

Example with minimal required parameters and billingAddress

RevolutCheckout("<PUBLIC_ID>").then(function (instance) {
  instance.payWithPopup({
    onSuccess() {
      window.alert("Thank you!");
    },
    onError(message) {
      window.alert("Oh no :(");
    },
    locale: "es",
    billingAddress: {
      countryCode: "GB",
      region: "Greater London",
      city: "London",
      streetLine1: "Revolut",
      streetLine2: "1 Canada Square",
      postcode: "EC2V 6DN"
    },
  });
});

Example with all possible parameters.

Example with all possible parameters

RevolutCheckout("<PUBLIC_ID>").then(function (instance) {
  var popup = instance.payWithPopup({
    name: "First Last",
    email: "customer@example.com",
    phone: "+447950630319",
    locale: "es",
    billingAddress: {
      countryCode: "GB",
      region: "Greater London",
      city: "London",
      streetLine1: "Revolut",
      streetLine2: "1 Canada Square",
      postcode: "EC2V 6DN"
    },
    shippingAddress: {
      countryCode: "GB",
      region: "Greater London",
      city: "London",
      streetLine1: "Revolut",
      streetLine2: "1 Canada Square",
      postcode: "EC2V 6DN"
    },
    onSuccess() {
      window.alert("Thank you!");
    },
    onError(message) {
      window.alert("Oh no :(");
    }
  });


  // ...


  popup.destroy();
});

Instance.createCardField

Create a card field, which is available on the Instance.

type InstanceCreateCardField = (
  options: Options
) => {
  submit: (meta: Meta) => void;
  validate: () => void;
  destroy: () => void;
};


type Options = {
  target: HTMLElement;
  onSuccess?: () => void;
  onError?: (message: string) => void;
  onValidation?: (messages: string[]) => void;
  onCancel?: () => void;
  locale?: string;
  styles?: {
    default?: Object;
    focused?: Object;
    invalid?: Object;
    empty?: Object;
    autofilled?: Object;
    completed?: Object;
  };
  classes?: {
    default?: string;
    focused?: string;
    invalid?: string;
    empty?: string;
    autofilled?: string;
    completed?: string;
  };
};


type Meta = {
  name: string;
  email?: string;
  phone?: string;
  savePaymentMethodFor?: string;
  billingAddress?: {
    countryCode: string;
    region?: string;
    city?: string;
    postcode: string;
    streetLine1?: string;
    streetLine2?: string;
  };
  shippingAddress?: {
    countryCode: string;
    region?: string;
    city?: string;
    postcode: string;
    streetLine1?: string;
    streetLine2?: string;
  };
};

Use the Options object to specify the pages where the customer should be redirected and any additional information related to the payment of the customer:

Option Description Format
onSuccess Callback is called when the payment is completed successfully. Function
onError Callback if the transaction fails to complete. The reason for the failure is available in the message parameter. Function
onValidation Callback called on validation of the status change.
Function contains messages as first parameter (see below)
Function
onValidation.messages Array of strings that contains validation errors (e.g. Your card has expired.) String
onCancel Callback if a user did not complete the transaction and cancelled the authorisation or closed the checkout window. Function
locale Controls the language of the text in the widget. Possible values are: en (English), es (Spanish), de (German), fr (French), it (Italian), nl (Dutch), pl (Polish), pt (Portuguese) String
target DOM element where secure iframe with the card field input is rendered HTML Element
styles Object of styles for different state of card field input, used to customize different states inside the secure iframe. Object
styles.default Base styles that are always applied regardless of state. Object
styles.focused Applied when a user focuses inside the input with a mouse or a keyboard. Object
styles.invalid Applied on validation error Object
styles.empty Applied when a user hasn't entered any amount. Object
styles.autofilled Applied when a user used autofilled card details from the browser. Object
styles.completed Applied if the card field input is completed without any errors Object
classes Same as styles but used to apply styles with classes to the target element outside the secure iframe. Object
classes.default Set default to 'rc-card-field' String
classes.focused Set default to 'rc-card-field--focused' String
classes.invalid Set default to 'rc-card-field--invalid' String
classes.empty Set default to 'rc-card-field--empty' String
classes.autofilled Set default to 'rc-card-field--autofilled' String
classes.completed Set default to 'rc-card-field--completed' String

Returns

Methods object:

Field Description Format
methods.destroy Manually destroy card field if needed Function
methods.submit Submit the card details that a user entered and complete the payment with additional customer metadata. Accepts a single meta parameter (see below) Function
methods.validate Manually trigger validation of the card details that a user entered. By default, it’s triggered only after a user starts to enter card details and on submit. Function

Meta object:

Field Description Format
meta.name Cardholder’s name in the format of FirstName LastName. This value is required. String
meta.email Customer's email. This is required if not set on the order via API. String
meta.phone Customer's phone number if available String
meta.savePaymentMethodFor Indicates in which case this saved payment method can be used for payments.

Possible values:
- customer: This method can be used only when the customer is on the checkout page.
- merchant: This method can be used without the customer being on the checkout page, and the merchant can initiate transactions (e.g. take payments for recurring transactions). This method is saved as the new default payment method for merchant initiated transactions, regardless of the number of saved payment methods stored against the customer.
Enum
meta.billingAddress Customer's billing address. This is required if not set on order via API. Object
meta.billingAddress.countryCode Country code (e.g. GB). If sending the billingAddress, this is required. String
meta.billingAddress.region State, county or region String
meta.billingAddress.city Name of the city (e.g. London) String
meta.billingAddress.postcode Postal code (e.g. EC2V 6DN). If sending the billingAddress, this is required. String
meta.billingAddress.streetLine1 Address line 1 (e.g. 1 Canada Square) String
meta.billingAddress.streetLine2 Address line 2 (optional) String
meta.shippingAddress Same as meta.billingAddress, However, it is displayed only in the order details on the merchant dashboard. Object

Examples

Example with minimal required parameters

HTML

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

JS

RevolutCheckout("<PUBLIC_ID>").then(function (instance) {
  var card = instance.createCardField({
    target: document.getElementById("card-field"),
    onSuccess() {
      window.alert("Thank you!");
    },
    onError(message) {
      window.alert("Oh no :(");
    },
  });


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

Example with minimal required parameters, assuming that the billingAddress and the email objects are not sent via API.

HTML

<form>
  <div>
    <label>Email</label>
    <input name="email" placeholder="customer@example.com" />
  </div>
  <div>
    <label>Card</label>
    <div name="card"></div>
  </div>
  <div>
    <label>Billing Address</label>


    <input name="country" placeholder="Country" />
    <input name="state" placeholder="State" />
    <input name="city" placeholder="City" />
    <input name="line1" placeholder="Address line 1" />
    <input name="line2" placeholder="Address line 2" />
    <input name="postal" placeholder="Postal" />
  </div>
  <button>Submit</button>
</form>

JS

RevolutCheckout("<PUBLIC_ID>").then(function (instance) {
  var form = document.querySelector("form");
  var card = instance.createCardField({
    target: document.querySelector("[name=card]"),
    onSuccess() {
      window.alert("Thank you!");
    },
    onError(message) {
      window.alert("Oh no :(");
    },
    locale: "es"
  });


  form.addEventListener("submit", function (event) {
    // Prevent browser form submission. You need to submit card details first.
    event.preventDefault();


    var data = new FormData(form);


    card.submit({
      email: data.get("email"),
      billingAddress: {
        countryCode: data.get("country"),
        region: data.get("state"),
        city: data.get("city"),
        streetLine1: data.get("line1"),
        streetLine2: data.get("line2"),
        postcode: data.get("postal")
      }
    });
  });
});

See the card field integration example.

Instance.revolutPay

Display the Revolut Pay button to allow your customer to make a payment with their Revolut app.

Display the button

interface Instance {
  // ...
  revolutPay: (options: Options) => {
    destroy: () => void
  }
}

interface Options {
  target: HTMLElement
  phone?: string
  email?: string
  locale?: string
  onSuccess?: () => void
  onError?: (RevolutCheckoutError) => void
  onCancel?: () => void
}

Use the Options object to specify the pages that the user should be redirected to and any additional information related to the payment of the user:

Field Description Format
target DOM element where secure iframe with the button is rendered HTMLElement
phone User phone number (optional) String
email User email address (optional) String
onSuccess Callback when the payment is successfully completed Function
onError Callback if a transaction fails, and the reason is available in the message parameter. Function
onCancel Callback if a user did not complete the transaction and canceled the authorization, or closed the payment pop-up window. Function
locale Controls the language of the text in the widget. Possible values are: en (English), es (Spanish), de (German), fr (French), it (Italian), nl (Dutch), pl (Polish), pt (Portuguese) String

Returns

Methods object:

Field Description Format
destroy Manually destroy the button if needed String

Example

Example with minimal parameters recommended:

Example

<div id='revolut-pay'></div>

RevolutCheckout("XXX").then(function(instance) {
  instance.revolutPay({
    target: document.getElementById('revolut-pay'),
    phone: '+441632960022', // recommended
    onSuccess() {
      console.log('Payment completed')
    },
    onError(error) {
      console.error('Payment failed: ' + error.message)
    }
  })
})

Integration examples

Integrating the payment pop-up

This sample shows how to use RevolutCheckout.js with a payment pop-up and the Merchant API. The hosted version is running in the Sandbox environment — use one of our test cards to ensure that the widget works properly.

Note: If you fork the example - you will need to create a new Revolut Business Sandbox account and set the API key as REVOLUT_API_KEY inside CodeSandbox secrets.

Fork

Integrating and customising the card field

This sample shows how to use RevolutCheckout.js with the integrated card field. The hosted version is running in the Sandbox environment — use one of our test cards to ensure that the widget works properly.

Note: If you fork the example - you will need to create a new Revolut Business Sandbox account and set the API key as REVOLUT_API_KEY inside CodeSandbox secrets.

3D Secure

When a customer initiates a card payment, Revolut performs a 3D Secure (3DS) challenge if it's required.

On the client side, you don’t need to implement additional changes to allow these challenges. The instance methods (instance.paywithPopup and instance.createCardField) of Revolut’s iFrame take care of every stage:

  1. Sending all the relevant information to the 3DS Server.
  2. Handling the frictionless flow when possible.
  3. Rendering the Access Control Server (ACS) URL in case a full challenge is requested.
  4. Handling the response from the 3DS server to complete the challenge and have an authenticated transaction.

Related links