Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Sumitbose5/tktplz/llms.txt

Use this file to discover all available pages before exploring further.

TktPlz uses Razorpay as its payment gateway. The payment flow is: create an order (server-side), complete payment in the Razorpay checkout (client-side), then verify the HMAC-SHA256 signature (server-side). On successful verification, the booking is finalised and tickets are issued. Refunds are processed back through Razorpay and tracked in the refunds table.

​
POST /api/payment/createOrder

Creates a Razorpay order. This endpoint runs the getPrices and calculateTicketPrices middlewares before the controller, so the request body must include the same fields required by the booking summary endpoint.
Items must already be locked via POST /api/booking/get-booking-summary before calling this endpoint. The convenience fee is calculated in the calculateTicketPrices middleware.
​
eventId
string
required
UUID of the event.
​
userId
string
required
UUID of the user making the purchase.
​
eventType
string
required
"Seating", "Open", "Online", or "Registration".
​
item
array
required
Seat UUIDs for Seating events, or { type, count } objects for other types.
​
selectedSeats
array
Array of seat UUIDs — required for Seating events.
​
eventDetails
object
Object containing at least { type } — required for Open and Online events.
​
categoriesBody
array
Array of { id, type, count, price } — required for Open and Online events.
curl -X POST https://api.tktplz.me/api/payment/createOrder \
  -H "Content-Type: application/json" \
  -d '{
    "eventId": "event-uuid",
    "userId": "user-uuid",
    "eventType": "Seating",
    "item": ["seat-uuid-1"],
    "selectedSeats": ["seat-uuid-1"]
  }'
Response
​
success
boolean
true on success.
​
orderId
string
Razorpay order ID to pass to the Razorpay checkout SDK.
​
amount
number
Total amount in INR (not paise).
​
currency
string
Always "INR".
​
receipt
string
Razorpay receipt string in the format order_{eventId[:6]}_{userId[:6]}_{timestamp}.
​
orderDetails
object
​
eventDetails
object
{
  "success": true,
  "orderId": "order_Razorpay123",
  "amount": 275.00,
  "currency": "INR",
  "receipt": "order_abc123_def456_1718000000000",
  "orderDetails": {
    "totalSeatAmount": 250.00,
    "totalConvenienceFee": 25,
    "gstAmount": 0,
    "totalAmount": 275.00,
    "itemDetails": [
      { "id": "seat-uuid-1", "seatLabel": "A5", "category": "Normal", "price": 250.00, "convenienceFee": 25 }
    ]
  },
  "eventDetails": {
    "eventId": "event-uuid",
    "eventName": "Inception (2010)",
    "eventType": "Seating"
  }
}

​
POST /api/payment/verifyPayment

Verifies the Razorpay payment signature using HMAC-SHA256 and, on success, completes the booking by creating a CONFIRMED ticket record.
​
razorpay_order_id
string
required
The Razorpay order ID returned from createOrder.
​
razorpay_payment_id
string
required
The Razorpay payment ID from the checkout callback.
​
razorpay_signature
string
required
The HMAC-SHA256 signature from the checkout callback.
​
eventId
string
required
UUID of the event.
​
userId
string
required
UUID of the user.
​
selectedSeats
array
Seat UUIDs — for Seating events.
​
eventDetails
object
Event metadata — for Open/Online events.
​
categories
array
Ticket categories — for Open/Online events.
​
totalAmount
number
required
Grand total in INR.
​
totalConvenienceFee
number
Convenience fee total.
curl -X POST https://api.tktplz.me/api/payment/verifyPayment \
  -H "Content-Type: application/json" \
  -d '{
    "razorpay_order_id": "order_Razorpay123",
    "razorpay_payment_id": "pay_AbcDef123",
    "razorpay_signature": "hmac_signature",
    "eventId": "event-uuid",
    "userId": "user-uuid",
    "selectedSeats": ["seat-uuid-1"],
    "totalAmount": 275.00,
    "totalConvenienceFee": 25
  }'
Response 
{ "success": true, "message": "Payment verified" }
Failure 
{ "error": "Invalid signature" }

​
POST /api/payment/refund

Initiates a refund for a CONFIRMED ticket via Razorpay. The ticket status is updated to "CANCELLED - REFUND DUE" immediately, then an async refund is created. A confirmation email is sent to the user.
​
orderId
string
required
The Razorpay order ID associated with the ticket to refund.
​
refundAmount
number
Amount to refund in INR. Defaults to the full totalAmount on the ticket. Cannot exceed the original ticket amount.
curl -X POST https://api.tktplz.me/api/payment/refund \
  -H "Content-Type: application/json" \
  -d '{"orderId": "order_Razorpay123"}'
Response
​
success
boolean
True on success.
​
message
string
Human-readable status message.
​
data
object
{
  "success": true,
  "message": "Refund initiated successfully",
  "data": {
    "refundId": "rfnd_Abc123",
    "orderId": "order_Razorpay123",
    "amount": 275.00,
    "status": "processing",
    "estimatedProcessingTime": "5-7 business days"
  }
}

​
GET /api/payment/payout-summary

Requires admin authentication (moderator role).
Returns all payout records enriched with event name and organiser name. 
curl https://api.tktplz.me/api/payment/payout-summary \
  --cookie "tktplz_cookie=<admin-token>"
Response 
{
  "success": true,
  "data": [
    {
      "id": "payout-uuid",
      "eventId": "event-uuid",
      "organizerId": "org-uuid",
      "totalRevenue": "50000.00",
      "deductions": "2500.00",
      "netPayable": "47500.00",
      "status": "pending",
      "availableToOrg": false,
      "paymentMethod": null,
      "eventName": "Battle of Bands",
      "organiserName": "Rhythm Events"
    }
  ]
}

​
GET /api/payment/payout/:id

Returns details for a single payout record, enriched with event and organiser names.
​
id
string
required
UUID of the payout record.
curl https://api.tktplz.me/api/payment/payout/payout-uuid
Response fields
​
id
string
Payout UUID.
​
eventId
string
Associated event UUID.
​
organizerId
string
Organiser UUID.
​
totalRevenue
string
Total revenue collected (decimal string).
​
deductions
string
Platform deductions (decimal string).
​
netPayable
string
Amount payable to the organiser.
​
status
string
"pending", "paid", or "cancelled".
​
paymentMethod
string
Payment method used: "UPI", "Bank Transfer", or "RazorpayX".
​
paidAt
string
ISO 8601 timestamp when payout was marked paid.
​
availableToOrg
boolean
Whether the organiser can see this payout in their dashboard.
​
allTicketsDetails
array
JSON blob of ticket details included in the payout calculation.
​
eventName
string
Resolved event name.
​
organiserName
string
Resolved organiser name.

​
POST /api/payment/payout/:id/mark-as-paid

Requires organiser authentication (organiser role). Also requires a verificationText that must match the server-side VERIFICATION_TEXT environment variable.
Marks a payout as paid and records the paidAt timestamp.
​
id
string
required
UUID of the payout to mark as paid.
​
verificationText
string
required
Server-side verification string. Must match the VERIFICATION_TEXT environment variable.
curl -X POST https://api.tktplz.me/api/payment/payout/payout-uuid/mark-as-paid \
  -H "Content-Type: application/json" \
  --cookie "tktplz_cookie=<organiser-token>" \
  -d '{"verificationText": "secret-text"}'
Response 
{ "success": true, "message": "Payout marked as paid" }

Build docs developers (and LLMs) love

Get started for freeTalk to us