Guides • Accept Payments
Card payments

Accept your first card payment

tip

If your website runs on WooCommerce, Prestashop, Magento 2, BigCommerce, 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 a Revolut Checkout Widget (widget) with the Merchant API:

  1. Server side: Create an order via the Merchant API request.
  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 contained in the response, which 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. 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. 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.
  • 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,n){var r=e=>{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=o.createElement("script");return r.id="revolut-checkout",r.src=n[e]||n.prod,r.async=!0,o.head.appendChild(r),r},t=function(e,r){return{then:function(t,c){e.onload=function(){t(r())},e.onerror=function(){o.head.removeChild(e),c&&c(new Error(n+" failed to load"))}}}};e[n]=function(o,c){var u=t(r(c||"prod"),(function(){return e[n](o)}));return"function"==typeof Promise?Promise.resolve(u):u},e[n].payments=function(o){var c=t(r(o.mode||"prod"),(function(){return e[n].payments({locale:o.locale||"en",publicToken:o.publicToken||null})}));return"function"==typeof Promise?Promise.resolve(c):c}}(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({
// (mandatory!) name of the cardholder
name: "First Last",
// (optional) email of the customer
email: "customer@example.com",
// (optional) phone of the customer
phone: "+447950630319",
// (optional) billing address of the customer
billingAddress: {
countryCode: "GB", //if sending billing address, this field is mandatory
region: "Greater London",
city: "London",
streetLine1: "Revolut",
streetLine2: "1 Canada Square",
postcode: "EC2V 6DN", //if sending billing address, this field is mandatory
},
// (optional) shipping address of the customer
shippingAddress: {
countryCode: "GB", //if sending shipping address, this field is mandatory
region: "Greater London",
city: "London",
streetLine1: "Revolut",
streetLine2: "1 Canada Square",
postcode: "EC2V 6DN", //if sending shipping address, this field is mandatory
},
// Callback called when payment finished successfully
onSuccess() {
window.alert("Thank you!");
},
// Callback in case some error happened
onError(message) {
window.alert("Oh no :(");
},
// (optional) Callback in case user cancelled a transaction
onCancel() {
window.alert("Payment cancelled!");
},
});
});
});
</script>

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, you can deploy to production. 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

Was this page helpful?