Revolut Other API

openapi: 3.2.0
info:
  title: Merchant Other API
  version: '2026-04-20'
  description: 'Welcome to the Revolut Merchant API - your solution to managing the core aspects of e-commerce and accepting online payments. Whether you''re a startup, a growing business, or an established enterprise in the e-commerce industry, our API helps you streamline your operations.


    As a Revolut Business customer with a Merchant Account, you can use the

    Merchant API to leverage the following features:


    - [Order management](https://developer.revolut.com/docs/api/merchant#tag-orders)

    - [Customer management](https://developer.revolut.com/docs/api/merchant#tag-customers)

    - [Payment management](https://developer.revolut.com/docs/api/merchant#tag-payments)

    - [Subscription management](https://developer.revolut.com/docs/api/merchant#tag-subscriptions)

    - [Payout management](https://developer.revolut.com/docs/api/merchant#tag-payouts)

    - [Dispute management](https://developer.revolut.com/docs/api/merchant#tag-disputes)

    - [Reporting analytics](https://developer.revolut.com/docs/api/merchant#tag-report-runs)

    - [Webhook management](https://developer.revolut.com/docs/api/merchant#tag-webhooks)

    - [Location management](https://developer.revolut.com/docs/api/merchant#tag-locations)


    ... and more.


    ### API versions


    :::warning

    We highly recommend using versioning in your API calls. If you don''t provide a version header on the operations where it''s required, you will receive an error response.

    :::


    The Merchant API uses request header versioning. Where it is required you need to use the `Revolut-Api-Version` header parameter to specify an API version. Each request, where it is indicated in the API specification, must contain a version header in the following format:


    ```

    ''Revolut-Api-Version: 2026-04-20''

    ```


    :::info

    For more information, see: [API versions](https://developer.revolut.com/docs/guides/merchant/reference/versioning/api-versions)

    :::


    ### Test the Merchant API


    You can test the Merchant API in Postman by forking this collection:


    [![View in Postman](https://run.pstmn.io/button.svg)](https://www.postman.com/revolut-api/workspace/revolut-developers/overview)'
  contact: {}
servers:
- description: Production server (uses live data)
  url: https://merchant.revolut.com
- description: Sandbox server (uses test data)
  url: https://sandbox-merchant.revolut.com
security:
- Api-Key: []
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:
  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.
  schemas:
    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
    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).

        :::        '
    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
    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
  securitySchemes:
    Api-Key:
      type: apiKey
      in: header
      name: Authorization
      description: 'Each Merchant API request must contain an authorization header in the following format:


        ```

        ''Authorization: Bearer <yourSecretApiKey>''

        ```


        To use this API, you need to generate API keys from your Revolut Business account. The Secret key is used in the authorization header for all server calls, while the Public key is provided with payment methods at checkout.


        :::info

        For detailed instructions on generating your API keys, see: [Generate API keys](https://developer.revolut.com/docs/guides/merchant/get-started#generate-api-keys).

        :::'