NAV Navbar

Merchant API

Introduction to Merchant accounts

Please note that Merchant Accounts feature is available only to businesses that have been invited to participate in our private launch. In the meantime, our team is working hard to make it available to every eligible business. Stay tuned!

Revolut has created Merchant Accounts to provide customers with an opportunity to accept online debit & credit card payments straight into their Revolut Business Merchant accounts.

There are two ways to accept card payments:

You can decide which one of those checkout methods suits your website and proceed to the respective guide to start the integration!

Revolut Widget

This guide will help you to set up a Revolut Checkout Widget and configure your back-end infrastructure to start accepting online debit & credit card payments on your website.

The Checkout Widget can be integrated in two different ways:

This page provides a general overview of how to integrate the Checkout Widget. For more detailed documentation, please refer to the following guides:

Reference to RevolutCheckout.js

Reference to Back-end API

Integration guide

Step 1. In your Revolut Business account, apply for a Merchant Account. Once your application gets approved, get an API token.

Step 2. Create a new order on your server back-end with the amount and currency.

Create a new order

POST https://merchant.revolut.com/api/1.0/orders

Authorization: Bearer <your_API_token>

{
  "amount": 200,
  "currency": "GBP"
}

Response

{
  "id": "ID",
  "public_id": "TOKEN_XXX",
  "type": "PAYMENT",
  "state": "PENDING",
  "created_date": 0,
  "updated_date": 0,
  "order_amount": { "value": 10000, "currency": "GBP" }
}

From the response save the public_id - it is a temporary token generated for every new order a customer initiates on a merchant's website. Normally, a public_id is created at the moment when the amount is known for the order. A public_id is also the identifier which is passed from the back-end server to the client side in order to initiate th checkout widget. Once the order is paid, a public_id expires.

You will need to create a new order for each purchase.

Step 3. Add an embed script snippet to the html document head in the page template. This script will be requested asynchronously so you don't have to worry about content blocking the loading of the page.

Embed script snippet

<head>
  <title>Shop</title>
  <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>
</head>

The script also availble as NPM package for your convenience.

NPM package

npm install @revolut/checkout

Step 4. Collect card details.

After inserting a code snippet into the document head, you have two options to collect a card number and make a payment:

Below you will find detailed instructions on how to set up either of those methods.

Pop-up

A pop-up window is the easiest method to accept payments with Revolut. Here is how it looks like:

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

<script>
  RevolutCheckout("TOKEN_XXX").then(function(RC) {
    var payButton = document.getElementById("pay-button");

    // On click open payment pop-up
    payButton.addEventListener("click", function() {
      RC.payWithPopup({
        // (optional) name of the customer
        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: "UK",
          region: "Greater London",
          city: "London",
          streetLine1: "Revolut",
          streetLine2: "1 Canada Square",
          postcode: "EC2V 6DN"
        },
        // (optional) shipping address of the customer
        shippingAddress: {
          countryCode: "UK",
          region: "Greater London",
          city: "London",
          streetLine1: "Revolut",
          streetLine2: "1 Canada Square",
          postcode: "EC2V 6DN"
        },
        // 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>

The shown snippet will open a payment pop-up window when a user decides to click on the payment button. Therefore, we need to create a button and attach a click event listener to it that will trigger RC.payWithPopup(options).

Card Field

Inserting a card field into the check-out page allows you to create a separate field securely accepting card details from the users and to submit payments with the rest of your payment form.

<form id="form">
  <div id="card-input"></div>
  <button>Submit</button>
</form>

<script>
  RevolutCheckout('TOKEN_XXX').then(function(RC) {
    var form = document.getElementById('form')
    var cardInput = document.getElementById('card-input');

    var card = RC.createCardField({
      // empty `<div>` inside your form
      target: cardInput,
      // callback called when payment finished successfully
      onSuccess() {
        window.alert('Thank you!')
      },
      // callback in case error happened
      onError(message) {
        window.alert('Oh no :(')
      },
      // callback in validation status change
      onValidation(messages) {
        console.log(messages) // -> [ 'Your card has expired' ]
      }
      // (optional) Callback in case user cancelled a transaction
      onCancel() {
        window.alert("Payment cancelled!")
      },
      // (optional) see API reference
      styles: {},
      // (optional) see API reference
      classes: {},
    })

    form.addEventListener('submit', function(event) {
      event.preventDefault()

      /**
        Gather additional info from the form if needed
        and submit card number to finish the order
      */

      card.submit({
        // (optional) name of the customer
        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: 'UK',
          region: 'Greater London',
          city: 'London',
          streetLine1: 'Revolut',
          streetLine2: '1 Canada Square',
          postcode: 'EC2V 6DN',
        },
        // (optional) shipping address of the customer
        shippingAddress: {
          countryCode: 'UK',
          region: 'Greater London',
          city: 'London',
          streetLine1: 'Revolut',
          streetLine2: '1 Canada Square',
          postcode: 'EC2V 6DN',
        },
      })
    })
  });
</script>

The snippet shows how we can create a form with a div element in it which will render a card field and then submit a payment.

See card field integration and customisation example.

Once the card details are collected and the payment is authorised, the respective transaction will appear in the transaction list of your Merchant Account section.

For any paid order in the transaction list, you can perform the following actions right in the Merchant section of your Revolut Business account, or you can also trigger these actions via API requests:

Sandbox environment

If you would like to test your Merchant Accounts integration before going into production, we have provided Revolut Business Sandbox environment so that you can do this.

Please create a dummy account on Revolut Business Sandbox environment. Once you have it, please do the following 2 steps:

1. Adjust the endpoints addresses by replacing https://merchant.revolut.com/ with https://sandbox-merchant.revolut.com/ and by using the Sandbox API key in the headers of requests from your back-end. For example:

Create a new order

POST https://sandbox-merchant.revolut.com/api/1.0/orders

Authorization: Bearer <your_Sandbox_API_token>

{
  "amount": 200,
  "currency": "GBP"
}

2. Specify the sandbox environment in the second prameter of the RevolutCheckout.

Sandbox

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

Test with dummy cards

In order for you to be able to test various payment flows, we provide the following dummy card numbers for a variety of scenarios. These cards only work in our Sandbox environment:

Card PAN Response
5185520050000010 FRICTIONLESS_3DS
4111111111111111 FAILED_AUTHORISATION
4012888888881881 FAILED_CAPTURE
5205205205205200 CAN_CANCEL_CAPTURED
378282246310005 FAILED_CANCEL
6011111111111117 FAILED_REFUND
5105105105105100 RISK_DECLINED_CARD

Once you make sure that everything works as expected on Revolut Business Sandbox environment, simply revert back to using https://merchant.revolut.com/ in both back-end requests and the embed script snippet, and replace the Sandbox API key with Production API key in the back-end requests. Now you are ready to accept real card payments!

Wrap-up

To sum up, one can follow the following high-level flow in order to integrate FE and BE:

Read detailed reference to RevolutCheckout.js

Read detailed reference to Back-end API

Browse Integration examples

RevolutCheckout.js reference

Initialize the widget

You have 2 options to add RevolutCheckout.js to your website as:

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>

Embed the following script on all pages that you intend to use RevolutCheckout on. Please note it should be inserted before the code that actually calls RevolutCheckout.

NPM package

Install npm package and import ES module later in your code.

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

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

RevolutCheckout

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

Load the embedded script and create an Instance for the order token.

Parameters

Script load example

RevolutCheckout("XXX", "prod").then(function(instance) {
  // Work with instance:

  // instance.payWithPopup()
  // instance.createCardField()
  // ...
});

Returns Promise with order Instance.

Instance

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

Instance is passed as an argument to the function defined inside RevolutCheckout. It can be used to open a payment pop-up window or to create a card field.

Instance usage example

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

Instance.payWithPopup

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

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

type Options = {
  onSuccess?: () => void;
  onError?: (message: string) => void;
  onCancel?: () => void;
  name?: string;
  email?: string;
  phone?: 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;
  };
};

Options object:

Field Description Format
options.onSuccess Callback when the payment is successfully completed Function
options.onError Callback if transaction is failed to complete, reason should be available in message parameter Function
options.onCancel Callback if a user did not complete the transaction and canceled the authorisation or closed the payment pop-up window Function
options.name Customer name in form of FirstName LastName String
options.email Customer's email String
options.phone Customer's phone number if available String
options.billingAddress Contains customer's billing address which is required if not set on order via API Object
options.billingAddress.countryCode Country code (i.e. GB) String
options.billingAddress.region State, county or region String
options.billingAddress.city Name of the city (i.e. London) String
options.billingAddress.postcode Postal code (i.e. EC2V 6DN) String
options.billingAddress.streetLine1 Address line 1 (i.e. 1 Canada Square) String
options.billingAddress.streetLine2 Address line 2 (optional) String
options.shippingAddress The same object as billingAddress object, however, it is only displayed 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

Minimal required parameters example

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

Minimal required parameters assuming that the billingAddress object is not sent via API.

Minimal example with billingAddress

RevolutCheckout("XXX").then(function(instance) {
  instance.payWithPopup({
    billingAddress: {
      countryCode: "UK",
      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 :(");
    }
  });
});

Full example with all possible parameters.

All possible parameters

RevolutCheckout("XXX").then(function(instance) {
  var popup = instance.payWithPopup({
    name: "First Last",
    email: "customer@example.com",
    phone: "+447950630319",
    billingAddress: {
      countryCode: "UK",
      region: "Greater London",
      city: "London",
      streetLine1: "Revolut",
      streetLine2: "1 Canada Square",
      postcode: "EC2V 6DN"
    },
    shippingAddress: {
      countryCode: "UK",
      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;
  destory: () => void;
};

type Options = {
  target: HTMLElement;
  onSuccess?: () => void;
  onError?: (message: string) => void;
  onValidation?: (messages: string[]) => void;
  onCancel?: () => void;
  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;
  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;
  };
};

Options object:

Field Description Format
options.onSuccess Callback will be called when the payment is completed successfully Function
options.onError Callback if transaction is failed to complete, the reason should be available in the message parameter Function
options.onValidation Callback called on validation of the status change.
Function will contain messages as first parameter (see below)
Function
options.onValidation.messages Array of strings containing validation errors (i.e. Your card has expired) String
options.onCancel Callback if a user did not complete the transaction and canceled the authorisation or closed the checkout window Function
target DOM element where secure iframe with the card field input will be rendered HTML Element
options.styles Object of styles for different state of card field input, should be used to customise different states inside the secure iframe Object
options.styles.default Base styles that will be always applied regardless of state Object
options.styles.focused Applied when a user focuses inside the input with a mouse or a keyboard Object
options.styles.invalid Applied on validation error Object
options.styles.empty Applied when a user hasn't entered any amount Object
options.styles.autofilled Applied when a user used autofilled card details from the browser Object
options.styles.completed Applied if the card field input is completed without any errors Object
options.classes Same as styles but used to apply styles with classes to the target element outside the secure iframe Object
options.classes.default Set default to 'rc-card-field' String
options.classes.focused Set default to 'rc-card-field--focused' String
options.classes.invalid Set default to 'rc-card-field--invalid' String
options.classes.empty Set default to 'rc-card-field--empty' String
options.classes.autofilled Set default to 'rc-card-field--autofilled' String
options.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 entered and complete the payment with additional customer meta data. Accepts a single meta parameter (see below) Function
methods.validate Manually trigger validation, by default it will be only triggered after user will start entering card details and on submit Function

Meta object:

Field Description Format
meta.name Customer name in the form of FirstName LastName String
meta.email Customer's email (required if not set on the order via API) String
meta.phone Customer's phone number if available String
meta.billingAddress Customer's billing address (required if not set on order via API) Object
meta.billingAddress.countryCode Country code (i.e. GB) String
meta.billingAddress.region State, county or region String
meta.billingAddress.city Name of the city (i.e. London) String
meta.billingAddress.postcode Postal code (i.e. EC2V 6DN) String
meta.billingAddress.streetLine1 Address line 1 (i.e. 1 Canada Square) String
meta.billingAddress.streetLine2 Address line 2 (optional) String
meta.shippingAddres Same as meta.billingAddress, but only used to display in the order details on merchant dashboard Object

Examples

Minimal required parameters example

HTML

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

JS

RevolutCheckout("XXX").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();
    });
});

Minimal required parameters example, assuming billingAddress and email 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("XXX").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 :(");
    }
  });

  form.addEventListener("submit", function(event) {
    // Prevent browser form submittion. 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 card field integration and customisation example.

API

Introduction

Merchant API allows Revolut Business customers to accept online (Card Not Present) payments made with debit/credit cards, and, subsequently, to manage these transactions by means of capturing, canceling or refunding orders.

All merchant requests should contain an authorisation header which includes the name of the merchant account Bearer and the MERCHANT_API_KEY.

You can generate the MERCHANT_API_KEY on a merchant portal. In order to do so, please proceed to the Merchant tab in your Revolut Business app, click on the API menu option, and you will find the MERCHANT_API_KEY under the section called Production API key.

Screenshot 2020-02-10 at 15 43 13

All requests and responses should have a JSON format.

Authorization

curl
--header 'authorization: Bearer AUTHORIZATION_TOKEN'
--header 'content-type: application/json'

Order object

An Order object helps you through the process of accepting payments from your customers.

You are advised to create an Order for every customer session or order being created in your own system. An Order will then go through multiple status as it interfaces with the Revolut Checkout Widget to collect payments from your customers. An Order can have at most one successful payment.

Order object:

Order example

{
  "id": "6a1353a8-3054-40ee-ab39-97a11e4c5f2a",
  "public_id": "b9dd41ee-c6ef-4f3f-983d-18b6136219a0",
  "type": "PAYMENT",
  "state": "PENDING",
  "created_at": 2020-05-12T14:22:01.046526Z,
  "updated_at": 2020-05-12T14:23:11.046526Z,
  "completed_at": 2020-05-12T14:23:11.046526Z,
  "order_amount": {
    "value": 10000,
    "currency": "GBP"
  },
  "merchant_order_ext_ref": "00122",
  "merchant_customer_ext_ref": "sally01",
  "email": "customer@gmail.com",
  "settled_amount": {
    "value": 100,
    "currency": "GBP"
  },
  "refunded_amount": {
    "value": 100,
    "currency": "GBP"
  },
  "fees": [
    {
      "value": 100,
      "currency": "GBP",
      "type": "ACQUIRING"
    }
  ],
  "payments": [
    {
      "type": "card",
      "amount": {
        "value": 10000,
        "currency": "GBP"
      },
      "created_at": 2020-05-12T14:22:01.046526Z,
      "updated_at": 2020-05-12T14:23:11.046526Z,
      "completed_at": 2020-05-12T14:23:11.046526Z,
      "card": {
        "card_type": "VISA",
        "funding": "CREDIT",
        "card_bin": "5185",
        "card_last_four": "0010",
        "card_expiry": "12/30",
        "cardholder_name": "Johann Smith",
        "checks": {
          "three_ds": {
            "state": "CHALLENGE",
            "version": 2
          },
          "authorization_code": "HOSTOK",
          "cvv_verification": "MATCH"
        },
        "risk_level": "LOW",
        "billing_address": {
          "street_line_1": "205",
          "street_line_2": "10 Downing Street",
          "region": "Greater London",
          "city": "London",
          "country_code": "UK",
          "postcode": "XY14 2LG"
        }
      }
    }
  ],
  "attempts": [
    {
      "id": "530f8f46-bf5d-447e-bc80-ca9cf33a5052",
      "type": "REFUND",
      "amount": {
        "value": 10000,
        "currency": "GBP"
      }
    }
  ],
  "related": [
    {
      "id": "4695b666-45d0-4f15-ad10-e66a84c914bf",
      "type": "REFUND",
      "amount": {
        "value": 100,
        "currency": "GBP"
      }
    }
  ],
  "shipping_address": {
    "street_line_1": "195",
    "street_line_2": "100 Rural Drive",
    "region": "Greater London",
    "city": "London",
    "country_code": "UK",
    "postcode": "E115AB"
  },
  "phone": "+44 20 7234 3456"
}
Field Description Format
id Permament order ID used to perform actions with the orders beyond authorisation: retrieve, capture, cancel, or refund UUID
public_id Temporary ID for a customer's order - expires once the payment is authorised UUID
type Order type: PAYMENT, REFUND or CHARGEBACK Text
state Order state: PENDING, PROCESSING, AUTHORISED, COMPLETED or FAILED Text
created_at Creation date for an order ISO-8601
updated_at Last update date for an order (optional) ISO-8601
completed_at Completion date for an order (optional) ISO-8601
order_amount.value Order minor amount Integer
order_amount.currency Order currency ISO-4217
merchant_order_ext_ref Merchant order ID (optional) Text
merchant_customer_ext_ref Merchant customer ID (optional) Text
email Customer email (optional) Email
settled_amount.value Settled amount (optional - only for settled orders) Integer
settled_amount.currency Optional settlement currency (optional - only for settled orders) ISO-4217
refunded_amount.value Refunded minor amount (optional - only for refunded orders) Integer
refunded_amount.currency Refunded order currency (optional - only for refunded orders) ISO-4217
fees[n].value Fee amount (optional) Integer
fees[n].currency Fee currency (optional) ISO-4217
fees[n].type Fee type: FX or ACQUIRING (optional) Text
payments.type Payment type: Card (optional - only for orders with successful payments) Text
payments.amount.value Payment minor amount (optional - only for orders with successful payments) Integer
payments.amount.currency Payment currency (optional - only for orders with successful payments) ISO-4217
payments.created_at Payment created date (optional - only for orders with successful payments) ISO-8601
payments.updated_at Last update date (optional - only for orders with successful payments) ISO-8601
payments.completed_at Payment completion date (optional - only for orders with successful payments) ISO-8601
payments.card.card_type Card type: VISA or MASTERCARD (optional - only for orders with successful payments) Text
payments.card.funding Card funding: CREDIT, DEBIT or PREPAID (optional - only for orders with successful payments) Text
payments.card.card_bin Card BIN (optional - only for orders with successful payments) Text
payments.card.card_last_four Card last four digits (optional - only for orders with successful payments) Text
payments.card.card_expiry Card expiry date in the format of MM/YY (optional - only for orders with successful payments) Text
payments.card.cardholder_name Cardholder name (optional - only for orders with successful payments) Text
payments.card.proxy Confirms whether a proxy number is used or not (optional - only for orders with successful payments) Boolean
payments.card.vpn Confirms whether a VPN connection is used or not (optional - only for orders with successful payments) Boolean
payments.card.country_by_ip Country name associated with the IP address of the card used (optional - only for orders with successful payments) Text
payments.card.checks.three_ds.state 3DS check result: VERIFIED, FAILED or CHALLENGE (optional - only for orders with successful payments) Text
payments.card.checks.three_ds.version 3DS version (optional - only for orders with successful payments) Integer
payments.card.checks.authorization_code Authorization code returned by the processor (optional - only for orders with successful payments) Text
payments.card.checks.cvv_verification CVV verification: MATCH, NOT_MATCH, INCORRECT or NOT_PROCESSED (optional - only for orders with successful payments) Text
payments.card.checks.address Address verification: MATCH, NOT_MATCH, N_A or INVALID (optional - only for orders with successful payments) Text
payments.card.checks.postcode Postcode verification: MATCH, NOT_MATCH, N_A orINVALID (optional - only for orders with successful payments) Text
payments.card.checks.cardholder Cardholder verification: MATCH, NOT_MATCH, N_A orINVALID (optional - only for orders with successful payments) Text
payments.card.risk_level Card risk level: LOW, HIGH (optional - only for orders with successful payments) Text
payments.card.billing_address.street_line_1 Street line 1 information (optional - only for orders with successful payments) Text
payments.card.billing_address.street_line_2 Street line 2 information (optional - only for orders with successful payments) Text
payments.card.billing_address.region Region name (optional - only for orders with successful payments) Text
payments.card.billing_address.city City name (optional - only for orders with successful payments) Text
payments.card.billing_address.country_code Country associated with the address (optional - only for orders with successful payments) Alpha-2
payments.card.billing_address.postcode Postcode associated with the address (optional - only for orders with successful payments) Text
attempts[n].id ID of any attempted, but unsuccessful transactions (optional) UUID
attempts[n].type Type of any attempted, but unsuccessful transactions: PAYMENT, REFUND or CHARGEBACK (optional) Text
attempts[n].amount.currency Minor currency of any attempted, but unsuccessful transactions (optional) ISO-4217
attempts[n].amount.value Value of any attempted, but unsuccessful transactions (optional) Integer
related[n].id Related transaction ID (optional) UUID
related[n].type Related order type: PAYMENT, REFUND or CHARGEBACK (optional) Text
related[n].amount.currency Related transaction minor currency (optional) ISO-4217
related[n].amount.value Related transaction value (optional) Integer
shipping_address.street_line_1 Shipping address: Street line 1 information (optional) Text
shipping_address.street_line_2 Shipping address: Street line 2 information (optional) Text
shipping_address.region Shipping address: Region name (optional) Text
shipping_address.city Shipping address: City name (optional) Text
shipping_address.country_code Shipping address: Country associated with the address (optional) Alpha-2
shipping_address.postcode Shipping address: Postcode associated with the address (optional) Text

Create an Order

The following request creates an Order object.

Request

POST /api/1.0/orders

{
  "amount": 200,
  "capture_mode": "MANUAL",
  "merchant_order_ext_ref": "00122",
  "customer_email": "sally.gibson@gmail.com",
  "description": "description",
  "currency": "GBP",
  "settlement_currency": "USD",
  "merchant_customer_ext_ref": "sally01"
}

Request in cURL

curl -X "POST" "https://merchant.revolut.codes/api/1.0/orders" \
     -H 'Authorization: Bearer fh-WBDEX_b02ISLvL_iEfd-YpKVVYNzNCFmmBoWWvEvH_Ch7xFa9txqHP0w06tHw' \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d $'{
  "amount": 200,
  "capture_mode": "MANUAL",
  "merchant_order_ext_ref": "00122",
  "customer_email": "sally.gibson@gmail.com",
  "description": "description",
  "currency": "GBP",
  "settlement_currency": "USD",
  "merchant_customer_ext_ref": "sally01"
}'
Field Description Format
amount Minor amount Integer
capture_mode Capture mode: AUTOMATIC or MANUAL (optional - if it is not specified, then AUTOMATIC is used) Text
merchant_order_ext_ref Merchant order ID (optional) Text
customer_email Customer email (optional) Email
description Order description (optional) Text
currency Currency code ISO-4217
settlement_currency Settlement currency (optional - if it is not specified, then the payment is settled in transaction currency) ISO-4217
merchant_customer_ext_ref Merchant customer ID (optional) Text

Response

Order object

Retrieve an Order

Request

GET /api/1.0/orders/:ORDER_ID

Request in cURL

curl "https://merchant.revolut.codes/api/1.0/orders/6e1c0aa4-cb88-4be8-ab8d-4b9f21c64a68" \
     -H 'Authorization: Bearer fh-WBDEX_b02ISLvL_iEfd-YpKVVYNzNCFmmBoWWvEvH_Ch7xFa9txqHP0w06tHw'

Response

Order object

The following request retrieves the details of an Order that has been created.

Capture an Order

Request

POST /api/1.0/orders/:ORDER_ID/capture

Request in cURL

curl -X "POST" "https://merchant.revolut.codes/api/1.0/orders/6e1c0aa4-cb88-4be8-ab8d-4b9f21c64a68/capture" \
     -H 'Authorization: Bearer fh-WBDEX_b02ISLvL_iEfd-YpKVVYNzNCFmmBoWWvEvH_Ch7xFa9txqHP0w06tHw'

Response

Order object

The following request captures the funds of an existing uncaptured Order.

When the payment for a particular Order is authorised, it needs to be captured in order for it to be sent into the processing stage.

As a merchant, you can choose between automatic or manual capturing.

Cancel an Order

Request

POST /api/1.0/orders/:ORDER_ID/cancel

Request in cURL

curl -X "POST" "https://merchant.revolut.codes/api/1.0/orders/6e1c0aa4-cb88-4be8-ab8d-4b9f21c64a68/cancel" \
     -H 'Authorization: Bearer fh-WBDEX_b02ISLvL_iEfd-YpKVVYNzNCFmmBoWWvEvH_Ch7xFa9txqHP0w06tHw'

Response

Order object

The following request cancels an existing uncaptured Order.

Refund an Order

This request issues a refund for a completed Order. A refund can be either full or partial. Funds are always refunded to customer's original payment method.

Request

POST /api/1.0/orders/:ORDER_ID/refund

{
  "amount": 100,
  "currency": "GBP",
  "merchant_order_ext_ref": "00122",
  "description": "description"
}

Request in cURL

curl -X "POST" "https://merchant.revolut.codes/api/1.0/orders/6e1c0aa4-cb88-4be8-ab8d-4b9f21c64a68/refund" \
     -H 'Authorization: Bearer fh-WBDEX_b02ISLvL_iEfd-YpKVVYNzNCFmmBoWWvEvH_Ch7xFa9txqHP0w06tHw' \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d $'{
  "amount": 100,
  "currency": "GBP",
  "merchant_order_ext_ref": "00122",
  "description": "descr"
}'

Field Description Format
amount Minor amount Integer
currency Currency code ISO-4217
merchant_order_ext_ref Merchant order ID (optional) Text
description Refund description (optional) Text

If the refund is successful, a Refund Order object is returned, otherwise an error is returned.

Response

{
  "id": "6a1353a8-3054-40ee-ab39-97a11e4c5f2a",
  "type": "REFUND",
  "state": "COMPLETED",
  "created_at": 2020-05-12T14:23:11.046526Z,
  "updated_at": 2020-05-12T14:23:11.046526Z,
  "completed_at": 2020-05-12T14:23:11.046526Z,
  "order_amount": {
    "value": 10000,
    "currency": "GBP"
  },
  "merchant_customer_ext_ref": "sally01",
  "email": "customer@gmail.com",
  "related": [
    {
      "id": "4695b666-45d0-4f15-ad10-e66a84c914bf",
      "type": "REFUND",
      "amount": {
        "value": 100,
        "currency": "GBP"
      }
    }
  ]
}
Field Description Format
id Order ID for a merchant UUID
type Order type: REFUND Text
state Order state: PENDING, PROCESSING, AUTHORISED, COMPLETED, FAILED Text
created_at Сreation date for a refund order ISO-8601
updated_at Last update date for a refund order (optional) ISO-8601
completed_at Order completion date for a refund order (optional) ISO-8601
order_amount.value Order minor amount Integer
order_amount.currency Order currency ISO-4217
merchant_customer_ext_ref Merchant customer ID (optional) Text
email Customer email (optional) Email
related[n].id Related transaction ID (optional) UUID
related[n].type Related order type: PAYMENT, REFUND, CHARGEBACK (optional) Text
related[n].currency Related transaction minor currency (optional) Integer
related[n].value Related transaction currency (optional) ISO-4217

Webhooks

There are multiple events happening to Merchant Accounts. The majority of these occur synchronously - this means they arrive instantly and an immediate result is available. For example, an Order creation request is a synchronous request.

However, there are some events that run asynchronously and, therefore, require webhooks. Merchant API supports webhooks for order completion events.

Set webhook url

This request can be used by a merchant to subscribe for webhooks from Revolut Merchant API.

Request

POST /api/1.0/webhooks

{
  "url": "http://your-company.com/webhook"
}
Field Description Format
url valid URL to set, null to revoke URL

Response

{
  "url": "http://your-company.com/webhook"
}
Field Description Format
url valid URL if set, else null URL

Retrieve webhooks

This request is used to get the list of webhooks you are currently subscribed to.

Request

GET /api/1.0/webhooks

Response

[
  {
    "url": "http://your-company.com/webhook"
  }
]
Field Description Format
url valid URL if set, else null URL

Webhook request

Revolut will POST webhook messages to the URLs you have set webhooks for. Here is an example of an order completion event.

Request

POST http://your-company.com/webhook

Message

{
  "order_id": "4ee2a044-4965-4617-96e7-9debea935dfc"
}
Field Description Format
order_id Order ID of a completed order UUID

Integration examples

Payment pop-up integration: React.js + Next.js

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

Please note that 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

Card field integration and customisation

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

Please note that 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.

More examples are coming soon.

Plugins

Using various e-commerce platform plugins is a simple way for you to start accepting payments straight into Revolut Merchant Accounts without having to integrate with Revolut Backend API.

Make sure that you apply for a Merchant Account first and get your application approved by our team. Once it is approved, you can start installing and configuring any of Revolut Gateway plugins available.

WooCommerce

Revolut WooCommerce plugin lets you accept online card payments via your WooCommerce e-store - in an easy and hassle-free fashion. The following guide will help you install and configure Revolut WooCommerce plugin.

Installation

Step 1. Log in to the admin section of your WooCommerce webstore.

Step 2. On the menu on the left hand side of the page, go the the Plugins section.

Step 3. At the very top of the page, click on Add New button next to the plugins page title.

Step 4. You will be redirected to the following page:

Click on Upload Plugin button next to the Add Plugins page title.

Step 5. Download the following Woocommerce-Revolut-Gateway.zip file and upload it on this page:

Step 6. Once the installation of the Revolut WooCommerce plugin is successfully finished, you can go ahead and click on the Activate Plugin button.

Step 7. Congrats! You have just activated the Revolut WooCommerce plugin. You'll be automatically redirected to the page with all the plugins you have installed.

Configuration

Step 1. Testing the WooCommerce Revolut Gateway plugin:

In the admin settings of your WooCommerce shop, under WooCommerce Revolut Gateway plugin, click Settings. You will land on the following page:

Make sure you perform the following actions to enable test mode:

Step 2. Using WooCommerce Revolut Gateway plugin in production environment:

Go back to the admin settings of your WooCommerce shop and under WooCommerce Revolut Gateway plugin click Settings.

Make sure you perform the following actions to enable payments in production environment:

Errors

The API uses the following error codes:

CODE MEANING
400 Bad Request -- Your request is invalid.
401 Unauthorized -- Your access token is wrong.
403 Forbidden -- Access to the requested resource or action is forbidden.
404 Not Found -- The requested resource could not be found.
405 Method Not Allowed -- You tried to access an endpoint with an invalid method.
406 Not Acceptable -- You requested a format that isn't JSON.
429 Too Many Requests -- You're sending too many requests.
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.