Stay organized with collections Save and categorize content based on your preferences.

Create and resolve disputes

This page describes how you can use the issuer switch API to create or resolve a dispute in the Unified Real-time Clearing and Settlement (URCS) system of NPCI. This page assumes that you are familiar with the Unified Dispute and Issue Resolution (UDIR) specification defined by the NPCI.

When you create a dispute, you specify a reason for the dispute. For example, some reasons for creating a dispute could be:

  • A customer claims a fraudulent transaction has been processed.
  • A transaction hasn't been settled within a specified time.
  • A transaction has inadvertently been initiated multiple times.
  • A customer has accidentally transferred funds to the wrong beneficiary.

Each of the reasons specified when creating a dispute maps to a specific reason code in the Unified Dispute and Issue Resolution (UDIR) specification defined by the NPCI.

When you create a dispute, you must also specify if an adjustment is required or not.

When a dispute is processed and the action required is determined, you can use the issuer switch API to resolve the dispute. While resolving a dispute, specify the adjustment required and the reason code for the resolution of the dispute. The adjustment required as well as the reason for resolving the dispute map to specific adjustment flags and reason codes in the UDIR specification.

Create a dispute

To create a dispute using the issuer switch API, use the CreateDispute method [REST, gRPC]. In the request body, specify the Dispute object. This object requires you to specify the RaiseDisputeAdjustment object and the CaseDetails object, which contain the specific values that you want to associate with the dispute.

The following curl command creates a dispute for an original transaction with the specified Retrieval Reference Number (RRN) and transaction ID. The reason for the complaint is specified in the adjustment code and the adjustment flag is set to CHARGEBACK_RAISE to indicate that an adjustment is required. The transaction amount and currency are also provided. In this example, the dispute is created by the remitter bank, as indicated by the transaction subtype.

curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json; charset=utf-8" -d '
{
  "parent": "projects/PROJECT_ID",
  "dispute": {
    "raiseDisputeAdjustment": {
      "adjustmentFlag": "CHARGEBACK_RAISE",
      "adjustmentCode": "CHARGEBACK_RAISE_REMITTER_DEBITED_BENEFICIARY_NOT_CREDITED"
    },
    "details": {
      "currentCycle": false,
      "originalSettlementResponseCode": "RB",
      "amount": {
        "currencyCode": "INR",
        "units": "99",
        "nanos": 990000000
      },
      "transactionSubType": "TRANSACTION_SUB_TYPE_REMITTER",
      "originalTransaction": {
        "transactionId": "GOO4a69d250abe6433899c2f5a081000033882",
        "retrievalReferenceNumber": "013100747891",
        "requestTime": "2022-02-28T00:00:00.000Z"
      }
    }
  }
}
    ' "https://ISSUER_SWITCH_API_ENDPOINT/v1/projects/PROJECT_ID/disputes"

In this example:

  • PROJECT_ID is the ID of your Google Cloud project.
  • $TOKEN is your OAuth 2.0 access token.
  • ISSUER_SWITCH_API_ENDPOINT is your issuer switch's API endpoint. For example, api.129a0b1a-bb73-4906-a5b7-a6e0bfe7860e.issuerswitch.goog.

Replace these with values specific to your environment.

When you run this command, you see a response similar to the following:

{
  "name": "projects/PROJECT_ID/operations/Q09NUExBSU5UIyNvcmlnUlJOJCRUUkFOU0FDVElPTl9TVUJfVFlQRV9SRU1JVFRFUg==",
  "metadata": null,
  "done": false
}

Resolve a dispute

To resolve a dispute using the issuer switch API, use the ResolveDispute method [REST, gRPC]. In the request body, specify the Dispute object. This object allows you to specify the ResolveDisputeAdjustment object and the CaseDetails object, which contain the specific values that you want to associate with the dispute resolution.

The following curl command resolves a dispute with the specified dispute ID. The details provided inlcude the Retrieval Reference Number (RRN) and transaction ID of the original transaction. The reason for resolving the dispute is specified in the adjustment code and the adjustment flag indicates the adjustment made. The transaction amount and currency are also provided. In this example, the dispute resolution is accepted by the beneficiary bank, as indicated by the transaction subtype.

curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json; charset=utf-8" -d '
{
  "dispute": {
    "name": "projects/PROJECT_ID/disputes/DISPUTE_ID",
    "details": {
      "originalTransaction": {
        "transactionId": "GOO4a69d250abe6433899c2f5a081000033882",
        "retrievalReferenceNumber": "013100747891"
      },
      "transactionSubType": "TRANSACTION_SUB_TYPE_BENEFICIARY",
      "amount": {
        "currencyCode": "INR",
        "units": "99",
        "nanos": 990000000
      },
      "originalSettlementResponseCode": "RB",
      "currentCycle": true
    },
    "resolveDisputeAdjustment": {
      "adjustmentFlag": "CHARGEBACK_ACCEPTANCE",
      "adjustmentCode": "CHARGEBACK_ACCEPTANCE_MERCHANT_CANNOT_PROVIDE_SERVICE"
    }
  }
}
    ' "https://ISSUER_SWITCH_API_ENDPOINT/v1/projects/PROJECT_ID/disputes/DISPUTE_ID:resolve"

In this example:

  • PROJECT_ID is the ID of your Google Cloud project.
  • DISPUTE_ID is the unique identifier of the dispute that you want to resolve.
  • $TOKEN is your OAuth 2.0 access token.
  • ISSUER_SWITCH_API_ENDPOINT is your issuer switch's API endpoint. For example, api.129a0b1a-bb73-4906-a5b7-a6e0bfe7860e.issuerswitch.goog.

Replace these with values specific to your environment.

When you run this command, you see a response similar to the following:

{
  "name": "projects/PROJECT_ID/operations/Q09NUExBSU5UIyNvcmlnUlJOJCRUUkFOU0FDVElPTl9TVUJfVFlQRV9SRU1JVFRFUg==",
  "metadata": null,
  "done": false
}