Payments API
The one integration a merchant writes. It doesn't change when payment methods are turned on or off. Every route, field and error is in the API reference; all docs are at /docs.
1. Create a payment from your server
POST /api/v1/payments
Authorization: Bearer sk_test_{tenant}_…
Idempotency-Key: ord-ACM-20931
Content-Type: application/json
{ "amount": 149900, "currency": "INR", "reference": "ACM-20931",
"description": "Full-stack course", "return_url": "https://acme.in/orders/ACM-20931",
"customer": { "email": "rahul@example.com" }, "metadata": { "plan": "monthly" } }
Amounts are integers in paise. The response has id, status and checkout_url. The same Idempotency-Key with the same body returns the same payment.
2. Send the payer to checkout_url
PayLink shows the methods you turned on (PayLink UPI, and the Simulator in Test), runs the flow and returns the payer to return_url?payment_id=…&status=….
3. Trust the signed webhook
PayLink-Signature: t=1760900120,v1=<hex HMAC-SHA256 of "{t}.{raw body}" with your whsec_ secret>
PayLink-Event: payment.succeeded
Events: payment.processing, payment.on_hold, payment.succeeded, payment.failed, payment.cancelled, payment.expired. Retries for 24 hours.
| Route | What it does |
|---|---|
| POST /api/v1/payments | Create a payment |
| GET /api/v1/payments/{id} | Status, attempts, how it was paid or why it failed |
| GET /api/v1/payments | List, newest first (status, reference, limit, offset) |
| POST /api/v1/payments/{id}/cancel | Cancel an open payment |
| /api/tenant/… | Tenant automation API (tdk_ keys): payments, UPI verification and statements, methods, webhooks, risk rules. Guide |
Statuses
created → requires_action → processing → succeeded | failed | cancelled | expired, plus on_hold when a risk rule asks for review. Final statuses never change.