ONDC Buyer App Util API'sVersion 1.0.0

Endpoint Details

This endpoint allows you to place orders by submitting encrypted transaction details along with an initialization vector for decryption.

endpoint:
  path: /company_order/place_order
  method: POST
  headers:
    - name: X-API-KEY
      required: true
      description: API key for authentication. This header will be used to identify the consuming channel of the API.
  requestBody:
    required: true
    content:
      application/json:
        schema:
          type: object
          required:
            - data
            - iv
          properties:
            data:
              type: string
              description: Encrypted JSON string containing transaction details (transactionId and companyOrderId)
            iv:
              type: string
              description: Initialization vector (IV) used for AES-CBC encryption
  responses:
    description: JSON object containing the status of the company order with encrypted voucher details.
  

Endpoint Url:

/company_order/place_order

Note: Append this path to the appropriate base URL mentioned in the Prerequisites section.

Endpoint Description and Usage:

This endpoint is used to place orders in the ONDC network. The request requires encrypted transaction data along with an initialization vector (IV) for AES-CBC encryption. The encrypted data should contain transaction ID and company order ID details. Upon successful placement, the API returns an ONDC order ID.

Security

All requests to this endpoint must be authenticated using the required headers as specified in the Prerequisites section. Additionally, sensitive transaction data must be encrypted using AES-CBC encryption with a proper initialization vector. Ensure that your API key is kept secure and not exposed in client-side code. Failure to provide valid authentication headers will result in a 401 Unauthorized error.

Sample Request:

Here is an example of a cURL command to place an order using this endpoint:

curl -X POST \
  {{base_url}}/company_order/place_order \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
  "data": "<encrypted-transaction-json>",
  "iv": "<initialization-vector>"
}'

Request Body Schema

The POST request requires the following JSON body with encrypted transaction data:

RequestBody:
  type: object
  required:
    - data
    - iv
  properties:
    data:
      type: string
      description: "Encrypted JSON string containing transaction details (transactionId and companyOrderId)"
      example: "<encrypted-transaction-json>"
    iv:
      type: string
      description: "Initialization vector (IV) used for AES-CBC encryption"
      example: "<initialization-vector>"

Decrypted Request Data Structure

The encrypted data field should contain the following JSON structure before encryption:

DecryptedRequestData:
  type: object
  properties:
    transactionId:
      type: string
      description: "Unique identifier for the transaction"
      example: "txn_123456789"
    companyOrderId:
      type: string
      description: "Unique identifier for the company order"
      example: "order_987654321"

Success Response

When the order is placed successfully, the API returns a JSON response with the ONDC order ID:

{
  "status": {
    "code": "200",
    "error": false
  },
  "message": "Success",
  "result": {
    "ondcOrderId": "POR4545GFGJ"
  }
}

Error Response

If there is an error with the request (e.g., invalid encryption, missing fields, authentication failure), the API will return a JSON object with error details:

{
  "status": {
    "code": "400",
    "error": true
  },
  "message": "Invalid request body or encryption error",
  "result": null
}

Response Schema (YAML)

The response schema for both success and error responses is as follows:

parameters:
  - name: status
    in: body
    description: Contains response metadata.
    required: true
    schema:
      type: object
      properties:
        code:
          type: string
          description: HTTP-style status code.
        error:
          type: boolean
          description: Indicates if the API encountered an error.

  - name: message
    in: body
    description: Human-readable message describing the result or error.
    required: true
    schema:
      type: string

  - name: result
    in: body
    description: Contains details of the result in case of success; will be null in case of an error.
    required: true
    schema:
      type: object
      nullable: true
      properties:	
    status:
      type: object
      properties:
        code:
          type: string
          example: "400"
        error:
          type: boolean
          example: true
    message:
      type: string
      example: "Invalid request body or encryption error"
    result:
      type: null
      example: null