# Payment evidence v2

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 |

## cURL example

```bash
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"
```

## JavaScript example

```js
// 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](/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`.