REST API
NextTatvaPay's REST API for agents and your servers.
Coming next. The API runs on the sandbox today (
http://localhost:8100on a local engine), with fake rails.api.tatvapay.comis 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 (
150000is ₹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