Skip to content
TatvaPay
Docs menu· REST API

REST API

Next

TatvaPay's REST API for agents and your servers.

Coming next. The API runs on the sandbox today (http://localhost:8100 on a local engine), with fake rails. api.tatvapay.com is not live yet.

  • Base URL: https://api.tatvapay.com (sandbox engine locally)
  • Machines call /v1/pay/…: your servers with an API key (Authorization: Bearer tpk_…), agents with a signature (TatvaPay-Agent-Signature).
  • People decide in the app: authorising a mandate, approving a payment or a refund, booking a forex deal. There is no API for those, on purpose.
  • Money is always integer paise (150000 is ₹1,500). Forex rates are integer ten-thousandths.
  • IDs are prefixed strings: agt_, mdt_, qt_, pi_, rcpt_, fxo_.
  • Idempotency: paying, refunds and forex quotes need an Idempotency-Key; the same key returns the same result.
  • Errors answer {"detail": {"code", "message"}}: see error codes and rule ids.

The OpenAPI document for /v1/pay/** is in the engine repository (docs/openapi.json) and served at /v1/openapi.json outside production.

Area Main routes
Agents POST /v1/pay/agents, PUT /v1/pay/agents/{id}/listing, GET /v1/pay/sellers
Mandates POST /v1/pay/mandates (a draft), GET /v1/pay/mandates
Quotes POST /v1/pay/quotes, POST /v1/pay/sellers/{id}/quotes, POST /v1/pay/quotes/{id}/preview
Payments POST /v1/pay/intents, GET /v1/pay/intents, POST /v1/pay/intents/{id}/refunds
Receipts GET /v1/pay/receipts/{id}, GET /v1/receipts/{id}/verify, GET /.well-known/tatvapay-keys.json
Forex /v1/pay/forex/… (Forex API)
Webhooks POST /v1/pay/webhooks (Webhooks)

Last updated 2 October 2026

Something unclear or wrong? Tell us