API Integration Guide

PaySeats provides a powerful REST API that allows you to integrate event management into your existing applications and workflows.

Getting Started

Authentication

All API requests require authentication using API keys:

curl -H "Authorization: Bearer YOUR_API_KEY" \
     https://api.payseats.com/v1/events

Base URL

All API endpoints are available at:

https://api.payseats.com/v1/

Rate Limits

  • Free tier: 100 requests per hour
  • Pro tier: 1,000 requests per hour
  • Enterprise: Custom limits available

Core Endpoints

Events

# List all events
GET /events

# Create a new event
POST /events
{
  "title": "My Event",
  "description": "Event description",
  "start_date": "2025-12-01T19:00:00Z",
  "end_date": "2025-12-01T22:00:00Z",
  "venue": "My Venue",
  "capacity": 100,
  "price": 25.00
}
# Get event details
GET /events/{event_id}

# Update event
PUT /events/{event_id}

# Delete event
DELETE /events/{event_id}

Tickets

# List tickets for an event
GET /events/{event_id}/tickets

# Create a ticket
POST /events/{event_id}/tickets
{
  "attendee_name": "John Doe",
  "attendee_email": "[email protected]",
  "quantity": 1
}
# Get ticket details
GET /tickets/{ticket_id}

# Check in attendee
POST /tickets/{ticket_id}/checkin

Attendees

# List attendees
GET /events/{event_id}/attendees

# Get attendee details
GET /attendees/{attendee_id}

# Update attendee information
PUT /attendees/{attendee_id}

Webhooks

Setting Up Webhooks

Configure webhooks to receive real-time notifications:

POST /webhooks
{
  "url": "https://your-app.com/webhooks/payseats",
  "events": ["ticket.created", "ticket.checked_in", "event.updated"]
}

Available Events

  • ticket.created - New ticket purchased
  • ticket.checked_in - Attendee checked in
  • event.created - New event created
  • event.updated - Event details changed
  • event.cancelled - Event cancelled
  • payment.completed - Payment processed
  • refund.processed - Refund completed

Webhook Security

Verify webhook authenticity using signatures:

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return signature === expectedSignature;
}

SDKs and Libraries

JavaScript/Node.js

npm install @payseats/sdk
import { PaySeatsClient } from '@payseats/sdk';

const client = new PaySeatsClient({
  apiKey: 'your-api-key',
  environment: 'production' // or 'sandbox'
});

// Create an event
const event = await client.events.create({
  title: 'My Event',
  description: 'Event description',
  startDate: new Date('2025-12-01T19:00:00Z'),
  capacity: 100,
  price: 25.00
});

// List events
const events = await client.events.list();

Python

pip install payseats-sdk
from payseats import PaySeatsClient

client = PaySeatsClient(
    api_key='your-api-key',
    environment='production'
)

# Create an event
event = client.events.create({
    'title': 'My Event',
    'description': 'Event description',
    'start_date': '2025-12-01T19:00:00Z',
    'capacity': 100,
    'price': 25.00
})

# List events
events = client.events.list()

PHP

composer require payseats/sdk
use PaySeats\PaySeatsClient;

$client = new PaySeatsClient([
    'api_key' => 'your-api-key',
    'environment' => 'production'
]);

// Create an event
$event = $client->events->create([
    'title' => 'My Event',
    'description' => 'Event description',
    'start_date' => '2025-12-01T19:00:00Z',
    'capacity' => 100,
    'price' => 25.00
]);

// List events
$events = $client->events->list();

Common Integration Patterns

Event Management System

// Sync events from your system to PaySeats
async function syncEvent(eventData) {
  try {
    const payseatsEvent = await client.events.create({
      title: eventData.name,
      description: eventData.description,
      start_date: eventData.startTime,
      venue: eventData.location,
      capacity: eventData.maxAttendees,
      price: eventData.ticketPrice
    });

    // Store PaySeats event ID in your system
    await updateLocalEvent(eventData.id, {
      payseatsEventId: payseatsEvent.id
    });

    return payseatsEvent;
  } catch (error) {
    console.error('Failed to sync event:', error);
    throw error;
  }
}

Check-in Integration

// Check in attendees from your system
async function checkInAttendee(ticketId) {
  try {
    const result = await client.tickets.checkIn(ticketId);

    // Update your local system
    await updateLocalAttendee(ticketId, {
      checkedIn: true,
      checkInTime: new Date()
    });

    return result;
  } catch (error) {
    console.error('Check-in failed:', error);
    throw error;
  }
}

Analytics Integration

// Fetch event analytics
async function getEventAnalytics(eventId) {
  try {
    const analytics = await client.events.getAnalytics(eventId);

    // Process and store analytics data
    await storeAnalytics(eventId, {
      totalTickets: analytics.total_tickets,
      soldTickets: analytics.sold_tickets,
      revenue: analytics.revenue,
      checkIns: analytics.check_ins
    });

    return analytics;
  } catch (error) {
    console.error('Failed to fetch analytics:', error);
    throw error;
  }
}

Error Handling

HTTP Status Codes

  • 200 - Success
  • 201 - Created
  • 400 - Bad Request
  • 401 - Unauthorized
  • 403 - Forbidden
  • 404 - Not Found
  • 429 - Rate Limited
  • 500 - Server Error

Error Response Format

{
  "error": {
    "code": "validation_error",
    "message": "Invalid event data",
    "details": {
      "field": "start_date",
      "reason": "Date must be in the future"
    }
  }
}

Retry Logic

async function apiCallWithRetry(apiCall, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      return await apiCall();
    } catch (error) {
      if (error.status === 429 && attempt < maxRetries) {
        // Rate limited, wait and retry
        await new Promise(resolve =>
          setTimeout(resolve, Math.pow(2, attempt) * 1000)
        );
        continue;
      }
      throw error;
    }
  }
}

Testing

Sandbox Environment

Use the sandbox environment for testing:

const client = new PaySeatsClient({
  apiKey: 'your-sandbox-api-key',
  environment: 'sandbox'
});

Test Data

  • All operations work with test data
  • No real payments are processed
  • Webhooks are sent to your test endpoints
  • Data is reset daily

Support and Resources

Documentation

  • API Reference: Complete endpoint documentation
  • SDK Documentation: Language-specific guides
  • Webhook Guide: Real-time integration patterns
  • Code Examples: Sample implementations

Community

  • Developer Forum: Ask questions and share solutions
  • GitHub Repository: Open source SDKs and examples
  • Slack Community: Real-time developer support
  • Office Hours: Weekly Q&A sessions

Getting Help

  • API Support: Technical integration assistance
  • Code Review: Get feedback on your implementation
  • Custom Integration: Enterprise integration services
  • Training: Developer workshops and training sessions