Dispute Transfer API

The Dispute Transfer API enables ODR Institutions to automatically receive and register disputes on their platforms as soon as they are referred to them by SMART ODR. This documentation provides guidelines on how to implement this API to facilitate real-time dispute transfer from SMART ODR to your ODR Portal.

Introduction

When a dispute is registered on SMART ODR and is assigned to an ODR Institution, the Dispute Transfer API will trigger a POST request to the ODR Institution's specified endpoint. This ensures immediate transfer of dispute details for further processing.

Authentication

All incoming requests from SMART ODR will include a valid SMART ODR access token in the Authorization header. ODR Institutions should validate this token to ensure the request is from SMART ODR.

To setup authentication, please follow the guidelines provided below.

Authorization : `Signature keyId="${unique_key_id}|${token}|RS256" algorithm="RS256" type="transfer" created="${created}",expires="${expires}" `

{unique_key_id} - API Key generated by ODR Institution from SMART ODR

{token} - Signed JWT Token [RS256]

Token Payload

The payload of the JWT includes the following information:

• Primary POC's Email: The email address of the institution's primary Point of Contact.
• Primary POC's Phone Number: The phone number of the institution's primary Point of Contact.

---

Implementing the API

Endpoint URL

ODR Institutions should expose a POST endpoint to receive dispute details. The URL structure could be:

POST https://your-odr-platform.com/api/dispute-transfer

Request Payload

The POST request from SMART ODR will have the following JSON payload:

{
  "data": {
    "context": {
    "domain": "smartodr.in",
    "version": "1.1.0",
    "timestamp": "2023-05-25T05:23:03.443Z",
    "stamp_id": "b0d2f7e5-96a8-42d1-9c64-11e9a3c6a0bb"
  },
    "service": "online_arbitration",
    "disputeId": "XXXX-XX-201-08-32232",
    "caseRegisteredAt" : 2023-10-06T12:20:53.000Z,
    "primaryCaseRefAt" : 2023-10-06T12:20:53.000Z,
    "conciliationInitiatedAt" : 2023-11-09T03:46:37.000Z, 
    "status": "DUMMY_STATUS",
    "claimAmount": 1234,
    "category": "Depository Participants",
    "subCategory": "Depository Participants",
    "miiDetails": {
      "name": "Dummy MII DP",
      "address": "Dummy address",
      "email": "bse@gmail.com",
      "phone": "12345678",
      "poc": {
        "name": "Dummy MII",
        "email": "abc@gmail.com",
        "phone": "7878787878",
        "address": "address"
      }
    },
    "complainant": {
      "type": "Intermediary",
      "name": "Dummy Complainant",
      "email": "sayak@gmail.com",
      "phone": "9898989898",
      "organisation": {
        "name": "Dummy Intermediary DP",
        "address": "1305-A, A-Wing, Marathon Futurex Mafatlal Mills Compound N.M.Joshi Marg, Lower Parel",
        "poc": {
          "name": "Dummy User",
          "email": "sampleintermediary@gmail.com",
          "phone": "7878778787"
        }
      }
    },
    "respondent": {
      "type": "Intermediary",
      "name": "Dummy Intermediary User",
      "email": "sampleintermediary@gmail.com",
      "organisation": {
        "name": "Dummy Intermediary",
        "address": "dummy address",
        "poc": {
          "name": "Dummy Intermediary User",
          "email": "sampleintermediary@gmail.com",
          "phone": "7878787878"
        }
      }
    },
    "natureofDispute": [
      {
        "natureType": "Service",
        "subNatureType": "Non-execution of order",
        "description": "Test One",
        "files": [
          {
            "fileName": "file-1681212225017-notice_notice.pdf",
            "fileType": "application/pdf",
            "uploadedAt": "2023-08-16T11:44:26.174Z",
            "uploadedBy": "Dummy Intermediary User",
            "location": "Signed_URL"
          }
        ],
        "lastUpdatedBy": "Dummy Intermediary User",
        "ComplainComments": [
          {
            "description": "This dispute is fake",
            "createdAt": "2023-08-15T16:08:00.000Z",
            "NestedComments": [],
            "User": {
              "userName": "Dummy Intermediary User",
              "userType": "Intermediary",
              "Organisation": {
                "organisationName": "Dummy Intermediary SB + DP",
                "organisationType": "INTERMEDIARY"
              }
            }
          }
        ]
      }
    ]
  }
}

Hybrid Encryption for API Request Payload

To ensure secure communication, the API requires the payload to be encrypted before sending it via a POST request. The provided encryption function is a hybrid encryption scheme that utilizes both a symmetric key and a public key. Here's a detailed breakdown:

The function uses the following algorithms:

• Symmetric Key Encryption: AES-128-CBC
• Asymmetric Key Encryption: RSA

API Payload Structure

When sending encrypted data to the API, the payload should adhere to the following structure:

Payload Format

The payload should be an object with the following properties:

Example Payload

{
  "message": {
    "key": "encrypted-symmetric-key",
    "data": "encrypted-data",
    "vector": "initialization-vector"
  }
}

Decryption Function

To retrieve the original plaintext payload from the encrypted data sent in the API request, the decryption process involves utilizing the encrypted symmetric key, initialization vector (IV), and the private key. Here's a detailed breakdown:

The decryption process requires the following components:

• Encrypted Symmetric Key (key): The symmetric key used for encryption, encrypted with the public key

• Initialization Vector (vector): A random initialization vector used during encryption.

• Encrypted Data (data): The payload encrypted using AES with the symmetric key and IV.

• Private Key (privateKey): The private key used for decrypting the symmetric key.

To use JWT in your application, you need to generate an RSA key pair and share the public key with SMART ODR.

// Example usage of the decryption function
const decryptedPayload = decryptPayload(
  "base64-encoded-encrypted-symmetric-key",
  "base64-encoded-initialization-vector",
  "base64-encoded-encrypted-data",
  privateKey
)

log(decryptedPayload);

Versioning

The Dispute Transfer API is a versioned API. Updates are released quarterly.

• Initial Release:

  • Version 1.0.0

• Adding a New Feature:

  • Version 1.1.0

• Fixing a Bug:

  • Version 1.1.1

• Making a Backward-Incompatible Change:

  • Version 2.0.0

---

Usage Limitations

The Dispute Transfer API is available only to approved ODR Institutions.

The Dispute Transfer API doesn't support sending additional information back to SMART ODR.

---

Request Body Schema

Field	Type
message*	dispute_details

---

Response Body Schema

Field	Type
success*	Boolean
message*	{message}

---

Response Codes

Code	Description
200	Acknowledgement of Data received

Sample Response

Sample JSON success response sent by an ODR Institution

{
    "success" : true,
    "message" : "success_message"
    "stamp_id" : "{context.stamp_id}"
}

Sample JSON error response sent by an ODR Institution

{
    "success" : false,
    "message" : "error_message"
    "stamp_id" : "{context.stamp_id}"
}