openapi: 3.0.1
info:
version: '1.0'
title: Business Accounting Payment intents 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: Payment intents
description: 'Operations for managing payment intents in the push payments to Revolut Terminal flow.
A **payment intent** represents the intention to complete payment for a specific order on a specific Revolut Terminal device. Payment intents are the mechanism that links orders created via the Merchant API with physical terminal devices in **Pay at Counter** mode.
## What is a payment intent?
When you create a payment intent, you''re pushing a payment request from your POS system to a Revolut Terminal. The payment intent:
- Links an order to a specific terminal device
- Triggers the payment request to appear on the terminal screen
- Tracks the customer''s interaction with the terminal (pending → processing → completed)
- Provides a `payment_id` when completed, which you use to retrieve the final payment status
## Payment intent lifecycle
1. **Create:** Push a payment intent to a terminal by [creating a payment intent](https://developer.revolut.com/docs/api/merchant#create-payment-intent)
1. **Track:** Poll the payment intent status by [retrieving payment intent details](https://developer.revolut.com/docs/api/merchant#retrieve-payment-intent) until it reaches a final state
1. **Complete:** When state is `completed`, extract the `payment_id` and [retrieve the final payment status](https://developer.revolut.com/docs/api/merchant#retrieve-payment-details)
1. **Cancel (optional):** Cancel pending payment intents using [Cancel a payment intent](https://developer.revolut.com/docs/api/merchant#cancel-payment-intent)
## Important notes
- A payment intent reaching `completed` state means the checkout process finished on the terminal, but it does **not** guarantee the payment succeeded
- You must check the actual payment status using the `payment_id` returned in the completed payment intent
- Payment status can be `captured`/`completed` (successful), `declined` (card rejected), `failed` (technical error), or `cancelled`
:::info
For the complete push payments integration guide, see: [Push payments to Revolut Terminal](https://developer.revolut.com/docs/guides/merchant/accept-payments/in-person-payments/terminal/push-payments).
:::'
paths:
/api/orders/{order_id}/payment-intents:
parameters:
- $ref: '#/components/parameters/Authorization'
- $ref: '#/components/parameters/Revolut-Api-Version-Optional'
- $ref: '#/components/parameters/Order-Id'
post:
summary: Create a payment intent
operationId: createPaymentIntent
description: 'Create a payment intent to push a payment request to a specific Revolut Terminal device.
This endpoint is used in push payments to Revolut Terminal integration, where a POS system sends payment requests to physical terminal devices. The terminal must be in Pay at Counter mode and assigned to the same location as the order.
**Requirements:**
- Order must be created with `channel: "pos"` and include a `location_id`
- Terminal must be online, in `pos` operation mode, and assigned to the same location
- Amount must match the order amount
**What happens next:**
- The payment request appears on the Revolut Terminal screen
- Customer presents their card or device to complete payment
- You should poll the payment intent status until it reaches a final state (`completed`, `cancelled`, or `failed`)
- When the payment intent reaches `completed` state, use the returned `payment_id` to retrieve the final payment status
:::info
For the complete push payments flow, see: [Push payments to Revolut Terminal](https://developer.revolut.com/docs/guides/merchant/accept-payments/in-person-payments/terminal/push-payments).
:::'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Payment-Intent-Creation'
examples:
create_payment_intent:
$ref: '#/components/examples/Req-Payment-Intent'
responses:
'201':
description: Payment intent created
content:
application/json:
schema:
$ref: '#/components/schemas/Payment-Intent'
examples:
payment_intent_pending:
$ref: '#/components/examples/Res-Payment-Intent-Pending'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
security:
- Api-Key: []
tags:
- Payment intents
/api/payment-intents/{payment_intent_id}:
parameters:
- $ref: '#/components/parameters/Authorization'
- $ref: '#/components/parameters/Revolut-Api-Version-Optional'
- $ref: '#/components/parameters/Payment-Intent-Id'
get:
summary: Retrieve a payment intent
operationId: retrievePaymentIntent
description: 'Retrieve the current state and details of a payment intent.
This endpoint is used to poll the payment intent status after pushing a payment request to a Revolut Terminal. You should poll this endpoint repeatedly until the payment intent reaches a final state.
**Payment intent states:**
| State | Description |
|-------|-------------|
| `pending` | Payment intent created and sent to terminal, customer has not yet started interacting |
| `processing` | Customer is actively interacting with the terminal (e.g., inserting card, entering PIN) |
| `completed` | Payment authorisation is complete, response includes a `payment_id` that you should use to [retrieve the final payment status](https://developer.revolut.com/docs/api/merchant#retrieve-payment-details) |
| `cancelled` | Payment intent was cancelled (by your system or by the customer on the terminal) |
| `failed` | Payment intent failed due to technical issues (e.g., timeout, terminal became unavailable) |
:::tip [Polling strategy]
- Poll every second while the state is `pending` or `processing`
- Set a reasonable timeout (e.g., 60 seconds) to handle cases where the customer abandons the payment
:::
:::info
For the complete push payments flow, see: [Push payments to Revolut Terminal](https://developer.revolut.com/docs/guides/merchant/accept-payments/in-person-payments/terminal/push-payments).
:::'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Payment-Intent'
examples:
payment_intent_pending:
$ref: '#/components/examples/Res-Payment-Intent-Pending'
payment_intent_processing:
$ref: '#/components/examples/Res-Payment-Intent-Processing'
payment_intent_completed:
$ref: '#/components/examples/Res-Payment-Intent-Completed'
payment_intent_cancelled:
$ref: '#/components/examples/Res-Payment-Intent-Cancelled'
payment_intent_failed:
$ref: '#/components/examples/Res-Payment-Intent-Failed'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
security:
- Api-Key: []
tags:
- Payment intents
/api/payment-intents/{payment_intent_id}/cancel:
parameters:
- $ref: '#/components/parameters/Authorization'
- $ref: '#/components/parameters/Revolut-Api-Version-Optional'
- $ref: '#/components/parameters/Payment-Intent-Id'
post:
summary: Cancel a payment intent
operationId: cancelPaymentIntent
description: 'Cancel a payment intent while it''s still in `pending` state, before the customer has completed the payment.
This is useful if the customer changes their mind or if there''s an issue with the order before payment is completed.
:::warning
**Requirements:**
- Payment intent must be in `pending` state
- Cannot cancel payment intents that are already `completed`, `cancelled`, or `failed`
:::
:::info
For the complete push payments flow, see: [Push payments to Revolut Terminal](https://developer.revolut.com/docs/guides/merchant/accept-payments/in-person-payments/terminal/push-payments).
:::'
responses:
'200':
description: Payment intent cancelled
content:
application/json:
schema:
$ref: '#/components/schemas/Payment-Intent'
examples:
payment_intent_cancelled:
$ref: '#/components/examples/Res-Payment-Intent-Cancelled'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
security:
- Api-Key: []
tags:
- Payment intents
components:
examples:
Res-Payment-Intent-Failed:
summary: Payment intent failed
value:
id: b4d58add-b3fe-40e4-a70a-8c78df977888
state: failed
terminal_id: 0e53f673-7705-473a-a263-89a3e7647c3d
order_id: 5c9fc54e-11b4-4f7f-8686-4a64d4d20db4
amount: 2500
currency: GBP
created_at: '2025-01-15T11:01:00Z'
updated_at: '2025-01-15T11:03:00Z'
Req-Payment-Intent:
summary: Create payment intent request example
value:
amount: 2500
terminal_id: 0e53f673-7705-473a-a263-89a3e7647c3d
Res-Payment-Intent-Processing:
summary: Payment intent processing
value:
id: b4d58add-b3fe-40e4-a70a-8c78df977888
order_id: 5c9fc54e-11b4-4f7f-8686-4a64d4d20db4
state: processing
amount: 2500
currency: GBP
terminal_id: 0e53f673-7705-473a-a263-89a3e7647c3d
created_at: '2025-01-15T11:01:00Z'
updated_at: '2025-01-15T11:02:15Z'
Res-Payment-Intent-Pending:
summary: Payment intent pending
value:
id: b4d58add-b3fe-40e4-a70a-8c78df977888
state: pending
order_id: 5c9fc54e-11b4-4f7f-8686-4a64d4d20db4
amount: 2500
currency: GBP
Res-Payment-Intent-Completed:
summary: Payment intent completed
value:
id: b4d58add-b3fe-40e4-a70a-8c78df977888
state: completed
terminal_id: 0e53f673-7705-473a-a263-89a3e7647c3d
order_id: 5c9fc54e-11b4-4f7f-8686-4a64d4d20db4
payment_id: 7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d
amount: 2500
currency: GBP
created_at: '2025-01-15T11:01:00Z'
updated_at: '2025-01-15T11:02:30Z'
Res-Payment-Intent-Cancelled:
summary: Payment intent cancelled
value:
id: b4d58add-b3fe-40e4-a70a-8c78df977888
state: cancelled
terminal_id: 0e53f673-7705-473a-a263-89a3e7647c3d
order_id: 5c9fc54e-11b4-4f7f-8686-4a64d4d20db4
amount: 2500
currency: GBP
created_at: '2025-01-15T11:01:00Z'
updated_at: '2025-01-15T11:01:45Z'
schemas:
Currency:
type: string
format: ISO 4217
minLength: 3
maxLength: 3
description: '[ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code in upper case.
:::info
For more information about the supported currencies, see: [Help Center](https://help.revolut.com/business/help/merchant-accounts/payments/in-which-currencies-can-i-accept-payments/).
:::'
Payment-Intent-Id:
title: Payment Intent ID
type: string
format: uuid
description: The unique identifier of the payment intent.
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
Payment-Intent-State:
type: string
description: 'The current state of the payment intent.
| State | Description |
|-------|-------------|
| `pending` | Payment intent created and sent to terminal, customer has not yet started interacting |
| `processing` | Customer is actively interacting with the terminal (e.g., inserting card, entering PIN) |
| `completed` | Payment authorization is complete, includes a `payment_id` in the response |
| `cancelled` | Payment intent was cancelled (by system or customer) |
| `failed` | Payment intent failed due to technical issues (timeout, terminal unavailable, network error) |'
enum:
- pending
- processing
- completed
- cancelled
- failed
Payment-Intent:
title: Payment Intent
type: object
description: 'Represents a payment intent that has been pushed to a Revolut Terminal device.
When the payment intent reaches `completed` state, it includes a `payment_id` that can be used to [retrieve the final payment status](https://developer.revolut.com/docs/api/merchant#retrieve-payment-details).'
properties:
id:
$ref: '#/components/schemas/Payment-Intent-Id'
state:
$ref: '#/components/schemas/Payment-Intent-State'
terminal_id:
$ref: '#/components/schemas/Terminal-Id'
order_id:
$ref: '#/components/schemas/Order-Id'
payment_id:
$ref: '#/components/schemas/Payment-Id'
amount:
$ref: '#/components/schemas/Payment-Intent-Amount'
currency:
$ref: '#/components/schemas/Currency'
created_at:
type: string
format: date-time
description: The date and time the payment intent was created.
updated_at:
type: string
format: date-time
description: The date and time the payment intent was last updated.
required:
- id
- order_id
- state
- amount
- currency
- terminal_id
- created_at
- updated_at
Payment-Intent-Amount:
title: Payment Intent amount
type: integer
description: 'The payment amount expressed in minor currency units, according to the [ISO 4217 standard](https://en.wikipedia.org/wiki/ISO_4217). For example, `7034` in `EUR` corresponds to €70.34.
:::info
Conversion between major and minor units varies by currency. For instance, `100` minor units equal £1.00 in `GBP`, whereas in `ISK` they represent 100 units. For more details, see the [ISO 4217 standard](https://en.wikipedia.org/wiki/ISO_4217).
:::'
Terminal-Id:
title: Terminal ID
type: string
format: uuid
description: The unique identifier of the terminal.
Payment-Intent-Creation:
title: Payment Intent creation
type: object
description: Request body for creating a payment intent to push to a terminal.
properties:
amount:
$ref: '#/components/schemas/Payment-Intent-Amount'
terminal_id:
$ref: '#/components/schemas/Terminal-Id'
required:
- amount
- terminal_id
Order-Id:
type: string
format: uuid
description: Permanent order ID used to retrieve, capture, cancel, or refund an order after authorization.
Payment-Id:
type: string
format: uuid
description: The ID of the payment.
parameters:
Revolut-Api-Version-Optional:
name: Revolut-Api-Version
in: header
schema:
type: string
format: date
example: '2026-04-20'
enum:
- '2023-09-01'
- '2024-05-01'
- '2024-09-01'
- '2025-10-16'
- '2025-12-04'
- '2026-03-12'
- '2026-04-20'
description: 'The version of the Merchant API, specified in `YYYY-MM-DD` format.
:::info
For more information about API versioning, see: [API versions](https://developer.revolut.com/docs/guides/merchant/reference/versioning/api-versions).
:::'
x-config-always-visible-in-example: true
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:::"
Payment-Intent-Id:
name: payment_intent_id
in: path
required: true
description: The unique identifier of the payment intent.
schema:
$ref: '#/components/schemas/Payment-Intent-Id'
Order-Id:
name: order_id
in: path
schema:
type: string
format: uuid
description: A UUID string, typically used to identify resources.
required: true
description: The ID of the `Order` object.
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)"