Merchant API
Retrieve a dispute list
api
get
/api/disputes

Retrieve a dispute list

Retrieve a list of disputes associated with your merchant account.

note

This endpoint is only available in Production environment.

You can also use the query parameters for:

FilteringPagination
Filter the diputes that you want to retrieve, for example, only retrieve the disputes that have a specific state.

Parameters used for filtering:
  • from_created_date
  • to_created_date
  • payment_id
  • state
View the disputes without loading all of them at once, for example, return a specified number of disputes per page.

Parameters used for pagination:
  • limit
  • from_created_date or to_created_date

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​

Query Parameters
Query Parameters

Possible values: >= 1 and <= 500

Default value: 100

The maximum number of disputes returned per request.

tip

Use for pagination in combination with from_created_date or to_created_date.

Retrieve all diputes with a created_at value ≥ from_created_date.

Use the ISO 8601 date-time format: yyyy-MM-ddTHH:mm:ss[.SSSSSS]Z.

Retrieve all diputes with a created_at value ≤ to_created_date.

Use the ISO 8601 date-time format: yyyy-MM-ddTHH:mm:ss[.SSSSSS]Z.

Possible values: [needs_response, under_review, won, lost]

Retrieve all disputes with specific states. You can pass multiple values.

If multiple states are selected, for example needs_response and under_review, disputes with either of the selected values are returned. See this example of such a request URL:

https://merchant.revolut.com/api/disputes?state=needs_response&state=under_review

The parameter is case sensitive.

Retrieve disputes related to one or more payments based on their IDs.

If multiple IDs are selected, disputes with either of the selected values are returned. See this example of such a request URL:

https://merchant.revolut.com/api/disputes?payment_id=123&payment_id=456
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

Possible values: [2023-09-01, 2024-05-01, 2024-09-01]
Example: "2024-09-01"

The version of the Merchant API, specified in YYYY-MM-DD format.

If not specified, you will receive an error.

info

For more information about API versioning, see: API versions.

Response​

List of disputes retrieved

Response body
Body array of objects

Unique identifier of the dispute.

Possible values: [needs_response, under_review, won, lost]

Represents the state of the dispute.

It indicates either the final outcome of the dispute or if further action is required.

Parameter valueDescription
needs_responseIndicates that the dispute requires a response or action from the merchant.
under_reviewIndicates that the dispute is currently under review, and the outcome is pending.
wonIndicates that the dispute has been resolved in favor of the merchant.
lostIndicates that the dispute has been resolved against the merchant.

Possible values: [new, lost_expired, pre_arbitration, won_pre_arbitration, lost_pre_arbitration, lost_accepted, arbitration, won_arbitration, lost_arbitration]

Provides additional granularity about the dispute state.

It details the progression of the dispute process, showing the current stage or phase.

Parameter valueDescription
newThe dispute has been recently created and is in the initial phase, awaiting further processing.
lost_expiredThe dispute has been lost due to expiration, likely because the merchant did not respond within the required timeframe.
pre_arbitrationThe dispute is in the pre-arbitration phase, where preliminary evidence is being gathered before a formal arbitration process.
won_pre_arbitrationThe merchant secured a win during the pre-arbitration phase based on the evidence provided.
lost_pre_arbitrationThe dispute was lost during the pre-arbitration phase, indicating that the preliminary review did not favor the merchant.
lost_acceptedThe loss has been accepted as final, implying that no further contestation is likely or needed.
arbitrationThe dispute has escalated to the arbitration stage, where a neutral third party is reviewing the evidence.
won_arbitrationThe merchant won the dispute during the arbitration process.
lost_arbitrationThe merchant lost the dispute during the arbitration process.

ISO 8601 date and time when the dispute was created.

ISO 8601 date and time when the dispute was last updated.

ISO 8601 date and time until when the merchant needs to respond to the dispute.

The response time by default is 15 days after the dispute is created. If no response is provided by this date, the dispute transitions to:

  • state: lost
  • substate: lost_expired

Dispute reason code from the payment scheme, following standard formats defined by individual providers.

info

For complete, official lists of dispute codes, see:

Provides a human-readable explanation for the dispute reason codes.

Disputed amount expressed in minor currency units, according to the ISO 4217 standard. 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.

ISO 4217 currency code in upper case.

info

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

Dispute-Payment

The ID of the original payment that was disputed.

The ID of the order linked to the original disputed payment.

ISO 8601 date and time when the original disputed payment was created.

Acquirer Reference Number (ARN) of the original payment.

note

Only returned for payments made by a card.

Amount of the original payment expressed in minor currency units, according to the ISO 4217 standard. 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.

ISO 4217 currency code in upper case.

info

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

Payment method used for the original payment.

Possible values: [apple_pay, apple_tap_to_pay, card, google_pay, revolut_pay_account, revolut_pay_card]

Type of the payment method used for the original payment.

Available values:

Payment method typeDescription
apple_payThe customer paid the order using Apple Pay.
apple_tap_to_payThe customer paid the order using Apple Tap to Pay.
cardThe customer paid the order using their credit or debit card.
google_payThe customer paid the order using Google Pay.
revolut_pay_cardThe customer paid the order via Revolut Pay using their credit or debit card.
revolut_pay_accountThe customer paid the order via Revolut Pay using their Revolut account.

Possible values: [visa, mastercard, american_express]

The type of the card.

note

Only returned for payments made by a card.

Possible length: >= 4 characters and <= 4 characters

The last four digits of the card number.

note

Only returned for payments made by a card.

Was this page helpful?
Loading...