---
updatedAt: 2026-05-14T13:09:07.000Z
agentTools:
  projectIndex: https://developer.onefinops.com/llms.txt
---

# Decode Signed QR

Decodes a NIC IRP signed-QR JWS into its 10-field payload. The signature is verified against NIC IRP's public certificate; on signature failure the response is `400 einvoice.signature.invalid` (production) or a warning with decoded claims (sandbox).


# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "OneFinOps API",
    "version": "1.0.0",
    "summary": "Programmatic access to the Indian GSTN portal — IRN registration, e-Way Bills, and GSP credential management.",
    "description": "The OneFinOps GST API lets you generate IRNs (e-invoices), manage e-Way Bills, and onboard GSP\ncredentials directly against your tenant. This reference documents every public endpoint exposed\non `api.in.onefinops.com` (production) and `sandbox-api.in.onefinops.com` (sandbox).\n\nAll endpoints are authenticated with OAuth 2.0 client credentials. See **Authentication** in the\nguides for token issuance, scope semantics, and SDK examples.\n",
    "contact": {
      "name": "OneFinOps Developer Support",
      "email": "developers@onefinops.com",
      "url": "https://onefinops.com"
    },
    "license": {
      "name": "Proprietary"
    }
  },
  "servers": [
    {
      "url": "https://api.in.onefinops.com",
      "description": "Production"
    },
    {
      "url": "https://sandbox-api.in.onefinops.com",
      "description": "Sandbox"
    }
  ],
  "tags": [
    {
      "name": "E-Invoice",
      "description": "Generate, fetch, cancel and poll IRN registrations against the NIC IRP."
    }
  ],
  "security": [
    {
      "oauth2": []
    }
  ],
  "paths": {
    "/v1/einvoices/decodeqr": {
      "post": {
        "tags": [
          "E-Invoice"
        ],
        "operationId": "decodeSignedQr",
        "summary": "Decode Signed QR",
        "description": "Decodes a NIC IRP signed-QR JWS into its 10-field payload. The signature is verified against NIC IRP's public certificate; on signature failure the response is `400 einvoice.signature.invalid` (production) or a warning with decoded claims (sandbox).\n",
        "security": [
          {
            "oauth2": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/GstinHeader"
          },
          {
            "$ref": "#/components/parameters/RequestIdHeader"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DecodeQrRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Decoded QR payload.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/QrDecodeResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "422": {
            "$ref": "#/components/responses/ValidationError"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "oauth2": {
        "type": "oauth2",
        "description": "OAuth 2.0 client credentials flow. Mint your token from `login.onefinops.com` using your `ofin_live_*` (production) or `ofin_test_*` (sandbox) credentials issued from the Developer console. The realm attaches `onefinops.api` as a **default scope** to every `ofin_*` client at provision time — you do not pass `scope=...` on the token request. The minted access token carries `aud=onefinops.api` and `client_class=external_customer`.",
        "flows": {
          "clientCredentials": {
            "tokenUrl": "https://login.onefinops.com/realms/onefinops/protocol/openid-connect/token",
            "scopes": {}
          }
        }
      }
    },
    "parameters": {
      "GstinHeader": {
        "in": "header",
        "name": "gstin",
        "required": true,
        "description": "GSTIN whose NIC IRP / EWB-portal credential authorizes the call.\nSeed each GSTIN's credential through the Developer Console.\n",
        "schema": {
          "type": "string",
          "pattern": "^[0-9]{2}[A-Z]{5}[0-9]{4}[A-Z][A-Z0-9]{3}$",
          "minLength": 15,
          "maxLength": 15,
          "example": "05AAACG2409A1ZH"
        }
      },
      "RequestIdHeader": {
        "in": "header",
        "name": "X-Request-Id",
        "required": false,
        "description": "Optional client-supplied UUID for correlation across logs and dashboards. If omitted, OneFinOps mints one and echoes it back on the response.",
        "schema": {
          "type": "string",
          "format": "uuid"
        }
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Request rejected.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ApiError"
            }
          }
        }
      },
      "Unauthorized": {
        "description": "Missing or invalid token.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ApiError"
            }
          }
        }
      },
      "ValidationError": {
        "description": "Body or query failed validation.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ApiError"
            }
          }
        }
      }
    },
    "schemas": {
      "ApiError": {
        "type": "object",
        "description": "Canonical error body returned on every 4xx / 5xx response. The HTTP\nstatus carries the category — there is no `httpStatus` field in the\nbody. NIC IRP / EWB rejections come through as the top-level `code`\n(numeric NIC code or `GSP_GATEWAY_REJECT` for non-NIC vendor errors);\nthe verbatim NIC text is preserved in `details` keyed by code.\n",
        "required": [
          "code",
          "message"
        ],
        "properties": {
          "code": {
            "type": "string",
            "description": "Stable machine-readable code. For NIC business errors this is the NIC numeric code (e.g. `\"382\"`); for our own errors it is a dotted identifier (e.g. `einvoice.cancel_window_expired`). Branch on this — never on `message`.",
            "examples": [
              "382",
              "einvoice.cancel_window_expired",
              "validation_error",
              "GSP_GATEWAY_REJECT"
            ]
          },
          "message": {
            "type": "string",
            "description": "Human-readable explanation. Safe to show end users, but not for programmatic logic."
          },
          "details": {
            "type": "object",
            "description": "Optional. Keys are error codes (or field paths on 422 validation\nfailures); values are arrays of messages. For NIC errors the\nverbatim message text from NIC is preserved here under the NIC\ncode key.\n",
            "additionalProperties": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "examples": [
              {
                "382": [
                  "You Cannot Extend as EWB can be Extended only 8 hour before or after w.r.t Validity of EWB"
                ]
              },
              {
                "documentDetails.documentDate": [
                  "The document date should not be a future date."
                ]
              }
            ]
          },
          "requestId": {
            "type": "string",
            "description": "Echoes the request id (X-Request-Id) for support correlation."
          },
          "traceId": {
            "type": "string",
            "description": "W3C trace-id for distributed-tracing correlation."
          },
          "timestamp": {
            "type": "string",
            "format": "date-time",
            "description": "UTC timestamp the error was generated."
          }
        }
      },
      "DecodeQrRequest": {
        "type": "object",
        "description": "Body for `POST /v1/einvoices/decodeqr`.",
        "required": [
          "signedQR"
        ],
        "properties": {
          "signedQR": {
            "type": "string",
            "description": "The signed QR JWS (JWT) returned by NIC at IRN generation.",
            "minLength": 1,
            "example": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjEwYWY4ZjU5LWY5ZDgtNDhmMy04NWZlIn0..."
          }
        }
      },
      "QrDecodeResponse": {
        "type": "object",
        "description": "Decoded payload of a NIC IRP signed-QR JWS. NIC packs ten fields into the QR JWS claims;\nwe surface each as a typed property so customers don't have to parse the embedded JSON.",
        "required": [
          "irn",
          "sellerGstin",
          "buyerGstin",
          "documentNumber",
          "documentType",
          "mainHsnCode"
        ],
        "properties": {
          "irn": {
            "type": "string",
            "description": "64-character IRN.",
            "minLength": 64,
            "maxLength": 64
          },
          "sellerGstin": {
            "type": "string",
            "description": "Seller GSTIN."
          },
          "buyerGstin": {
            "type": "string",
            "description": "Buyer GSTIN."
          },
          "documentNumber": {
            "type": "string",
            "description": "Document number."
          },
          "documentType": {
            "type": "string",
            "description": "Document type — INV / CRN / DBN.",
            "enum": [
              "INV",
              "CRN",
              "DBN"
            ]
          },
          "documentDate": {
            "type": "string",
            "format": "date",
            "nullable": true,
            "description": "Document date (wire `dd/MM/yyyy`)."
          },
          "totalInvoiceValue": {
            "type": "number",
            "format": "double",
            "nullable": true,
            "description": "Total invoice value."
          },
          "itemCount": {
            "type": "integer",
            "nullable": true,
            "description": "Line-item count."
          },
          "mainHsnCode": {
            "type": "string",
            "description": "Primary HSN code."
          },
          "irnDate": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "IRN issue timestamp."
          }
        }
      }
    }
  }
}
```