Merchant API
Create a new report run
api
post
/api/report-runs

Create a new report run

Start generating a new report of the relevant transactions, and receive report_run_id.

After generation is done, use the link in file_url to download the report. Use the Retrieve report run details operation to check the status of the report run.

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 account: Access the Revolut Business log in page and enter your credentials.
  2. Navigate to Merchant API settings: Once logged in, access the Merchant API settings page by clicking in the top right corner, then selecting APIs > Merchant API. Here you can access your Production API keys (Public, Secret) specific to your Merchant account.
  3. Get API keys: If you're visiting this page for the first time, you'll need to generate your Production API Secret key, click the Generate button.
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

Example: "Bearer sk_1234567890ABCdefGHIjklMNOpqrSTUvwxYZ_1234567890-Ab_cdeFGHijkLMNopq"

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  

A settlement report contains all the query information for generating reports of settled transactions associated with a Merchant account.

List of filtering parameters to be applied to the report.

This parameter specifies the start boundary for filtering transaction data in the report based on an order's payments.created_at parameter. It accepts ETC/UTC date and time in ISO 8601 format and includes all transactions created on or after this timestamp.

Combined with the to parameter, this determines the report's timeframe, including all transactions between the two values.

For example, by setting the from parameter to 2021-01-01T00:00:00Z, the report will include transactions created from the first second of January 1, 2021, UTC, and onwards.

This parameter specifies the end boundary for filtering transaction data in the report based on an order's payments.created_at parameter. It accepts ETC/UTC date and time in ISO 8601 format and includes all transactions created before this timestamp (exclusive).

Combined with the from parameter, this determines the timeframe for the report, including all transactions between the two values.

For example, setting the to parameter to 2021-12-31T23:59:59Z will include all transactions in the report created up to, but not including, the last second of December 31, 2021, UTC.

Possible values: [payment, refund, dispute]

Select transactions by type to be included in the report.

Possible values: [completed, failed, declined, processing, cancelled, reverted]

Select transactions by state to be included in the report.

If not provided, only completed transactions will be included in the report.

Possible length: >= 3 characters and <= 3 characters
Example: "GBP"

Select transactions with specific currencies to include in the report. Provide ISO 4217 currency code in upper case.

info

For more information about the supported currencies, see: Help Center.

Select transactions by location ID to be included in the report.

info

For more information, see: Locations.

Possible values: [csv]
Example: "csv"

Format of the generated report file.

Possible values: [settlement_report, custom_report, payout_statement_report, icpp_fee_breakdown_report]
Example: "settlement_report"

Type of the report.

Possible values:

Type of reportDescription
settlement_reportSettlement report is a report including transactions settled to the user account. This parameter sets the predefined options and list of represented columns.
custom_reportCustom reports require users to define options.
payout_statement_reportPayout statement Reports provide a detailed breakdown of all transactions contributing to a specific payout amount. It requires the additional parameter filter.payout_id, which should be obtained from the payout ID retrieved via the payout list endpoint or from webhook events.
icpp_fee_breakdown_reportIC++ fee breakdown reports provide a detailed breakdown of fees for each IC++ transaction related to a payout. It requires the additional parameter filter.icpp_charge_id, which should be obtained from the related_icpp_charge_id column in the Payout statement report. A separate report should be generated for each IC++ transaction.

Further options to customize the report.

Example: "Europe/London"

Defaults to ETC/UTC. Defines the output timezone for all timestamps displayed in the report.

Has no effect on from or to parameters.

Names of the columns to be included in the report.

If the columns parameter is not defined in the request, all available columns will be included in the report. An empty array will return an error.

If you created orders using the metadata object, you can include them in the report by adding them with metadata. prefix. For example: metadata.custom_attribute.

Available columns:

Column nameDescription
transaction_idUnique identifier of the transaction related to an order.
order_idUnique identifier of the order.
started_dateDate and time the transaction was created.
updated_dateDate and time the transaction was last updated.
completed_dateDate and time the transaction was completed.
typeType of the order.
stateState of the order.
descriptionDescription of the order.
merchant_order_ext_refMerchant's order identifier for external reference.
customer_idUnique identifier of the customer related to an order.
amountTotal amount of the order.
currencyThe ISO 4217 currency code that represents the currency of the order.
settlement_amountTotal amount settled on the merchant's account.
settlement_currencyThe ISO 4217 currency code that represents the currency of the settled amount.
fee_amountTotal amount of extra fees applied to the order.
fee_currencyThe ISO 4217 currency code that represents the currency of extra fees.
processing_fee_amountTotal amount of processing fees applied to the order.
processing_fee_currencyThe ISO 4217 currency code that represents the currency of processing fees.
payment_methodType of the payment method the customer used to pay for the order.
browser_urlThe URL where the customer initiated the payment.
related_icpp_charge_idUnique identifier of the IC++ charge related to the transaction. This column is only available in the payout_statement_report.
location_idUnique identifier of the location related to the transaction. This column is only available in settlement_report and custom_report.

Response​

Report run created, report started generating

Response body
Body object 

Unique ID used for accessing report details. Use this to check report generation status.

Possible values: [processing, completed, failed, expired]

Current status of the report run.

Use this link to download report file. Not available, until status is completed.

Was this page helpful?
Loading...