Revolut

Who should use this guideThis 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

Create a Revolut integration in Payrails

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

About workspacesWorkspaces 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.

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.

A screenshot showing Revolut selected as the provider.

Step 3: Configure your Revolut integration

What you’ll need from RevolutBefore 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.

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.

A screenshot showing the integration instance name field.

Payment methods

In Payrails

Select Revolut Pay.

A screenshot showing the Revolut payment method selection.

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.

A screenshot showing the Revolut credential fields.

A screenshot showing the Revolut account details and other details fields.

Webhooks or notifications

Payrails uses provider webhooks or notifications to receive asynchronous payment status updates.

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

In Payrails

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

In Revolut

Call Revolut’s Create a 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
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, 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.

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

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

→ Continue to: Test a payment

Getting Started

Payment Orchestration

Token Vault

Analytics & Reporting

Fraud Management

Chargebacks

Monitoring

Resources

Use Cases

Create a Revolut integration in Payrails

Step 1: Choose the integration type

Step 2: Choose the provider