API

Create orders, collect payment references and receive verification results — everything the dashboard can do, from your own systems.

Webhooks

API keys

Security settings
Live key
pk_live_8f2c…d41a
Test key
pk_test_2d7a…c9e1
Sandbox
Base URL
https://api.payverify.example.com/v1

Authenticate every request with Authorization: Bearer <key>. All traffic is JSON over HTTPS; requests without a key return 401.

Endpoints

Six endpoints cover the full manual-payment lifecycle.

Method Endpoint What it does Example
POST /orders Create an order and get a hosted checkout URL View
GET /orders/{id} Retrieve an order with its verification state View
POST /orders/{id}/payment-reference Submit the customer’s UTR / transaction reference View
GET /payments/{id}/status Check a payment’s status and confidence score View
GET /transactions/{id} Fetch a detected transaction with both parser results View
POST /payment-methods Create a manual payment method shown at checkout View

Create order

POST/v1/orders

Creates an order and returns the hosted checkout URL the customer should open. The order stays in awaiting_payment until a reference is submitted.

Request — curl
curl -X POST https://api.payverify.example.com/v1/orders \ -H "Authorization: Bearer pk_live_8f2c…d41a" \ -H "Content-Type: application/json" \ -d '{ "amount": 2499, "currency": "INR", "payment_method": "upi", "description": "Premium Subscription", "customer": { "name": "John Doe", "email": "john@example.com" } }'
Response — 200
{ "id": "ORD-10428", "status": "awaiting_payment", "amount": 2499, "currency": "INR", "checkout_url": "https://pay.payverify.example.com/checkout?order=ORD-10428", "expires_at": "2026-09-02T16:04:09+05:30", "created_at": "2026-09-01T16:01:12+05:30" }

Get order

GET/v1/orders/{id}

Returns the order with its payment reference, verification status and the matched transaction, if any.

Request — curl
curl https://api.payverify.example.com/v1/orders/ORD-10428 \ -H "Authorization: Bearer pk_live_8f2c…d41a"
Response — 200
{ "id": "ORD-10428", "status": "verified", "amount": 2499, "currency": "INR", "customer": { "name": "John Doe", "email": "john@example.com" }, "payment": { "method": "upi", "reference": "928473928", "verification_status": "verified", "confidence": 99, "verified_at": "2026-09-01T16:04:07+05:30" } }

Submit payment reference

POST/v1/orders/{id}/payment-reference

What the checkout form calls when the customer clicks “I have paid”. The order moves to waiting_verification and the engine starts watching for the confirmation.

Request — curl
curl -X POST https://api.payverify.example.com/v1/orders/ORD-10428/payment-reference \ -H "Authorization: Bearer pk_live_8f2c…d41a" \ -H "Content-Type: application/json" \ -d '{ "transaction_id": "928473928", "payment_method": "upi", "sender_name": "John Doe" }'
Response — 200
{ "id": "ORD-10428", "status": "waiting_verification", "submitted_reference": "928473928", "payment_id": "PAY-3391", "confirmation_deadline": "2026-09-02T16:04:09+05:30" }

Check payment status

GET/v1/payments/{id}/status

Poll this after the webhook fires, or use it as the source of truth on your confirmation screen.

Request — curl
curl https://api.payverify.example.com/v1/payments/PAY-3391/status \ -H "Authorization: Bearer pk_live_8f2c…d41a"
Response — 200
{ "payment_id": "PAY-3391", "order_id": "ORD-10428", "status": "verified", "confidence": 99, "decision": "auto_approved", "verified_at": "2026-09-01T16:04:07+05:30" }

Get transaction

GET/v1/transactions/{id}

Returns one detected confirmation message with both parser results — useful for reconciling manual review decisions.

Request — curl
curl https://api.payverify.example.com/v1/transactions/TXN-88213 \ -H "Authorization: Bearer pk_live_8f2c…d41a"
Response — 200
{ "id": "TXN-88213", "source": "email", "connection": "HDFC Alerts Gmail", "amount": 2499, "currency": "INR", "transaction_id": "928473928", "receiving_account": "XX4921", "matched_order": "ORD-10428", "regex_result": "match", "ai_result": "match", "confidence": 99, "status": "verified", "received_at": "2026-09-01T16:04:04+05:30" }

Create payment method

POST/v1/payment-methods

Adds a manual method to the checkout. Account details, instructions and the matching parse rule are configured together.

Request — curl
curl -X POST https://api.payverify.example.com/v1/payment-methods \ -H "Authorization: Bearer pk_live_8f2c…d41a" \ -H "Content-Type: application/json" \ -d '{ "name": "UPI", "type": "upi", "currency": "INR", "upi_id": "streambox@upi", "instructions": "Pay exactly ₹2,499, then submit your UTR." }'
Response — 201
{ "id": "pm_upi_2f7a", "name": "UPI", "type": "upi", "currency": "INR", "upi_id": "streambox@upi", "status": "active", "automation_enabled": true }

Webhook events

Every status change above is also pushed to your callback endpoint, signed with your whsec_ secret. Six event types are delivered — treat these payloads as the authoritative feed.

  • payment.detectedA confirmation message arrived from a source
  • payment.pendingReference submitted, waiting for bank confirmation
  • payment.verifiedAmount, reference and account all confirmed
  • payment.review_requiredConfidence fell below the auto-approve band
  • payment.failedRejected, unmatched or the order expired
  • order.approvedThe order can be fulfilled
Configure the callback and view deliveries