dispute

arises when your customer or the issuing bank questions the validity of a payment.

You can try out our APIs on the Razorpay Postman Public Workspace.

Use Cases

Accept a dispute
against the payment.
Contest a dispute
with explanations and supporting documents to submit evidences.
Retrieve information about all disputes
.
Retrieve details for a specific dispute
using the unique identifier linked to the dispute.

Dispute Entity

The Disputes entity has the following fields:

string The unique identifier of the dispute generated by Razorpay. For example, disp_AHfqOvkldwsbqt.

entity

string Indicates the type of entity. In this case, it is dispute.

payment_id

string The unique identifier of the payment against which the dispute was created. For example, pay_EsyWjHrfzb59eR.

amount

integer Amount, in currency subunits, for which the dispute was created.

currency

string 3-letter ISO currency code associated with the amount. Check the list of

supported currencies

amount_deducted

integer The amount, in currency subunits, deducted from your Razorpay current balance when the dispute is lost. This amount will be 0 unless the status of dispute is updated to lost. Know about the different

states of disputes

reason_code

string Code associated with the reason for the dispute.

reason_description

string A brief description of the reason for dispute.

respond_by

integer Unix timestamp by which a response should be sent to the customer.

status

string The status of the dispute. Possible statuses are:

open: Indicates that the dispute has been created.
under_review: Indicates that the issuing bank is reviewing the dispute.
won: Indicates that the bank has accepted the remedial documents, and you have won the chargeback.
lost: Indicates that the bank did not accept the remedial documents, and you have lost the chargeback.
closed: Indicates that the fraudulent transaction was closed after you provided either the transaction details or made a refund to the customer.

phase

string Phase associated with the dispute. Possible phases are:

fraud: A dispute raised by the bank when it suspects a transaction to be fraudulent based on the risk analysis.
retrieval: A request initiated by the customer with their issuer bank for additional information about a transaction.
chargeback: A refund claim initiated by the customers with their issuer banks. In such cases, the bank starts an official inquiry.
pre_arbitration: A chargeback that you have won is challenged by the customer for the second time.
arbitration: A chargeback that you have won is challenged for a third time by the customer and the card networks directly getting involved.

created_at

integer Unix timestamp when the dispute was created.

evidence

object Provides details of the evidence submitted/saved for contesting a dispute. Use the

Documents API

to securely share documents with Razorpay.

amount

integer The contested amount in currency subunits, for which evidence is provided. The value can vary from 0 to the dispute amount. The default value is the dispute amount.

summary

string The explanation provided by you for contesting the dispute. It can have a maximum length of 1000 characters.

shipping_proof

list (List of document ids) Document(s) which serves as proof that the product was shipped to the customer at their provided address. It should show their complete shipping address, if possible.

billing_proof

list (List of document ids) Document(s) which serves as proof of order confirmation, such as a receipt.

cancellation_proof

list (List of document ids) Document(s) that serves as proof that this product/service was cancelled.

customer_communication

list (List of document ids) Document(s) listing any written/email communication from the customer confirming that the customer received the product/service or is satisfied with the product/service.

proof_of_service

list (List of document ids) Document(s) showing proof of service provided to the customer.

explanation_letter

list (List of document ids) Any letter(s) from you specifying information pertinent to the dispute/payment that needs to be considered for processing the dispute.

refund_confirmation

list (List of document ids) Document(s) showing proof that the refund had been provided to the customer.

access_activity_log

list (List of document ids) Document(s) of any server or activity logs which prove that the customer accessed or downloaded the purchased digital product.

refund_cancellation_policy

list (List of document ids) Document(s) listing your refund and/or cancellation policy, as shown to the customer.

term_and_conditions

list (List of document ids) Document(s) listing your sales terms and conditions, as shown to the customer.

others

list Specifies the evidence documents to be uploaded as a part of contesting a dispute. It is a list of tuples consisting of the following:

type

string Describes the custom type of evidence document(s) provided.

document_ids

list (List of document ids) Document(s) corresponding to the customer evidence type.

[
  {
    "type": "receipt_signed_by_customer",
    "document_ids": [
      "doc_EFtmUsbwpXwBH7",
      "doc_EFtmUsbwpXwBH6"
    ]
  }  
]

submitted_at

integer Unix timestamp when the dispute was last submitted by you (for review) to Razorpay. The default value is null.

{
  "id": "disp_AHfqOvkldwsbqt",
  "entity": "dispute",
  "payment_id": "pay_EsyWjHrfzb59eR",
  "amount": 10000,
  "currency": "INR",
  "amount_deducted": 0,
  "reason_code": "chargeback",
  "respond_by": 1590604200,
  "status": "open",
  "phase": "chargeback",
  "created_at": 1590059211,
  "evidence": {
    "amount": 9000,
    "summary": "goods delivered",
    "shipping_proof": [
      "doc_EFtmUsbwpXwBH9",
      "doc_EFtmUsbwpXwBH8"
    ],
    "billing_proof": [
      "doc_EFtmUsbwpXwBG9",
      "doc_EFtmUsbwpXwBG8"
    ],
    "cancellation_proof": null,
    "customer_communication": null,
    "proof_of_service": null,
    "explanation_letter": null,
    "refund_confirmation": null,
    "access_activity_log": null,
    "refund_cancellation_policy": null,
    "term_and_conditions": null,
    "others": [
      {
        "type": "receipt_signed_by_customer",
        "document_ids": [
          "doc_EFtmUsbwpXwBH1",
          "doc_EFtmUsbwpXwBH7"
        ]
      }
    ],
    "submitted_at": null
  }
}

You can manage disputes using APIs or from the

Razorpay Dashboard

to ensure a seamless dispute management experience.

Fetch all Disputes

The following endpoint retrieves all the disputes raised by your customers.

GET

/disputes

Response Parameters

Descriptions for the response parameters are present in the

Dispute Entity

parameters table.

Fetch a Dispute

The following endpoint retrieves the details of a specific dispute.

GET

/disputes/:id

{
    "error": {
        "code": "BAD_REQUEST_ERROR",
        "description": "The id provided does not exist",
        "source": "business",
        "step": "payment_initiation",
        "reason": "input_validation_failed",
        "metadata": {}
    }
}

Response Parameters

Descriptions for the response parameters are present in the

Dispute Entity

parameters table.

Path Parameter

mandatory

string The unique identifier of the dispute.

Error Response Parameters

Given below is a list of possible errors you may face while fetching a dispute.

Error	Cause	Solution
The id provided does not exist	A non-public id is used. A wrong prefix is used. The dispute id does not exist or does not belong to the requestor.	Use a public id. The dispute id must start with `disp_`. Use a valid dispute id that belongs to the requestor.
_id is not a valid id	The id is not 14 characters long. The id is not alphanumeric.	Use a valid dispute id.

Accept a Dispute

The following endpoint allows you to accept a dispute charge, indicating that you do not wish to contest the dispute, acknowledging it as lost.

POST

/disputes/:id/accept

Watch Out!

The dispute status will change from open to lost.
Accepting a dispute is irreversible.

Path Parameter

mandatory

string The unique identifier of the dispute.

Response Parameters

Descriptions for the response parameters are present in the

Dispute Entity

parameters table.

Contest a Dispute

The following endpoint allows you to contest a dispute, indicating that you would like to challenge the dispute raised against a payment.

PATCH

/disputes/:id/contest

In addition to explicitly contesting a dispute, the contest process can also be triggered by:

Attaching an evidence document using
Documents API
with having a purpose set to dispute_evidence.
Providing the evidence in textual format.
Specifying the contest amount (partial or full). The default choice is contesting the full amount if it is not specifically mentioned.

Handy Tips

Ensure you pass the action parameter as submit to confirm the contest of the dispute. Dispute evidence draft does not get auto-submitted.
Ensure you provide a minimum of one document for contesting a dispute. Add as many relevant documents as possible to maximise the chances of dispute resolution in your favor.

Path Parameter

mandatory

string The unique identifier of the dispute.

Request Parameters

amount

optional

integer The amount being contested. If the contest amount is not mentioned, we will assume it to be a full dispute contest.

summary

string The explanation provided by you for contesting the dispute. It can have a maximum length of 1000 characters.

shipping_proof

list (List of document ids) Document(s) which serves as proof that the product was shipped to the customer at their provided address. It should show their complete shipping address, if possible.

billing_proof

list (List of document ids) Document(s) which serves as proof of order confirmation, such as a receipt.

cancellation_proof

list (List of document ids) Document(s) that serves as proof that this product/service was cancelled.

customer_communication

list (List of document ids) Document(s) listing any written/email communication from the customer confirming that the customer received the product/service or is satisfied with the product/service.

proof_of_service

list (List of document ids) Document(s) showing proof of service provided to the customer.

explanation_letter

list (List of document ids) Any letter(s) from you specifying information pertinent to the dispute/payment that needs to be considered for processing the dispute.

refund_confirmation

list (List of document ids) Document(s) showing proof that the refund was provided to the customer.

access_activity_log

list (List of document ids) Document(s) of any server or activity logs which prove that the customer accessed or downloaded the purchased digital product.

refund_cancellation_policy

list (List of document ids) Document(s) listing your refund and/or cancellation policy, as shown to the customer.

term_and_conditions

list (List of document ids) Document(s) listing your sales terms and conditions, as shown to the customer.

others

list Specifies the evidence documents to be uploaded as a part of contesting a dispute. It is a list of tuples consisting of the following:

type

string Describes the custom type of evidence document(s) provided.

document_ids

list (List of document ids) Document(s) corresponding to the customer evidence type.

[
  {
    "type": "receipt_signed_by_customer",
    "document_ids": [
      "doc_EFtmUsbwpXwBH7",
      "doc_EFtmUsbwpXwBH6"
    ]
  }  
]

action

optional

string The action to be taken for this contest. Possible values:

draft: Allows you to contest the dispute by updating the dispute entity. This action does not submit the dispute yet. The absence of the key action or a corresponding value would default the action to draft.
submit: Allows you to contest the dispute by updating the dispute entity and submitting the same to Razorpay. You need to provide a minimum of one document id (across any of the evidence object attributes) for a successful submission:
- Submitting for review would change the status of your dispute from open to under_review.
- It triggers the webhook event payment.dispute.under_review.

Handy Tips

Add as many relevant documents as possible to maximise the chances of dispute resolution in your favor.

Response Parameters

Descriptions for the response parameters are present in the

Dispute Entity

parameters table.

Webhooks

Set up

Razorpay Webhooks to configure and receive notifications when a specific

event

occurs. When one of these events is triggered, we send an HTTP POST

payload

in JSON to the webhook's configured URL.