Run ticketing from your own product.

1. 1 Create a key at Developer → API keys. It is shown once.
2. 2 Send it as x-api-key on every request.
3. 3 Call /me to confirm which account it belongs to.

curl https://events.vihaya.app/api/v1/me \
  -H "x-api-key: $VIHAYA_API_KEY"

Then create an event. It is always created as a draft — it has no public page until you publish it.

curl -X POST https://events.vihaya.app/api/v1/events \
  -H "x-api-key: $VIHAYA_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "title": "TechFest 2027",
    "description": "Two days of workshops and talks.",
    "startDate": "2027-03-01",
    "location": "Kollam",
    "capacity": 300,
    "price": 250
  }'

The date field is startDate, not date. The response echoes both, which misleads on a second read.

Every request carries x-api-key. A key is bound to one account and can only ever see that account's events — there is no way to widen it, and no uid or email is ever read from a request body.

• Revocation is immediate. A revoked key returns 403 on the next call.
• Origin pinning is optional. Restrict a key to your domains and a request from anywhere else is refused. Server-to-server calls send no Origin and are unaffected.
• Publishing needs organiser access. Check canPublish on /me; without it a publish returns 403 while everything else works.
• Keys are stored hashed. We cannot show you a key again — rotate it instead.

A whole sandbox account, selected by the key you call with. Build and run your whole integration — registration, payment, check-in, webhooks — without charging anyone, emailing anyone, or putting an event in front of the public.

Why the mode is in the key, not a header. A header would let one credential act on real or fake data depending on a value your code controls — one forgotten header away from a test suite confirming real registrations, emailing real attendees and moving real money. Because the prefix carries it, a key is permanently one or the other, it is visible in every log and code review, and a test key pasted into production config fails loudly instead of quietly doing damage.

The rules

• A test key can only act on TEST EVENTS. Create one by calling POST /events with the test key — it is stamped automatically.
• A live key can never touch a test event, and a test key can never touch a live one. Both directions return 403 with an explanation.
• GET /events returns only the events belonging to your key's mode, so test fixtures never appear in a live listing.
• A test event can NEVER be published. It has no public page, appears in no search or listing, and cannot sell a real ticket.
• Test events are fee-exempt, so they can never contribute to a payout, a revenue total or an organiser balance.

End to end in four calls

# 1. Mint a test key (dashboard, or POST /v1/keys with { "mode": "test" })
export VIHAYA_TEST_KEY=vihaya_test_sk_...

# 2. Everything below is fake. Nothing is charged, nobody is emailed.
curl -X POST https://events.vihaya.app/api/v1/events \
  -H "x-api-key: $VIHAYA_TEST_KEY" \
  -H "content-type: application/json" \
  -d '{ "title": "Fixture", "description": "Scratch event",
        "startDate": "2027-01-01", "price": 250 }'
# -> 201, isTestEvent: true, status: "draft" (always)

# 3. Register somebody. A PAID test event returns a REAL Razorpay order.
curl -X POST .../events/{id}/register \
  -H "x-api-key: $VIHAYA_TEST_KEY" \
  -d '{ "name": "Asha", "email": "asha@example.com" }'
# -> { orderId, registrationId, amount, currency, key: "rzp_test_..." }
#    Open Razorpay Checkout with that key, pay with a TEST card, then POST
#    again with { registrationId, orderId, paymentId } to confirm — the same
#    two calls as production.

# 4. Admit them at your own door.
curl -X POST .../events/{id}/check-in \
  -H "x-api-key: $VIHAYA_TEST_KEY" \
  -d '{ "registrationId": "..." }'
# -> { success: true, changed: true, data: { checkedIn: true, ... } }

Test mode is the real flow, on a test account. Test mode runs the REAL two-call flow against Vihaya's Razorpay TEST account. You get a real order, open real Razorpay Checkout with the `key` we return, pay with Razorpay's test cards or test UPI, and confirm with the payment id exactly as in production. The only difference is which Razorpay account it runs on — `rzp_test_` credentials cannot move real money. Your integration is therefore genuinely exercised rather than simulated, and the code path is identical to live.

Emails and webhooks

Nothing is emailed. Ticket delivery is off on every test event, and a broadcast always previews however you set `dryRun` — the addresses in your test data may well be real ones, and "it was only a test" is not something you can say to whoever received the mail. The preview still returns the true recipient count and sample, so the endpoint is fully testable.

Webhooks DO fire in test mode — that is the point. `registration.confirmed` is delivered and signed exactly as in production, so you can drive your receiver end to end without a real booking.

What it is not

• It is not a separate database you can seed in bulk — create test events through the API like any other.
• It runs on Vihaya's Razorpay test account, not yours. You are testing the integration, not your own gateway settlement.
• Test events still appear in your own dashboard, badged as test. They are drafts, so nobody else can see them.

A free event is one call and it is confirmed immediately. A paid event is two, because the payment itself has to happen in the buyer's browser.

POST https://events.vihaya.app/api/v1/events/{eventId}/register
{ "name": "Asha Menon", "email": "asha@example.com", "phone": "+919000000000" }

→ 200
{
  "orderId":        "order_TZud2hMOtfhq9f",
  "registrationId": "pNd1m0TRqN8Hx5a1QopI",
  "amount":         25000,            // paise
  "currency":       "INR",
  "key":            "rzp_live_..."    // public key — safe in a browser
}

// 2. Your front end opens Razorpay Checkout with that key + orderId.
//    On success Razorpay hands you a razorpay_payment_id.

POST https://events.vihaya.app/api/v1/events/{eventId}/register
{
  "registrationId": "pNd1m0TRqN8Hx5a1QopI",
  "orderId":        "order_TZud2hMOtfhq9f",
  "paymentId":      "pay_XXXXXXXXXXXX"
}

→ confirmed. Ticket + QR issued.

A paymentId alone is never proof of payment. We verify it against Razorpay and bind it to both the order and the registration before anything is confirmed — a forged id is refused and the registration stays pending.

Settlement: payments are collected into Vihaya's Razorpay account, not yours. The organiser withdraws from the dashboard and funds land by UPI in about two working days. Ask us before building if you need direct settlement.

All seven wrap the same four calls and the same base URL, so the shape is identical whichever you pick.

import { VihayaClient } from 'vihaya-sdk';

const vihaya = new VihayaClient(process.env.VIHAYA_API_KEY);

const events = await vihaya.events.list();
const result = await vihaya.events.register(eventId, {
  name: 'Asha Menon',
  email: 'asha@example.com',
  phone: '+919000000000',
});

Which account does this key belong to, and what may it do?

Create and manage events. A new event is always a draft until you publish it.

A festival with several bookable sessions. Each track carries its own date, price and capacity.

Take bookings from your own front end. This is the headless path — see the walkthrough above.

Email an event's own attendees. You can never name a recipient.

Charge members on a repeating UPI AutoPay mandate. A first slice — see the limits below before you build on it.

Run your own gate. Scan a ticket, admit it, undo a mistake — the same rules the Vihaya check-in desk uses.

Configure where we push booking notifications, without clicking through the dashboard.

We POST to an endpoint you own the moment something happens, so you do not have to poll.

Configure it two ways. In the dashboard at /profile/integrations, or over the API with GET / PUT / DELETE /api/v1/webhooks. The signing secret is generated by us, returned once, and never readable again. One endpoint per organiser account, covering every event they own.

• Must be https. Plain http is refused.
• Must resolve to a public host — loopback, link-local and RFC1918 literals are refused, because we POST to this from our own servers.
• Redirects are NOT followed. A 302 is the standard way to walk a validated public URL round to an internal one.

Events

There is exactly one. Subscribing to any other name means nothing will ever arrive.

The payload

POST <your endpoint>
X-Vihaya-Event:     registration.confirmed
X-Vihaya-Timestamp: 1789430651760          // unix MILLISECONDS, not seconds
X-Vihaya-Signature: sha256=<hex>           // note the prefix
Content-Type:       application/json

{
  "type":      "registration.confirmed",
  "createdAt": "2027-09-01T10:04:11.760Z",
  "data": {
    "registrationId": "pNd1m0TRqN8Hx5a1QopI",  // the booking — stable for its whole life
    "ticketCode":     "pNd1m0TRqN8Hx5a1QopI",  // ← this IS the QR payload (changes on a transfer)
    "eventId":        "8fK2...",
    "eventTitle":     "TechFest 2027",
    "name":           "Asha Menon",
    "email":          "asha@example.com",
    "phone":          "+919000000000",
    "ticketType":     "VIP",        // null if the event has no tiers
    "subEventId":     null,         // the track, when one was booked
    "quantity":       1,            // seats this ONE booking admits
    "amountPaid":     25000,
    "currency":       "INR",
    "paymentStatus":  "paid"        // or "free"
  }
}

Verifying the signature

// The signature covers `${timestamp}.${rawBody}` — the RAW bytes,
// before any JSON.parse. Parsing and re-stringifying changes them.
import crypto from 'crypto';

const timestamp = req.headers['x-vihaya-timestamp'];

// ⚠️ The header value is PREFIXED. Strip it before comparing, or the two
// buffers are different lengths and timingSafeEqual THROWS.
const signature = String(req.headers['x-vihaya-signature']).replace(/^sha256=/, '');

const expected = crypto
  .createHmac('sha256', process.env.VIHAYA_WEBHOOK_SECRET)   // sha256, NOT sha512
  .update(`${timestamp}.${rawBody}`)
  .digest('hex');

const ok = crypto.timingSafeEqual(
  Buffer.from(signature, 'hex'),
  Buffer.from(expected, 'hex'),
);
if (!ok) return res.status(401).end();

// Reject anything older than five minutes.
if (Date.now() - Number(timestamp) > 5 * 60_000) return res.status(401).end();

Delivery guarantees

A dropped delivery is gone. Nothing is retried, so reconcile against GET /events/{id}/registrations rather than treating the webhook as a durable queue.

The registration id, as a plain string. Example: pNd1m0TRqN8Hx5a1QopI No URL, no JSON, no signature — just the id.

So you never need an endpoint from us to draw a ticket. The moment you have the registration id you have the whole payload, and you can render the QR yourself at any size, in any format, inside your own ticket design. There is no endpoint that returns a QR image, and there does not need to be.

Where to get the id

• registrationId from POST /events/{id}/register
• registrationId from the registration.confirmed webhook
• id on each row of GET /events/{id}/registrations

Rendering it

// Any QR library. This is exactly what our own mailer does.
import QRCode from 'qrcode';

const png = await QRCode.toBuffer(registrationId, {
  type: 'png', width: 480, margin: 1, errorCorrectionLevel: 'M',
});

The scanner additionally parses `{"eventId":"…","registrationId":"…"}` if you would rather encode JSON. A bare id is what Vihaya itself emits.

Team bookings issue one ticket per member, each with its OWN id. The webhook carries the primary registration id; pull the roster to get each member's.

Vihaya’s ticket email is not customisable — but you do not have to use it. Everything needed to send your own already crosses the wire, so it is your template, your domain and your sender reputation.

Switching our delivery off does NOT reduce your platform fee today. The delivery slice of the rate is currently 0% — the published rate and the platform's own rate are the same number — so there is nothing to give back. Do not plan around a discount.

Every failure returns the same shape:

{ "error": "A sentence describing what went wrong." }

Rate limits