Merchant API
Create a webhook
api
post
/api/1.0/webhooks

Create a webhook

Set up a webhook URL so that the Merchant API can push event notifications to the specified URL.

Authorization

Each Merchant API request must contain an authorization header in the following format to make a call:

'Authorization: Bearer <yourSecretApiKey>'

Before you start, ensure that you've successfully applied for a Merchant Account in your Revolut Business Account.

The Public key is on the same path in your Revolut Business account as the Secret key. There are two different functions for each:

  • Public key should be provided with payment methods at checkout
  • Secret key is used as a part of the authorization header for all server calls, e.g., creating order

Complete the following steps to generate the Production API keys (Secret, Public):

  1. Log in to your Revolut Business portal.
  2. On the top left corner, click your account name, click APIs then select Merchant API.
  3. Under the Production API Secret key and Production API Public key sections you will find the API keys needed. If it's your first time on this page, you will need to click the Generate button to create your unique API keys.

You can also use this link to directly open the Merchant API page.

Merchant API - Settings

note

Use these keys only for the production environment. For the Revolut Business Sandbox environment, use the sandbox API keys.

SSL

note

This authentication protocol is used exclusively when using Fast checkout.

Connection over HTTPS is using SSL authentication. For successful authentication, your system's certificate should be issued by a Public Certificate Authority (PCA) and your system should trust Revolut's public certificate.

Revolut-Pay-Payload-Signature

note

This authentication protocol is used exclusively when using Fast checkout.

Data integrity and authorship will be verified using a payload-based signature. The response of a successful URL registration for address validation (see: Register address validation for Fast checkout) will contain a secret signing key.

The signing key will be used by Revolut to compute a Hash-based Message Authentication Code (HMAC) payload signature whenever the registered URL is called, which should be verified by your backend.

Request

Header Parameters
Header Parameters

This parameter accepts the Merchant API Secret key to authorise requests coming from the merchant's backend.

It 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.

info

For more information, see: Authorization

Request body
Body object

Possible values: <= 2000 characters

Your webhook's URL to which event notifications will be sent.

Must be a valid HTTP or HTTPS URL, capable of receiving POST requests.

caution

Restrictions:

  • Max length of url string: 2000
  • Only valid http:// or https:// domains are accepted
  • Domain cannot be localhost or IP address

Possible values: [ORDER_COMPLETED, ORDER_AUTHORISED, ORDER_CANCELLED, ORDER_PAYMENT_AUTHENTICATED, ORDER_PAYMENT_DECLINED, ORDER_PAYMENT_FAILED], >= 1

List of event types that the webhook is configured to listen to.

Response

OK

Response body
Body object

The ID of the webhook.

Possible values: <= 2000 characters

Your webhook's URL to which event notifications will be sent.

Must be a valid HTTP or HTTPS URL, capable of receiving POST requests.

caution

Restrictions:

  • Max length of url string: 2000
  • Only valid http:// or https:// domains are accepted
  • Domain cannot be localhost or IP address

Possible values: [ORDER_COMPLETED, ORDER_AUTHORISED, ORDER_CANCELLED, ORDER_PAYMENT_AUTHENTICATED, ORDER_PAYMENT_DECLINED, ORDER_PAYMENT_FAILED], >= 1

List of event types that the webhook is configured to listen to.

The signing secret for the webhook. Use it to verify the signature for the webhook request's payload.

Callbacks

Send webhook event to webhook URL

POST
{$request.body#/url}

The following webhook event payload is sent as a HTTP POST request to the URL registered as the merchant's webhook server via the Create a webhook operation.

The delivery of the webhook events happen asynchronously, based on the events you subscribed to.

Callback request

Header Parameters
Header Parameters

The UNIX timestamp of the date and time when the webhook event was sent from Revolut. Used to verify the webhook event payload was actually sent by Revolut.

info

For more information, see: Verify payload signature

The payload signature computed by Revolut using a Hash-based Message Authentication Code (HMAC). Used to verify the webhook event payload was actually sent by Revolut.

info

For more information, see: Verify payload signature

Request body
Body object

Possible values: [ORDER_COMPLETED, ORDER_AUTHORISED, ORDER_CANCELLED, ORDER_PAYMENT_AUTHENTICATED, ORDER_PAYMENT_DECLINED, ORDER_PAYMENT_FAILED]

The event type corresponding to the order.

The ID of the order the event is related to.

The information sent during order creation in the merchant_order_data.reference field.

Callback responses

If the webhook event was delivered successfully, we recommend to respond with a 204 code.

info

You can respond to and acknowledge the delivery of a webhook event by any HTTP response code between 200-399.

Was this page helpful?
Loading...