Payment evidence v2 — NiriPay Docs

Accepts merchant-owned payment evidence. This endpoint is separate from the v1 screenshot submission API.

Multipart fields#

Field	Type	Required	Description
`transaction_id`	String	Yes	Your merchant transaction ID
`utr`	String	Yes	Exactly 12 digits
`screenshots`	Image file	Yes	One or two images; maximum 10 MB per file
`upi_id`	String	No	Customer-supplied recipient UPI ID
`frontend_ocr`	JSON string	No	Array of `{ "utr": string, "upi_ids": string[] }` hints; backend OCR remains authoritative for evidence matching

Request example

Server-side

curl -X POST https://api.niripay.com/api/v2/merchant/deposits/evidence \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "transaction_id=ORDER-2026-001" \
  -F "utr=123456789012" \
  -F "screenshots=@payment-receipt.png"

// Server-side JavaScript. screenshotFile is a Blob or File read on your server.
const form = new FormData();
form.append("transaction_id", "ORDER-2026-001");
form.append("utr", "123456789012");
form.append("screenshots", screenshotFile, "payment-receipt.png");
const response = await fetch(
  "https://api.niripay.com/api/v2/merchant/deposits/evidence",
  { method: "POST", headers: { Authorization: `Bearer ${process.env.NIRIPAY_API_KEY}` }, body: form }
);
const result = await response.json();
if (!response.ok || result.status !== "success") {
  throw new Error(result.message || "Evidence submission failed");
}

Accepted response#

HTTP 201 indicates acceptance. These example IDs are illustrative. Read the actual returned code and ocr_state; processing can still be in progress.

JSON

{
  "status": "success",
  "message": "Payment evidence accepted",
  "data": {
    "evidence_id": "EXAMPLE_EVIDENCE_ID",
    "code": "ANALYZING",
    "message": {
      "en": "Screenshot accepted. We are checking the payment details.",
      "hi": "स्क्रीनशॉट मिल गया है। हम भुगतान विवरण जाँच रहे हैं।"
    },
    "requested_transaction_id": "EXAMPLE_INTERNAL_TRANSACTION_ID",
    "matched_transaction_id": null,
    "ocr_state": "pending"
  }
}

Response transaction identifiers describe resolved internal order references. Retain your original merchant transaction ID for the merchant status API.

Evidence outcomes#

Code	Meaning
`ANALYZING`	Screenshot processing is pending
`MATCHED_CURRENT_ORDER`	Evidence matches the current order
`MATCHED_OTHER_ORDER`	Evidence matches another eligible recent order
`MASKED_RECIPIENT`	Recipient information is hidden; review is needed
`MISSING_UTR` / `MISSING_RECIPIENT`	Required details could not be read
`OCR_CONFLICT` / `AMBIGUOUS_ORDER`	Details conflict or more than one order may match
`UPI_NOT_OURS`	Recipient does not match eligible payment instructions
`DUPLICATE_PENDING` / `DUPLICATE_SUCCESS`	The transaction reference is already associated with a payment
`MANUAL_REVIEW`	Evidence needs operator review
`VERIFIED`	Screenshot UTR and recipient match; not a final payment success status
`NATIVE_SCREENSHOT_UNSUPPORTED`	This flow does not apply to a native payment order

Confirm the payment separately#

Never credit an order on evidence acceptance or OCR verification alone. Query deposit status with the original merchant transaction ID and reconcile the final payment status.

Validation failures return HTTP 400; classified conflicts may return HTTP 409 with details under data.code and data.message.