ODR Redirection API

This API simplifies the process by allowing you to send a user's email and phone number and receive a secure token in response. The token can then be processed to facilitate a hassle-free redirection.

Introduction

The ODR Redirection API enables the swift transfer of redirection details to the specified endpoint of the Redirection Institution as soon as a redirection is initiated on the SMART ODR platform.

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="redirect" 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:

• email: The email address of the user trying to redirect to the ODR Institution Portal.
• phone: The phone number of the user trying to redirect to the ODR Institution Portal.

---

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/redirect

Request Payload

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

{
  "message": {
    "context": {
    "domain": "smartodr.in",
    "version": "1.1.0",
    "timestamp": "2023-05-25T05:23:03.443Z",
    "stamp_id": "b0d2f7e5-96a8-42d1-9c64-11e9a3c6a0bb"
  },
   "disputeId" : "ABCD-EF-2024-01-987654",
   "email" : "abc@gmail.com",
   "userType" : "Investor"  // ["Investor","MII","ODR","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 ODR Redirection 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 ODR Redirection API is available only to approved ODR Institutions.

The ODR Redirection 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*	{redirection_url}

---

Response Codes

Code	Description
200	Acknowledgement of Data received

Sample Response

Sample JSON success response sent by an ODR Institution

{
    "success" : true,
    "message" : `redirection_url`,
    "stamp_id" : "{context.stamp_id}"
}

Sample JSON error response sent by an ODR Institution

{
    "success" : false,
    "message" : "error_message"
    "stamp_id" : "{context.stamp_id}"
    "errors" : [
        {
            "code": "ERROR_CODE_1",
            "message": "Error Description 1"

        }
    ]
}