Revolut Other API
Other operations that can be done with the Merchant API.
OpenAPI Specification
openapi: 3.0.1
info:
version: '1.0'
title: Business Accounting Other API
description: "As a Revolut Business customer with a Business Account, you can use the Business API to automate your own business processes.\nSave time, reduce your costs, and avoid errors by using the Business API. \n\n:::tip[Before you get started]\nTo learn more about the Business API and its features, check the [**user guides**](https://developer.revolut.com/docs/guides/manage-accounts/introduction).\n\nYou can reach them at any time from the main navigation bar **→ Guides → Business**.\n:::\n\nYou can view accounts, manage counterparties, make payments or currency exchanges without manual effort in the Web UI:\n\n- Accounting: [Account management](https://developer.revolut.com/docs/api/business#get-account), [Accounting settings](https://developer.revolut.com/docs/api/business#tag-accounting), [Expense management](https://developer.revolut.com/docs/api/business#get-expense), [Transactions](https://developer.revolut.com/docs/api/business#get-transactions) \n- Payments: \n - [Counterparty management](https://developer.revolut.com/docs/api/business#get-counterparties)\n - Payment management: [Payment drafts](https://developer.revolut.com/docs/api/business#delete-payment-draft), [Payout links](https://developer.revolut.com/docs/api/business#get-payout-link), [Transfers](https://developer.revolut.com/docs/api/business#tag-transfers)\n - [Foreign exchange](https://developer.revolut.com/docs/api/business#tag-foreign-exchange)\n- Business team: [Card management](https://developer.revolut.com/docs/api/business#delete-card), [Card invitation management](https://developer.revolut.com/docs/api/business#update-card-invitation), [Team member management](https://developer.revolut.com/docs/api/business#delete-team-member)\n- Developer tools: [Sandbox simulations](https://developer.revolut.com/docs/api/business#tag-simulations), [Webhook management](https://developer.revolut.com/docs/api/business#tag-webhooks-v2)\n\nTo see the reference for the specific endpoints and operations of this API, browse the menu on the left.\n\n### Test the Business API\n\nYou can test the Business API in Postman by forking this collection:\n\n[](https://www.postman.com/revolut-api/workspace/revolut-developers/overview)"
contact: {}
servers:
- url: https://b2b.revolut.com/api/1.0
description: Production server (uses live data)
- url: https://sandbox-b2b.revolut.com/api/1.0
description: Sandbox server (uses test data)
tags:
- name: Other
description: Other operations that can be done with the Merchant API.
paths:
/api/synchronous-webhooks:
parameters:
- $ref: '#/components/parameters/Authorization'
post:
summary: Register address validation endpoint for Fast checkout
operationId: registerAddressValidationEndpoint
description: "Use this endpoint to register a URL where Revolut can send shipping address(es) from a Revolut Pay customer for validation during the [Fast checkout\nprocess](https://developer.revolut.com/docs/guides/merchant/optimise-checkout/fast-checkout).\n\nRevolut Pay can support Fast checkout for delivering goods. Once your customer selects a shipping address, Revolut needs to validate if the merchant (or their shipping partner) delivers to the address provided. This is done by contacting the merchant's backend and asking for such validation and information.\n\nIn order for your backend to support Fast checkout, you need to:\n\n1. Register an URL to handle address validation\n1. Validate the shipping address sent to your backend\n1. Respond with a JSON object containing the result of the validation\n\nAdditionally, Revolut Pay can support multiple webhooks if you have multiple stores. For more information, see:\n - [Manage multiple stores with Fast checkout](https://developer.revolut.com/docs/guides/merchant/optimise-checkout/fast-checkout#manage-multiple-stores-with-fast-checkout)\n - [Merchant API: Locations](https://developer.revolut.com/docs/api/merchant#tag-locations)\n\n:::note\nTo set up a webhook for tracking order completion, failure, error, etc. events, use the [Webhooks endpoints](https://developer.revolut.com/docs/api/merchant#tag-webhooks).\n:::"
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Synchronous-Webhook-Creation'
examples:
create_webhook:
summary: Create synchronous webhook
value:
event_type: fast_checkout.validate_address
url: https://backend.example.com/webhooks/validate-address
create_webhook_with_location_id:
summary: Create synchronous webhook with location ID
value:
event_type: fast_checkout.validate_address
url: https://backend.example.com/webhooks/validate-address
location_id: 8d9a7125-805f-40f3-a405-bc89765db996
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Synchronous-Webhook'
examples:
example_without_location:
summary: Synchronous webhook response
value:
id: f6abc4df-eb48-417c-8e75-f7c6d7ad394f
signing_key: swsk_y5z3LEHYZ9ndote3qegzWD6uL4t1lfp1
url: https://backend.example.com/webhooks/validate-address
event_type: fast_checkout.validate_address
example_with_location:
summary: Synchronous webhook response with location ID
value:
id: f6abc4df-eb48-417c-8e75-f7c6d7ad394f
signing_key: swsk_y5z3LEHYZ9ndote3qegzWD6uL4t1lfp1
url: https://backend.example.com/webhooks/validate-address
event_type: fast_checkout.validate_address
location_id: b0ebede4-5cbc-4951-977f-70329faa8769
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorized
security:
- Api-Key: []
tags:
- Other
get:
summary: Retrieve a synchronous webhook list
operationId: retrieveSynchronousWebhookList
description: 'Retrieve a list of synchronous webhook objects.
You can use this endpoint to see your different address validation endpoints registered to different locations.
:::info
For more information about locations, see: [Merchant API: Locations](https://developer.revolut.com/docs/api/merchant#tag-locations).
:::'
responses:
'200':
description: Synchronous webhook list returned
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Synchronous-Webhook'
examples:
example_without_location:
summary: List of synchronous webhooks
value:
- id: f6abc4df-eb48-417c-8e75-f7c6d7ad394f
signing_key: swsk_y5z3LEHYZ9ndote3qegzWD6uL4t1lfp1
url: https://example.com/webhooks/validate-address
event_type: fast_checkout.validate_address
- id: 5c08dcc1-cd60-4b7d-a255-e42d24d7365c
signing_key: swsk_VsuFcq6FIpa9gOWUu0n2WxiCbsDHIJlN
url: https://groceries.example.com/webhooks/validate-address
event_type: fast_checkout.validate_address
location_id: b0ebede4-5cbc-4951-977f-70329faa8769
- id: dbebe6f8-4c47-4176-a94f-576d76e1d0b6
signing_key: swsk_0TKYlzoakBgGGVvojCiRRqInMD1ufLZn
url: https://clothes.example.com/webhooks/validate-address
event_type: fast_checkout.validate_address
location_id: 6ebd3d2b-7a51-42e4-84f4-3c513621edd3
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorized
security:
- Api-Key: []
tags:
- Other
/api/synchronous-webhooks/{synchronous_webhook_id}:
parameters:
- $ref: '#/components/parameters/Authorization'
- $ref: '#/components/parameters/Synchronous-Webhook-Id'
delete:
summary: Delete a synchronous webhook
operationId: deleteSynchronousWebhook
description: Delete a specific synchronous webhook registration, based on its ID.
responses:
'204':
description: Synchronous webhook deleted
'401':
description: Unauthorized
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
security:
- Api-Key: []
tags:
- Other
components:
schemas:
Synchronous-Webhook:
title: SynchronousWebhook
type: object
properties:
id:
type: string
format: uuid
description: The ID of the synchronous webhook object.
signing_key:
type: string
pattern: ^swsk_[a-zA-Z0-9]{32}$
description: 'A randomly generated signing key, which can be used by merchants to authenticate requests from Revolut by verifying the signature. For more information, see: [Payload Signature](https://developer.revolut.com/docs/api/merchant#authentication).'
url:
type: string
format: uri
pattern: ^https:\/{2}.+/gi
maxLength: 2000
description: 'The valid URL of the endpoint, that uses HTTPS URL schema. Revolut sends the shipping address of the customer to this URL for validation.
:::warning
Restrictions:
- Must be a valid URI as defined by [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986)
- URI scheme is required and must be `https`
- URI host is required and cannot be `localhost` or an IP address
- Max length: `2000`
- Reserved or invalid characters must be percent-encoded (for example, use `%20` instead of a space)
:::'
event_type:
type: string
enum:
- fast_checkout.validate_address
description: "Type of event this synchronous webhook is configured for.\n\n:::note\nAt the moment, synchronous webhooks only support address validation events. \n:::"
location_id:
$ref: '#/components/schemas/Location-Id'
required:
- id
- signing_key
- url
- event_type
Location-Id:
type: string
format: uuid
description: 'Unique ID representing the location where merchants sells products.
:::info
For more information, see: [Locations](https://developer.revolut.com/docs/api/merchant#tag-locations).
::: '
Synchronous-Webhook-Creation:
title: SynchronousWebhookCreation
type: object
description: 'The `SynchronousWebhook` object allows merchants to register endpoints on their backend for receiving predefined event types. Currently, only address validation events are available.
In addition, merchants can specify locations representing their online stores, enabling them to set up different webhooks for different stores.'
properties:
event_type:
type: string
enum:
- fast_checkout.validate_address
description: "Type of event this synchronous webhook is configured for.\n\n:::note\nAt the moment, synchronous webhooks only support address validation events. \n:::"
url:
type: string
format: uri
pattern: ^https:\/{2}.+/gi
maxLength: 2000
description: 'The valid URL of the endpoint, that uses HTTPS URL schema. Revolut sends the shipping address of the customer to this URL for validation.
:::warning
Restrictions:
- Must be a valid URI as defined by [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986)
- URI scheme is required and must be `https`
- URI host is required and cannot be `localhost` or an IP address
- Max length: `2000`
- Reserved or invalid characters must be percent-encoded (for example, use `%20` instead of a space)
:::'
location_id:
$ref: '#/components/schemas/Location-Id'
required:
- event_type
- url
Error:
title: Error
type: object
properties:
errorId:
type: string
description: The ID of the error. You can share this ID with Revolut support for troubleshooting.
timestamp:
type: integer
description: The date and time the error happened.
required:
- errorId
- timestamp
parameters:
Authorization:
name: Authorization
in: header
schema:
type: string
format: Bearer <yourSecretApiKey>
example: Bearer sk_1234567890ABCdefGHIjklMNOpqrSTUvwxYZ_1234567890-Ab_cdeFGHijkLMNopq
required: true
description: "This parameter accepts the [Merchant API Secret key](https://business.revolut.com/settings/apis?tab=merchant-api) to authorise requests coming from the merchant's backend. \n\nIt ensures that ensures that each request is authenticated and authorised by verifying the secret key. The secret key should be included in all request headers as a `Bearer` token.\n\n:::info\nFor more information, see: [Authentication](https://developer.revolut.com/docs/api/merchant#authentication)\n:::"
Synchronous-Webhook-Id:
name: synchronous_webhook_id
in: path
schema:
type: string
format: uuid
description: A UUID string, typically used to identify resources.
required: true
description: The ID of the synchronous webhook.
securitySchemes:
AccessToken:
type: http
scheme: bearer
description: "Each Business API request must contain an authorization header in the following format to make a call: `Bearer <your_access_token>`.\n\nThe access token will be obtained the first time you set up your application and has an expiration of 40 minutes. \nDuring setup, a `refresh_token` will also be obtained which allows to obtain a new `access_token`.\n\n:::danger\nNever share your client-assertion JWT (JSON web token), `access_token` and `refresh_token` with anyone, as these can be used to access your banking data and initiate transactions.\n:::\n\nAccess tokens can be issued with four security scopes and require a JWT (JSON Web Token) signature to be obtained:\n- `READ`: Permissions for `GET` operations.\n- `WRITE`: Permissions to update counterparties, webhooks, and issue payment drafts.\n- `PAY`: Permissions to initiate or cancel transactions and currency exchanges. \n- `READ_SENSITIVE_CARD_DATA`: Permissions to retrieve sensitive card details.\n\n :::warning\n If you enable the `READ_SENSITIVE_CARD_DATA` scope for your access token, you must set up IP whitelisting. \n Failing to do so will prevent you from accessing **any** Business API endpoint. \n\n IP whitelisting means that you must specify an IP or a set of IPs which will be the only IPs from which requests to the API will be accepted. \n To do so:\n 1. Go to the Revolut Business web app [settings](https://business.revolut.com/settings) → **APIs** → **Business API**.\n 2. Select the corresponding API certificate.\n 3. In **Production IP whitelist**, provide the IP(s) which should be whitelisted.\n Make sure that the IPs you provide are **not** [local (i.e. private) IP addresses](https://www.okta.com/en-sg/identity-101/understanding-private-ip-ranges/). \n 4. Save the new settings.\n :::\n\nTo configure your JWT and obtain the refresh and first access tokens, complete the following steps:\n\n 1. [Sign up for a Revolut Business account](https://developer.revolut.com/docs/guides/manage-accounts/get-started/sign-up-for-revolut-business-account)\n 2. [Prepare your Sandbox environment](https://developer.revolut.com/docs/guides/manage-accounts/get-started/prepare-sandbox-environment)\n 3. [Make your first API request](https://developer.revolut.com/docs/guides/manage-accounts/get-started/make-your-first-api-request)"