Platforms (sandbox) · TatvaPay Docs

Coming next. The Platform API works on the sandbox today (wave T11). No real money moves. Payments into each business's own Razorpay account are built on Razorpay's documented partner API and wait for our partner approval; Razorpay is a planned integration, not a live partner yet.

The Platform API is for software that brings many businesses with it: AI automation platforms, chat-commerce products, booking and coaching tools. Each business you bring gets its own TatvaPay workspace and is paid into its own account. TatvaPay never holds the money, and neither does your platform.

What you get

Piece	What it does	Status
Platform keys	Your servers call `/v1/pay/platform` with a key that has the platform scope; an ordinary API key cannot	Next
Businesses (sub-merchants)	Each business has its own workspace, owner and seller agent; you see only the businesses you manage	Next
Onboarding hand-off	You can pre-fill the business's verification file; the owner finishes it, the payment partner's compliance team decides, and you get a webhook at every step	Next
The business's own payment account	The owner connects their own Razorpay account on Razorpay's page; payments settle to their bank	Planned (sandbox consent screen today)
Orders after the owner accepts	Items, packing and delivery lines; a pay link to a page with the business's name, "powered by TatvaPay" and a link back to you	Next
Refunds and cancellations	You cancel unpaid orders; refunds you ask for wait for the business's owner to approve in TatvaPay	Next
Fees and instalments	Fee plans, discount codes applied before the amount (no struck-through prices), AutoPay instalments, a pay link per instalment	Next
Referral statements	Computed statements of what an institute owes its referral partners; TatvaPay never pays them or holds the money	Next
Agents	Your AI agents collect for your businesses and pay TatvaPay sellers inside a mandate the business's owner set, over MCP	Next
Platform fees	A fee line is recorded on each order (0 by default); collecting it is not built yet	Planned

The flow

Turn on the Platform API in the app (Platform → Turn on), add your return hosts, make a platform key, and add a webhook endpoint under Developers → Webhooks with the platform events.
Bring a business: POST /v1/pay/platform/submerchants with your own reference, its name, the owner's email and kind (shop or institute).
Onboarding: the owner signs in to TatvaPay with that email and finishes the verification file; the payment partner decides. Then send the owner the link from POST …/submerchants/{id}/razorpay/connect.
An order: when the owner accepts an order on your side, POST …/submerchants/{id}/orders with an Idempotency-Key. Send the customer pay_url.
Paid: you get order.paid (signed). Move the order on your board.

curl -X POST "$TATVAPAY_URL/v1/pay/platform/submerchants/$SHOP/orders" \
  -H "Authorization: Bearer $TATVAPAY_PLATFORM_KEY" \
  -H "Idempotency-Key: accept:order_101" \
  -H "Content-Type: application/json" \
  -d '{"external_ref": "order_101", "accepted_by": "owner",
       "return_url": "https://your-platform.example/orders/order_101",
       "lines": [
         {"kind": "item", "name": "Truffle cake, 1 kg", "quantity": 1, "unit_paise": 120000},
         {"kind": "packing", "name": "Packing", "quantity": 1, "unit_paise": 4000},
         {"kind": "delivery", "name": "Delivery", "quantity": 1, "unit_paise": 6000}]}'

Money is always integer paise. The SDKs have the same calls: tatvapay.platform.Platform (Python) and Platform in @tatvapay/sdk.

Webhooks

submerchant.status, order.created, order.paid, order.failed (with retryable), order.cancelled, order.expired, refund.processed, order.refund_failed, settlement.processed, fee.instalment_paid, fee.instalment_failed, and mandate.* for AutoPay. Each delivery is signed with TatvaPay-Webhook-Signature and retried with backoff; see Webhooks.

Your agents

Collect for a business: give an agent a token with platform.collect for the businesses it serves. Over MCP it calls list_my_businesses, collect_for_business and get_business_order.
Buy for a business: register the agent in the business's workspace and ask for a mandate; the business's owner authorises it in TatvaPay. Then the agent uses the ordinary tools (find_seller, get_quote, pay_intent) and connectors. Above the mandate's limit, a person approves.
Tokens (tpa_…) are for MCP clients that can send only one header. They are scoped, expire and can be revoked at once. An agent can never approve anything.

Rules that do not bend

A business is paid into its own account. If its account is not connected, TatvaPay refuses the payment rather than take it anywhere else.
You act only for the businesses you manage, and a business's data is never shown to another.
Refunds always wait for a person in the business's workspace.
TatvaPay holds no RBI licence and never holds funds. See Trust and security.