Quickstart

This walkthrough takes you from “blank page” to “buyer purchased a ticket” in three calls. All snippets are plain fetch — no SDK required.

Prerequisites

Your tenant account_id (UUID) from UnderPass onboarding
The API base URL: https://api.underpass.com.co (dev: https://api-dev.underpass.com.co)

1. List events

Show the buyer what’s for sale. account_id is required so the response is scoped to your tenant.

const API = "https://api.underpass.com.co";
const ACCOUNT_ID = "00000000-0000-0000-0000-000000000000"; // your tenant UUID

async function listEvents() {
  const res = await fetch(
    `${API}/api/events/public?account_id=${ACCOUNT_ID}&limit=50`,
    { headers: { Accept: "application/json" } },
  );
  if (!res.ok) throw new Error(`List failed: ${res.status}`);
  const { data } = await res.json();
  return data.events; // → EventDto[] (see API reference for full shape)
}

// Hero image lives in `event.media[]`. Pick the one with `is_primary === true`.
function heroImage(event) {
  return event.media.find((m) => m.is_primary)?.url ?? event.media[0]?.url;
}

Render the list however you like — there’s no required UI. Note that data is { events: EventDto[], pagination: { page, limit, total, total_pages } }.

2. Fetch event detail (with tickets)

When a buyer picks an event, fetch the detail page. This includes selling stages, ticket types, prices, and locality info.

async function getEvent(slug) {
  const res = await fetch(
    `${API}/api/events/public/${encodeURIComponent(slug)}`,
    { headers: { Accept: "application/json" } },
  );
  if (!res.ok) throw new Error(`Get failed: ${res.status}`);
  const { data } = await res.json();
  return data; // → { id, name, slug, ticket_types: [...], selling_stages: [...], ... }
}

Each ticket_type has an id, name, price, available, and locality info. Render the picker, let the buyer select quantities.

Respect the purchase limits when rendering the picker: cap each ticket type’s selector at ticket_type.max_per_order, and the whole cart at the event’s max_tickets_per_order (both null = unlimited). These limits are also enforced server-side at checkout start — bypassing the UI just earns a 400.

3. Start checkout

After the buyer picks tickets + fills in their info, create the order:

async function startCheckout({ eventId, items, customer }) {
  const res = await fetch(`${API}/api/checkout/start`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      account_id: ACCOUNT_ID,
      event_id: eventId,
      items, // [{ ticket_type_id, quantity }]
      customer, // { email, name, phone, document_type, document_number }
    }),
  });
  if (!res.ok) throw new Error(`Checkout failed: ${res.status}`);
  const { data } = await res.json();
  return data; // → { order_id, payment_provider, redirect_url, total_amount }
}

A 400 here carries a machine code you should surface to the buyer instead of a generic failure — notably INSUFFICIENT_TICKETS (inventory ran out), MAX_PER_ORDER_EXCEEDED / MAX_TICKETS_PER_ORDER_EXCEEDED (per-order purchase limits), and MAX_TICKETS_PER_EMAIL_EXCEEDED (the email already holds the maximum tickets allowed for this event). See the API reference for the { code, message, detail } error shape. Redirect the buyer to redirect_url. They pay on the provider’s hosted checkout page (Bold). When done, they land back on a URL you provide (success_url / cancel_url — see the API reference for the full payload). If total_amount === 0 (courtesy / fully discounted), there’s no payment step — redirect_url will be your confirmation URL directly.

4. Poll order status

After the buyer returns from the payment page, you don’t know yet if the payment cleared. Poll the status endpoint until it resolves:

async function pollOrder(orderId, { intervalMs = 2000, maxAttempts = 30 } = {}) {
  for (let i = 0; i < maxAttempts; i++) {
    const res = await fetch(`${API}/api/checkout/status/${orderId}`);
    if (!res.ok) throw new Error(`Status failed: ${res.status}`);
    const { data } = await res.json();
    if (
      data.status === "confirmed" ||
      data.status === "partially_paid" ||
      data.status === "cancelled" ||
      data.status === "failed"
    ) {
      return data;
    }
    await new Promise((r) => setTimeout(r, intervalMs));
  }
  return { status: "pending" }; // give up — show "we'll email you when it confirms"
}

Tickets are emailed by UnderPass automatically when the order confirms — you don’t need to deliver them yourself.

End-to-end

const events = await listEvents();
const event = await getEvent(events[0].slug);
const session = await startCheckout({
  eventId: event.id,
  items: [{ ticket_type_id: event.ticket_types[0].id, quantity: 2 }],
  customer: {
    email: "buyer@example.com",
    name: "Jane Buyer",
    phone: "+573001112233",
    document_type: "CC",
    document_number: "123456789",
  },
});
window.location.href = session.redirect_url;
// ... buyer pays, returns to your `success_url` with `?order_id=...`
const result = await pollOrder(session.order_id);
console.log(result.status); // "confirmed"

Optional features

These slot into the same flow whenever the event has them enabled. Skip the ones your tenants don’t use. Validate a code before the user submits checkout. Some codes unlock hidden selling stages — re-fetch the event with ?unlocked_stages=... to reveal them.

async function validatePromoCode({ eventId, code }) {
  const res = await fetch(`${API}/api/promo-codes/validate`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ event_id: eventId, code }),
  });
  const { data } = await res.json();
  return data;
  // → { valid, effect_type, discount, unlocked_stages?, ... }
}

Pass the validated code on the startCheckout payload as promo_code so the backend re-applies the discount on order creation.

Sales links (private presales / promoter attribution)

A sales link is a per-event code that unlocks private selling stages and/or attributes the sale to a promoter. Validate before showing tickets:

async function validateSalesLink({ eventId, code }) {
  const res = await fetch(`${API}/api/sales-links/validate`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ event_id: eventId, code }),
  });
  const { data } = await res.json();
  return data;
}

When valid, fetch the event with ?link={code} so the response includes the unlocked private tickets:

const event = await fetch(`${API}/api/events/public/${slug}?link=${code}`)
  .then((r) => r.json()).then((b) => b.data);

Referrals

Show a referral program panel on event pages so buyers see what they’d earn for sharing:

async function getReferralProgram(eventId) {
  const res = await fetch(`${API}/api/referrals/program/${eventId}`);
  if (res.status === 404) return null; // event has no program
  const { data } = await res.json();
  return data; // → { tiers: [...], terms, ... }
}

If the buyer arrived via ?ref={code}, validate it before checkout:

async function validateReferralCode({ eventId, code }) {
  const res = await fetch(`${API}/api/referrals/validate`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ event_id: eventId, code }),
  });
  const { data } = await res.json();
  return data;
}

Pass the validated code on the startCheckout payload as referral_code for attribution.

What’s next

Full API reference

Every payload field, every response shape, every error code.

Identity & scoping

How account_id, ticket IDs, and (optionally) API keys gate access.

Need help?

Reach the UnderPass team at developers@underpass.com.co.

Getting started

Integration guides

Prerequisites

1. List events

2. Fetch event detail (with tickets)

3. Start checkout

4. Poll order status

End-to-end

Optional features

Sales links (private presales / promoter attribution)

Referrals

What’s next

Full API reference

Identity & scoping

Need help?

​Prerequisites

​1. List events

​2. Fetch event detail (with tickets)

​3. Start checkout

​4. Poll order status

​End-to-end

​Optional features

​Promo codes

​Sales links (private presales / promoter attribution)

​Referrals

​What’s next

Full API reference

Identity & scoping

​Need help?

Prerequisites

1. List events

2. Fetch event detail (with tickets)

3. Start checkout

4. Poll order status

End-to-end

Optional features

Promo codes

Sales links (private presales / promoter attribution)

Referrals

What’s next

Need help?