Download the PHP package znojil/revolut-business without Composer

Znojil Revolut Business

A simple and modern PHP library for communicating with the Revolut Business API.

Covers all 98 endpoints of the Merchant API v1.0 and the Webhooks API v2.0, with typed DTOs, enums and full PHPStan level max coverage.

🚀 Installation

🔑 Authorization

The Revolut Business API uses OAuth 2.0 with a JWT client assertion. Before you can send a single request, you need to complete a one-time consent flow:

1. Create an API certificate. In Revolut Business, go to Settings → API, upload your public key and set a redirect URI. Revolut gives you a client ID and you choose an issuer (the domain of your redirect URI).
2. Get the authorization code. Open the consent link shown next to your certificate. After you confirm, Revolut redirects to your redirect URI with a ?code= query parameter.
3. Exchange the code for a token pair — once, using Client::authorize().

See Make your first API request for the full walkthrough.

From then on the library handles tokens on its own — the access token is refreshed from the stored refresh token whenever it expires, so you only ever call send().

The refresh token expires after 90 days and cannot be renewed automatically. Once that happens, AuthenticationException is thrown and you have to run the consent flow again.

📖 Usage

1. Sending a Request

Every endpoint is a *Request class. Pass it to Client::send() and you get back a typed result:

Requests that need a body take their required parameters first and the optional ones as named arguments:

Listing endpoints are paginated by time, not by page number — you walk backwards using the timestamp of the oldest item you received:

2. Custom Token Storage

FileTokenStorage stores the token pair as JSON in a file with 0600 permissions. To keep tokens in a database or a cache instead, implement Znojil\RevolutBusiness\TokenStorage:

save() is called both by authorize() and by every automatic token refresh, so whatever you write to must be durable — losing the refresh token means going through the consent flow again.

3. Using a Custom HTTP Client

By default the library uses znojil/http. You can inject your own implementation as the third argument to the Client constructor. It must implement the Znojil\RevolutBusiness\Http\Client interface.

String keys in $options are Znojil\RevolutBusiness\Http\Option::* enum values that every implementation must honor, and unknown string keys must be rejected with an exception. Integer keys are raw CURLOPT_* constants — non-cURL implementations must reject them with an exception rather than silently ignore them, so that a consumer never ends up with options that silently don't apply.

🧩 Conventions

A few things that are specific to this library rather than to the API itself.

Clearing a Property

On Update* requests, null and "remove this value" are two different intentions, so null cannot mean both. Passing null leaves a property unchanged; to have the API remove it, pass the Clear::Value sentinel:

Where a property cannot be cleared through the API, its parameter simply doesn't accept Clear.

Requests That Need At Least One Property

Most Update* endpoints reject an empty body. Those requests throw InvalidArgumentException when you construct one with nothing to update, rather than sending a request that is guaranteed to fail.

Enums

Most enums are closed: an unknown value in a response throws UnexpectedValueException, so you learn about an API change instead of silently getting a wrong value.

Three of them are open, because their real value sets are larger than what the documentation lists and a new entry must not break a running application. Currency, PaymentRoute and TransferReasonCode are typed as string|Enum on the response side — you get the enum case when the value is known and the raw string when it isn't:

On the request side these are always plain enums — you can only send what the library knows.

Parameter Validation

Requests do not validate their parameters. The API returns precise errors for invalid input, and duplicating those rules here would mean maintaining a second copy of somebody else's specification. Every request class links to its official documentation page in a @link annotation.

📋 Available Requests

All 98 requests live in the Znojil\RevolutBusiness\Request namespace, grouped here the same way as the official documentation.

Accounting

Accounts

Cards

Card invitations

Counterparties

Expenses

Foreign exchange

Payment drafts

Payout links

Simulations

Sandbox only.

Teams

Transactions

Transfers

Webhooks

Version 2.0 of the Webhooks API. The deprecated v1 endpoints are not implemented.

⚠️ Error Handling

The client throws exceptions to help you identify the issue:

• Znojil\RevolutBusiness\Exception\ClientException: For HTTP client-side errors (4xx).
• Znojil\RevolutBusiness\Exception\ServerException: For HTTP server-side errors (5xx).
• Znojil\RevolutBusiness\Exception\ResponseException: For other unsuccessful HTTP responses. The base class of the three above — it carries apiErrorCode, apiErrorId and the raw responseBody.
• Znojil\RevolutBusiness\Exception\JsonException: When a response body is not valid JSON.
• Znojil\RevolutBusiness\Exception\JsonResponseException: When a response body is valid JSON but not the object or array the endpoint promises (subtype of ResponseException).
• Znojil\RevolutBusiness\Exception\UnexpectedValueException: When a response contains an enum value the library does not know.
• Znojil\RevolutBusiness\Exception\InvalidArgumentException: For invalid input (e.g. an update request with no properties to update).
• Znojil\RevolutBusiness\Exception\MissingTokenException: When no token pair is stored yet — run the authorization flow first.
• Znojil\RevolutBusiness\Exception\IOException: When FileTokenStorage cannot read or write the token file.
• Znojil\RevolutBusiness\Auth\Exception\AuthenticationException: When the token exchange or refresh fails (e.g. an expired or revoked refresh token).
• Znojil\RevolutBusiness\Auth\Exception\ClientAssertionException: When the JWT client assertion cannot be created (e.g. an invalid private key).

All exceptions thrown by the library implement the Znojil\RevolutBusiness\Exception\Exception marker interface, so a single catch can cover them all.

📄 License

This library is open-source software licensed under the MIT license.