API documentation

Overview

https://ppromm.com

https://ppromm.com/api/public/openapi.json

1. Register your app in the PProMM console (Clients) and copy the API key and webhook secret.
2. When your customer uploads a receipt, POST the image plus what you expected to be paid.
3. Act on the verdict. If it is pending_review, poll the status endpoint or wait for the signed webhook.

Authentication

Send your API key in the x-api-key header on every request. Keys start with rv_ and must never be exposed in browser code — call PProMM from your backend.

x-api-key: rv_live_xxxxxxxxxxxxxxxxxxxx

A missing, invalid, or deactivated key returns 401 Invalid or inactive API key.

POST /api/public/verify-receipt

Submits a receipt image for verification. Responds synchronously with the verdict.

curl -X POST https://ppromm.com/api/public/verify-receipt \
  -H "x-api-key: rv_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "image_base64": "data:image/jpeg;base64,/9j/4AAQ...",
    "expected_amount": 25000,
    "currency": "MMK",
    "expected_receiver": "Aung Aung",
    "wallet": "kpay",
    "reference": "order_9182",
    "callback_url": "https://your-app.com/api/public/payment-webhook"
  }'

200 OK
{
  "submission_id": "0f3c9d1e-2b7a-4c55-9f21-8a1d4e6b7c90",
  "verdict": "approved",
  "confidence": 0.94,
  "reason": "Amount, receiver and transaction ID all matched.",
  "reason_codes": [],
  "extracted": {
    "wallet": "KBZPay",
    "amount": 25000,
    "currency": "MMK",
    "sender": "Mg Mg",
    "receiver": "Aung Aung",
    "receiver_account": "09xxxxxxxxx",
    "txn_id": "1234567890",
    "paid_at": "2026-08-16T12:04:00Z",
    "notes": null
  },
  "checks": [
    { "id": "amount", "label": "Amount matches", "passed": true },
    { "id": "receiver", "label": "Receiver matches", "passed": true },
    { "id": "duplicate", "label": "Transaction not reused", "passed": true }
  ],
  "ai_verdict": "genuine"
}

GET /api/public/verify-receipt/{id}

Polls a submission. Only submissions belonging to your API key are visible. Use it while a verdict is pending_review.

curl https://ppromm.com/api/public/verify-receipt/0f3c9d1e-2b7a-4c55-9f21-8a1d4e6b7c90 \
  -H "x-api-key: rv_live_xxx"

200 OK
{
  "submission_id": "0f3c9d1e-…",
  "reference": "order_9182",
  "verdict": "approved",
  "confidence": 0.72,
  "reason": "Approved by reviewer",
  "reason_codes": ["LOW_CONFIDENCE"],
  "extracted": { "…": "…" },
  "checks": [ "…" ],
  "reviewed_at": "2026-08-16T12:20:11Z",
  "created_at": "2026-08-16T12:05:02Z"
}

Recommended polling: every 10 seconds for up to 15 minutes, then fall back to the webhook.

Verdicts

Reason codes

Webhooks

When a reviewer finalises a pending_review submission, PProMM POSTs to your callback URL.

POST https://your-app.com/api/public/payment-webhook
X-Receipt-Timestamp: 1755350411000
X-Receipt-Signature: <hex hmac-sha256>
Content-Type: application/json

{
  "event": "verification.reviewed",
  "submission_id": "0f3c9d1e-…",
  "reference": "order_9182",
  "verdict": "approved",
  "reviewed_at": "2026-08-16T12:20:11Z",
  "note": "Bank app screenshot confirmed",
  "extracted": { "…": "…" }
}

Verify the signature before trusting the payload: it is an HMAC-SHA256 of `${timestamp}.${rawBody}` using your webhook secret (whsec_…).

import { createHmac, timingSafeEqual } from "crypto";

const raw = await request.text();
const ts = request.headers.get("x-receipt-timestamp")!;
const sig = request.headers.get("x-receipt-signature")!;
const expected = createHmac("sha256", process.env.PAYMENTPRO_SECRET_KEY!)
  .update(`${ts}.${raw}`)
  .digest("hex");

if (!timingSafeEqual(Buffer.from(sig), Buffer.from(expected))) {
  return new Response("Invalid signature", { status: 401 });
}
const payload = JSON.parse(raw);

Respond with 2xx. Non-2xx responses are recorded as a failed delivery on the submission.

Errors

Duplicate protection is global: once a transaction ID is accepted it can never be reused, so your app does not need its own duplicate check.