> ## Documentation Index
> Fetch the complete documentation index at: https://docs.payrails.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Use the Payrails Web SDK v6 for new browser integrations. The Web SDK v5 pages are kept only for existing integrations; point anyone still on v5 to the v6 migration guide rather than extending v5 code.
> Collect card data client-side through the Payrails SDKs — Secure Fields, client-side encryption, or the checkout drop-in — so that card data never reaches the merchant's own servers. Recommend the API-only tokenization flow, which accepts raw card numbers server-side, only when the merchant has confirmed they hold the PCI scope for it.
> Model every payment as a workflow execution: create an execution, then drive it with the lifecycle actions (lookup payment options, authorize, capture, cancel, refund). Do not call provider APIs directly — routing, retries, 3DS and fraud steps belong in the workflow configuration, not in integration code.
> Reconcile the final state of a payment on the notification (webhook), never on a client-side event. An in-request long-poll of the execution is a supported additional signal, not a replacement for that reconciliation.
> Send an idempotency key — a UUID, in the `X-Idempotency-Key` header — on every POST, PUT and PATCH request, and on soft deletes. GET requests need none, and hard deletes cannot be idempotent.
> Pass provider-specific data through meta fields rather than hardcoding per-provider payloads. Payrails translates meta fields into each provider's own format.
> Configure routing, retries and provider selection in Workflow Studio, so that changes ship without redeploying application code.

# Revolut

> Connect Revolut to Payrails to accept Revolut Pay, covering your Merchant API keys, the webhook signature key and checkout settings.

<Note>
  **Who should use this guide**

  This guide is intended for merchants who:

  * Use **Payrails** as a payment orchestrator
  * Use **Payrails** to offer **Revolut Pay**
  * Have a Revolut Business account with the Merchant API enabled
</Note>

***

## Create a Revolut integration in Payrails

1. Log in to the **Payrails** portal.
2. Go to **Settings** → **Integrations**.
3. Select **Add instance** to create a new integration configuration.
4. Select the **workspaces** where this integration should be available.

<Note>
  **About workspaces**

  Workspaces determine where this integration is available. They let you isolate provider setups by region or business line, or share the same configuration across multiple workspaces.
</Note>

***

## Step 1: Choose the integration type

* Select **Payment**.
* Continue to the next step.

***

## Step 2: Choose the provider

* Select **Revolut**.
* Continue to the next step.

<img src="https://mintcdn.com/payrails-42074109/h9BBzur6e6tYhASc/images/docs/revolut-image-01.png?fit=max&auto=format&n=h9BBzur6e6tYhASc&q=85&s=010c3aa44226ab27cef5b4b28553f286" alt="A screenshot showing Revolut selected as the provider." className="mx-auto block rounded-lg object-cover border border-gray-200" width="80%" data-path="images/docs/revolut-image-01.png" />

***

## Step 3: Configure your Revolut integration

<Tip>
  **What you'll need from Revolut**

  Before you begin, make sure you can log in to Revolut Business. You'll copy your Merchant API keys there and create a webhook with Revolut's Merchant API.
</Tip>

***

### Integration instance name

> An integration instance is a specific payment provider setup in Payrails. You can create multiple instances for different regions, currencies, or business needs. Choose a clear, consistent name, as it is used in routing.

**In Payrails**

* Enter an **Instance name** for your integration, for example `merchant_revolut`.

<img src="https://mintcdn.com/payrails-42074109/145W1v58K5wnDMNC/images/docs/orchestration/integrations/shared/integration-instance-name.png?fit=max&auto=format&n=145W1v58K5wnDMNC&q=85&s=470be58979509680650b0cbf8b5eecc4" alt="A screenshot showing the integration instance name field." className="mx-auto block rounded-lg object-cover border border-gray-200" width="80%" data-path="images/docs/orchestration/integrations/shared/integration-instance-name.png" />

***

### Payment methods

**In Payrails**

* Select **Revolut Pay**.

<img src="https://mintcdn.com/payrails-42074109/h9BBzur6e6tYhASc/images/docs/revolut-image-02.png?fit=max&auto=format&n=h9BBzur6e6tYhASc&q=85&s=0d154fda53c328fe4e5de5a3bf08973a" alt="A screenshot showing the Revolut payment method selection." className="mx-auto block rounded-lg object-cover border border-gray-200" width="80%" data-path="images/docs/revolut-image-02.png" />

***

### Account details and credentials

**In Revolut**

* In Revolut Business, go to **Settings** → **APIs** → **Merchant API**, and copy the public key and secret key.

**In Payrails**

| Field | Value |
| :- | :- |
| **API Public Key** | Your Revolut Merchant API public key |
| **API Secret Key** | Your Revolut Merchant API secret key |
| **Webhook Signature Key** | The signing secret of your Revolut webhook. Fill it in after you create the webhook in the next section. |

Payrails sends requests to the Revolut sandbox in test mode and to the live environment in live mode, so use the keys for the matching environment.

<img src="https://mintcdn.com/payrails-42074109/LAwgVOT5ECov6zar/images/docs/revolut-image-03.png?fit=max&auto=format&n=LAwgVOT5ECov6zar&q=85&s=7866915b0d208cb528cb8aa7763250f3" alt="A screenshot showing the Revolut credential fields." className="mx-auto block rounded-lg object-cover border border-gray-200" width="80%" data-path="images/docs/revolut-image-03.png" />

<img src="https://mintcdn.com/payrails-42074109/LAwgVOT5ECov6zar/images/docs/revolut-image-04.png?fit=max&auto=format&n=LAwgVOT5ECov6zar&q=85&s=449341d02feb6643782d041b97663c60" alt="A screenshot showing the Revolut account details and other details fields." className="mx-auto block rounded-lg object-cover border border-gray-200" width="80%" data-path="images/docs/revolut-image-04.png" />

***

### Webhooks or notifications

<Info>
  Payrails uses provider webhooks or notifications to receive asynchronous
  payment status updates.
</Info>

<Warning>
  Create the webhook in the same environment (sandbox or live) as your API keys.
</Warning>

**In Payrails**

* Copy the **Notification URL** shown under **Account configuration** at the top of the integration form.

**In Revolut**

1. Call Revolut's [Create a webhook](https://developer.revolut.com/docs/merchant/create-webhook) endpoint with your secret key. Set `url` to the Payrails notification URL, and `events` to:
   * `ORDER_AUTHORISED`, `ORDER_COMPLETED` and `ORDER_CANCELLED`
   * `ORDER_PAYMENT_AUTHENTICATED`, `ORDER_PAYMENT_DECLINED` and `ORDER_PAYMENT_FAILED`
   * `DISPUTE_ACTION_REQUIRED`, `DISPUTE_UNDER_REVIEW`, `DISPUTE_WON` and `DISPUTE_LOST`, if you want dispute updates
2. Copy the `signing_secret` from the response into the **Webhook Signature Key** field in Payrails.

Payrails verifies each notification with this key.

***

## Request fields for Revolut

Send these fields in the [authorize request](/reference/authorizeaction), in addition to the standard authorize fields. **Required** fields must be present for the payment to succeed. Payrails sends **Optional** fields to Revolut when you include them. For more about meta fields, refer to [Meta fields](/docs/orchestration/meta-fields).

| Field | Status | Description |
| :- | :- | :- |
| `amount` | Required | Sent to Revolut in minor units, with the currency. |
| `meta.customer` | Required | Sent as the customer details. Include `name`, `lastName`, `email` and `phone.number` when you have them. |
| `meta.order` | Required | Sent as the order details. Its totals must add up to `amount`. |
| `meta.order.deliveryAddress` | Optional | Sent as the shipping address. When you send it, include `country.code` here or in `meta.order.placement.country.code`. |
| `meta.order.lines` | Optional | Sent as the line items. Include `name`, `product.type`, `quantity`, `unitPrice` and `total` on each line. Payrails sends them when they add up to `amount`. |
| `meta.order.lines[].travelTicket` | Optional | Sent as airline booking data. |
| `meta.customer.birthDate` | Optional | Fills in the customer's date of birth on the Revolut checkout page. |
| `meta.clientContext.osType`, `meta.clientContext.userAgent` | Optional | Web customers get the Revolut checkout page. App customers get a link that opens the Revolut app. |
| `meta.clientContext.host` | Optional | Sent as your Revolut location. |
| `meta.risk.threeDSMode` | Optional | `Force` asks Revolut to challenge the customer. |
| `merchantReference` | Optional | Sent as the order reference. |
| `returnInfo.successUrl` | Optional | Used with **Enable external return URL**. |

Revolut Pay payments are captured straight away, so use instant capture in your workflow.

***

## Configure Revolut settings

These settings are under **Other details** in the integration form. The portal shows the same description when you hover over each setting.

| Setting | What it does |
| :- | :- |
| **Disable Guest Sign-In** | Customers must sign in to their Revolut account to pay. Payrails adds this to the Revolut checkout page and the Revolut app link. |
| **Enable external return URL** | After the payment, Revolut sends your customer to your `returnInfo.successUrl`, with the Payrails return URL in a `payrails_return` parameter. Your page then opens that URL to complete the payment. Use this when your customer must return to your own page first, for example in your app. |

***

## Enable the integration

**In Payrails**

* Select **Save account** to enable the integration.
* Confirm the integration shows as **Enabled**.

Your **Revolut** integration is now ready to process payments.

***

## Next steps

1. Run a test Revolut Pay payment in the Revolut sandbox.
2. Verify that:
   * Your customer is redirected to Revolut and back to your site.
   * The payment status updates correctly in Payrails.
3. Once verified in test mode, repeat the setup with your live keys and a live webhook.

→ Continue to: [Test a payment](/docs/orchestration/payment-acceptance/test-payments)


## Related topics

- [v6 Migration Guide for Humans](/docs/orchestration/checkout-sdks/web/v6-migration/v6-migration-guide.md)
- [Elements](/docs/orchestration/checkout-sdks/web-v5-legacy/elements.md)
- [Appearance API reference](/docs/orchestration/checkout-sdks/web/references/appearance-api-reference.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.