Transaction Query Endpoint

Retrieve detailed information about a transaction using its unique reference number.

This endpoint allows merchants to query and fetch complete details of a transaction, including tickets, metadata, and pricing breakdowns. Use this endpoint to verify transaction status, retrieve booking details for customer support, or reconcile payments.

CRITICAL - How Our Transaction System Works

Our system is designed to only create transactions when they are successful. This means:

• ✅ Transactions are ONLY created when payment succeeds AND booking is confirmed

• ✅ Your wallet is ONLY debited when the transaction is successful

• ❌ If a purchase attempt fails (experience has passed, bus seats are full, room unavailable), we return a failed response

• ❌ Failed attempts DO NOT debit your wallet

• ❌ Failed attempts DO NOT create transaction records

Result: If a transaction exists in our system, it is guaranteed to be successful. There are no failed or pending transactions in our database.

---

Query Transaction Details

GET /api/v1/merpi/transaction/{reference}

Fetch detailed information about a specific transaction using its reference number.

Path Parameters

Parameter	Type	Required	Description
reference	string	Yes	Unique transaction reference number. Format varies by transaction type:<br/>- Experience: EX + numbers (e.g., EX142799733)<br/>- Transportation: TR + numbers (e.g., TR196608948)<br/>- Hospitality: HTL + numbers (e.g., HTL103088777)

Query Transaction Details by Reference

get

Retrieves detailed information about a transaction using its unique reference number.

Important: Our system only creates transactions when they are successful. If a purchase attempt fails (e.g., experience has passed, bus seats are full, room unavailable), we return a failed response and DO NOT debit your wallet or create a transaction record.

This endpoint returns comprehensive transaction details including tickets, metadata, and pricing breakdowns. The response structure varies based on the transaction type (Experience, Transportation, or Hospitality).

Path parameters

referencestringRequired

Unique transaction reference number. Format varies by transaction type:

• Experience: EX + numbers (e.g., EX142799733)
• Transportation: TR + numbers (e.g., TR196608948)
• Hospitality: HTL + numbers (e.g., HTL103088777)

Example: EX142799733

Responses

200

Transaction found successfully.

application/json

successbooleanOptionalExample: true

statusintegerOptionalExample: 200

messagestringOptionalExample: Transaction Found

400

Bad request due to invalid or missing reference parameter.

application/json

404

Transaction not found with the provided reference.

application/json

500

Internal server error.

application/json

get

/v1/merpi/transaction/{reference}

HTTPcURLJavaScriptPython

GET /v1/merpi/transaction/{reference} HTTP/1.1
Accept: */*

{
  "success": true,
  "status": 200,
  "message": "Transaction Found",
  "data": {
    "reference": "EX142799733",
    "status": "success",
    "transaction_type": "Experience",
    "amount": "3,000.00",
    "charges": "10.00",
    "business_commission": "45.00",
    "transaction_id": "TEX242799381",
    "customer_email": "[e-mail]",
    "purchased_at": "07-08-2024 12:59 PM",
    "ticket": [
      {
        "id": "6e436de1-887d-4fca-9a69-a4fcb379ecfa",
        "price": 3000,
        "count": 1
      }
    ],
    "metadata": {
      "experience": {
        "id": "850bf763-6be5-44e0-8f96-7a6357129436",
        "title": "Laughing away all these burdens",
        "cinema": false,
        "address": {
          "street": "123 Comedy Lane",
          "town": "Ikeja",
          "city": "Lagos",
          "country": "Nigeria"
        },
        "image": [
          {
            "image": "https://dev.syticks.com/storage/EventPhotos/AoiTwDj94pfwu85hs5aWaDMet9kB5QeqgMiJGsxQ.jpg"
          }
        ],
        "business": {
          "id": "0384a1ce-9933-4452-966e-9a0d09d17015",
          "name": "Your Fav Ticket Vendor",
          "photo": "https://dev.syticks.com/storage/profilePhotos/qr3JZSnpxxxNKQ7mbaBS0P00qejPzxXp7tQ8rgtM.jpg",
          "slug": "your-fav-ticket-vendor",
          "type": "entertainment"
        },
        "category": {
          "id": "04655360-5e8c-4683-887b-4f58147e1751",
          "slug": "bus",
          "name": "Bus"
        },
        "start_date": "2023-03-05T17:30:00",
        "end_date": "2023-07-06T06:00:00"
      },
      "tickets": [
        {
          "id": "6e436de1-887d-4fca-9a69-a4fcb379ecfa",
          "title": "Laugh like a big man",
          "quantity": 1,
          "price": 3055,
          "price_breakdown": {
            "ticket_price": 3000,
            "convenience_fee": 10,
            "merchant_commission": 45
          }
        }
      ]
    }
  }
}

Responses

Status	Description
200	Successfully retrieved transaction details
400	Bad Request - Invalid or missing reference parameter
404	Not Found - Transaction doesn't exist
500	Internal Server Error

---

Response Format

Root Response Object

Field	Type	Description
success	boolean	Indicates whether the request was successful.
status	integer	HTTP status code (200 for successful requests).
message	string	Human-readable description of the response.
data	object	Transaction details object.

Data Object (Common Fields)

All transaction types share these common fields:

Field	Type	Description
reference	string	Unique transaction reference.
status	string	Transaction status. Always "success" since only successful transactions are stored.
transaction_type	string	Type of transaction: "Experience", "Transportation", or "Hospitality".
amount	string	Total transaction amount (formatted with commas).
charges	string	Convenience fee charged.
business_commission	string	Commission paid to merchant.
transaction_id	string	Internal transaction ID (prefixed with TEX, TTR, or THO).
customer_email	string	Email of the customer who made the purchase.
purchased_at	string	Date and time of purchase (format: DD-MM-YYYY HH:MM AM/PM).
ticket	array	Ticket information. Structure varies by transaction type.
metadata	object	Additional transaction details. Structure varies by transaction type.

---

Response Differences by Transaction Type

1. Experience Transaction (Non-Cinema)

Ticket Structure (Experience - Non-Cinema):

• id - Ticket type ID

• price - Base ticket price

• count - Number of tickets purchased

Metadata Structure:

• experience - Complete experience details

• tickets - Array of ticket type details with price breakdowns

---

2. Experience Transaction (Cinema)

Additional Cinema Fields:

• attendance_date - Date the customer will attend the movie

• time - Specific showtime details (start and end time)

---

3. Transportation Transaction (Timed Schedule)

Ticket Structure (Transportation - Timed):

• price - Ticket price per seat

• seat_id - Specific seat ID assigned to the passenger

Metadata Structure:

• departure_date - Date and time of departure

• schedule_bus - Complete schedule and bus details

• time.departure - The exact time the bus departs on the departure date (for timed schedules)

---

4. Transportation Transaction (Random Schedule)

Ticket Structure (Transportation - Random):

• id - null for random schedules

• price - Total ticket price

• count - Number of tickets

• seat_count - Number of seats (0 for random since no specific seat assignment)

• total_amount - Total amount for all tickets

Key Difference: Random schedules don't assign specific seats (seat_id), so the ticket structure is different.

---

5. Hospitality Transaction (Hotel Booking)

Ticket Structure (Hospitality):

• price - Room price

• room_id - Specific room ID

Metadata Structure:

• checkin_date - Check-in date (YYYY-MM-DD)

• checkout_date - Check-out date (YYYY-MM-DD)

• number_of_nights - Length of stay

• number_of_rooms - Number of rooms booked

• number_of_guests - Total number of guests

• hotel - Complete hotel details

• room - Room details

• booking_number - Unique booking confirmation number

Additional Fields:

• booking_number - Also available at root level for easy access

• price_breakdown - Also available at root level

---

Request Examples

Using cURL

curl -X GET "https://api.syticks.com/api/v1/merpi/transaction/EX142799733" \
  -H "Accept: application/json"

Using JavaScript (Fetch)

const reference = 'EX142799733';

fetch(`https://api.syticks.com/api/v1/merpi/transaction/${reference}`, {
  method: 'GET',
  headers: {
    'Accept': 'application/json'
  }
})
  .then(response => response.json())
  .then(data => {
    if (data.success) {
      console.log('Transaction details:', data.data);
      console.log('Transaction type:', data.data.transaction_type);
    } else {
      console.error('Transaction not found');
    }
  })
  .catch(error => console.error('Error:', error));

Using Python (Requests)

import requests

reference = 'TR196608948'
url = 'https://api.syticks.com/api/v1/merpi/transaction/'
params = {'reference': reference}

response = requests.get(url, params=params, headers={'Accept': 'application/json'})
data = response.json()

if data['success']:
    transaction = data['data']
    print(f"Transaction Type: {transaction['transaction_type']}")
    print(f"Amount: {transaction['amount']}")
    print(f"Status: {transaction['status']}")
else:
    print("Transaction not found")

Using PHP

<?php
$reference = 'HTL103088777';
$url = 'https://api.syticks.com/api/v1/merpi/transaction/' . urlencode($reference);

$options = [
    'http' => [
        'method' => 'GET',
        'header' => 'Accept: application/json'
    ]
];

$context = stream_context_create($options);
$response = file_get_contents($url, false, $context);
$data = json_decode($response, true);

if ($data['success']) {
    $transaction = $data['data'];
    echo "Transaction Type: " . $transaction['transaction_type'] . "\n";
    echo "Amount: " . $transaction['amount'] . "\n";
}
?>

---

Understanding Transaction Types

Identifying Transaction Type

You can determine the transaction type in two ways:

1. From the reference prefix:

   • EX + numbers = Experience

   • TR + numbers = Transportation

   • HTL + numbers = Hospitality

2. From the transaction_type field in the response:

   • "Experience"

   • "Transportation"

   • "Hospitality"

Handling Different Response Structures

function handleTransactionResponse(data) {
  if (!data.success) {
    console.error('Transaction query failed:', data.message);
    return;
  }

  const transaction = data.data;
  
  switch (transaction.transaction_type) {
    case 'Experience':
      handleExperienceTransaction(transaction);
      break;
      
    case 'Transportation':
      handleTransportationTransaction(transaction);
      break;
      
    case 'Hospitality':
      handleHospitalityTransaction(transaction);
      break;
      
    default:
      console.error('Unknown transaction type');
  }
}

function handleExperienceTransaction(transaction) {
  const { metadata } = transaction;
  const isCinema = metadata.experience.cinema;
  
  if (isCinema) {
    console.log('Cinema booking:', metadata.experience.title);
    console.log('Showtime:', metadata.time.start, '-', metadata.time.end);
    console.log('Date:', metadata.attendance_date);
  } else {
    console.log('Event booking:', metadata.experience.title);
    console.log('Event dates:', metadata.experience.start_date, 'to', metadata.experience.end_date);
  }
  
  // Display tickets
  metadata.tickets.forEach(ticket => {
    console.log(`Ticket: ${ticket.title} x ${ticket.quantity} = ${ticket.price}`);
  });
}

function handleTransportationTransaction(transaction) {
  const { metadata } = transaction;
  const schedule = metadata.schedule_bus;
  
  console.log('Bus booking:', schedule.name);
  console.log('Route:', schedule.from, '→', schedule.to);
  console.log('Departure:', metadata.departure_date);
  
  if (schedule.route.schedule_type === 'timed') {
    console.log('Departure time:', schedule.time.departure);
    console.log('Seats:', transaction.ticket.map(t => t.seat_id).join(', '));
  } else {
    console.log('Operating window:', schedule.time.departure, '-', schedule.time.arrival);
    console.log('Tickets:', transaction.ticket[0].count);
  }
}

function handleHospitalityTransaction(transaction) {
  const { metadata } = transaction;
  
  console.log('Hotel booking:', metadata.hotel.name);
  console.log('Room:', metadata.room.room_name);
  console.log('Check-in:', metadata.checkin_date);
  console.log('Check-out:', metadata.checkout_date);
  console.log('Nights:', metadata.number_of_nights);
  console.log('Booking number:', metadata.booking_number);
}

---

Common Use Cases

1. Customer Support - Transaction Lookup

async function lookupCustomerTransaction(reference) {
  const response = await fetch(
    `/api/v1/merpi/transaction/${reference}`
  );
  const data = await response.json();
  
  if (!data.success) {
    return {
      found: false,
      message: 'Transaction not found. Please verify the reference number.'
    };
  }
  
  const transaction = data.data;
  
  return {
    found: true,
    reference: transaction.reference,
    type: transaction.transaction_type,
    amount: transaction.amount,
    customer: transaction.customer_email,
    date: transaction.purchased_at,
    details: formatTransactionDetails(transaction)
  };
}

function formatTransactionDetails(transaction) {
  switch (transaction.transaction_type) {
    case 'Experience':
      return {
        event: transaction.metadata.experience.title,
        location: transaction.metadata.experience.address,
        tickets: transaction.metadata.tickets.length
      };
      
    case 'Transportation':
      return {
        route: `${transaction.metadata.schedule_bus.from} → ${transaction.metadata.schedule_bus.to}`,
        departure: transaction.metadata.departure_date,
        seats: transaction.ticket.length
      };
      
    case 'Hospitality':
      return {
        hotel: transaction.metadata.hotel.name,
        checkin: transaction.metadata.checkin_date,
        checkout: transaction.metadata.checkout_date,
        booking_number: transaction.booking_number
      };
  }
}

2. Payment Reconciliation

async function reconcileTransaction(reference) {
  const response = await fetch(
    `/api/v1/merpi/transaction/${reference}`
  );
  const data = await response.json();
  
  if (!data.success) {
    return { status: 'not_found' };
  }
  
  const transaction = data.data;
  
  // Extract financial details
  const financials = {
    reference: transaction.reference,
    transaction_id: transaction.transaction_id,
    total_amount: parseFloat(transaction.amount.replace(/,/g, '')),
    convenience_fee: parseFloat(transaction.charges),
    merchant_commission: parseFloat(transaction.business_commission),
    customer_email: transaction.customer_email,
    purchase_date: transaction.purchased_at,
    status: transaction.status // Always 'success'
  };
  
  // Calculate net amount (what merchant receives)
  financials.merchant_receives = 
    financials.total_amount - 
    financials.convenience_fee - 
    financials.merchant_commission;
  
  return {
    status: 'found',
    financials: financials
  };
}

3. Generating Booking Confirmation

async function generateBookingConfirmation(reference) {
  const response = await fetch(
    `/api/v1/merpi/transaction/${reference}`
  );
  const data = await response.json();
  
  if (!data.success) {
    throw new Error('Transaction not found');
  }
  
  const transaction = data.data;
  
  let confirmation = {
    reference: transaction.reference,
    transactionId: transaction.transaction_id,
    customer: transaction.customer_email,
    purchasedAt: transaction.purchased_at,
    totalAmount: transaction.amount,
    status: transaction.status
  };
  
  // Add type-specific details
  if (transaction.transaction_type === 'Experience') {
    const exp = transaction.metadata.experience;
    confirmation.type = 'Event Ticket';
    confirmation.eventName = exp.title;
    confirmation.venue = `${exp.address.street}, ${exp.address.city}`;
    confirmation.eventDate = exp.start_date;
    confirmation.tickets = transaction.metadata.tickets;
    
    if (exp.cinema) {
      confirmation.showtime = `${transaction.metadata.time.start} - ${transaction.metadata.time.end}`;
      confirmation.attendanceDate = transaction.metadata.attendance_date;
    }
  } 
  else if (transaction.transaction_type === 'Transportation') {
    const schedule = transaction.metadata.schedule_bus;
    confirmation.type = 'Bus Ticket';
    confirmation.route = `${schedule.from} → ${schedule.to}`;
    confirmation.departureDate = transaction.metadata.departure_date;
    confirmation.departureTime = schedule.time.departure;
    confirmation.terminal = schedule.terminal.name;
    confirmation.bus = schedule.bus.name;
    
    if (schedule.route.schedule_type === 'timed') {
      confirmation.seats = transaction.ticket.map(t => t.seat_id);
    }
  }
  else if (transaction.transaction_type === 'Hospitality') {
    const meta = transaction.metadata;
    confirmation.type = 'Hotel Booking';
    confirmation.hotelName = meta.hotel.name;
    confirmation.hotelLocation = `${meta.hotel.city}, ${meta.hotel.state}`;
    confirmation.roomType = meta.room.room_name;
    confirmation.roomNumber = meta.room.room_number;
    confirmation.checkin = meta.checkin_date;
    confirmation.checkout = meta.checkout_date;
    confirmation.nights = meta.number_of_nights;
    confirmation.bookingNumber = meta.booking_number;
  }
  
  return confirmation;
}

4. Verifying Transaction Before Refund

async function verifyBeforeRefund(reference) {
  const response = await fetch(
    `/api/v1/merpi/transaction/${reference}`
  );
  const data = await response.json();
  
  if (!data.success) {
    return {
      canRefund: false,
      reason: 'Transaction not found'
    };
  }
  
  const transaction = data.data;
  
  // Verify transaction status (should always be 'success')
  if (transaction.status !== 'success') {
    return {
      canRefund: false,
      reason: 'Transaction was not successful'
    };
  }
  
  // Check if refund window is still open (example: 24 hours)
  const purchaseDate = new Date(
    transaction.purchased_at.replace(
      /(\d{2})-(\d{2})-(\d{4}) (\d{2}):(\d{2}) (AM|PM)/,
      '$3-$2-$1 $4:$5 $6'
    )
  );
  
  const now = new Date();
  const hoursSincePurchase = (now - purchaseDate) / (1000 * 60 * 60);
  
  if (hoursSincePurchase > 24) {
    return {
      canRefund: false,
      reason: 'Refund window has closed (24 hours)'
    };
  }
  
  return {
    canRefund: true,
    transaction: transaction,
    refundAmount: parseFloat(transaction.amount.replace(/,/g, ''))
  };
}

---

Key Differences Between Transaction Types

Feature	Experience	Transportation (Timed)	Transportation (Random)	Hospitality
Reference Prefix	EX	TR	TR	HTL
Ticket Structure	{id, price, count}	{price, seat_id}	{id, price, count, seat_count, total_amount}	{price, room_id}
Seat Assignment	No	Yes (specific seats)	No (general admission)	Room assignment
Date Field	start_date, end_date	departure_date	departure_date	checkin_date, checkout_date
Confirmation Number	No	No	No	Yes (booking_number)
Cinema Variation	Yes (cinema: true/false)	No	No	No
Schedule Type	N/A	timed	random	N/A

---

Error Handling

400 - Bad Request

Occurs when the reference parameter is missing or invalid:

{
  "success": false,
  "status": 400,
  "message": "Invalid reference format"
}

Common causes:

• Missing reference parameter

• Invalid reference format

• Reference contains invalid characters

404 - Not Found

Occurs when no transaction exists with the provided reference:

{
  "success": false,
  "message": "Transaction with Reference: EX142799733",
  "errors": "Transaction not found",
  "status": 404
}

Response fields:

• message - Includes the reference that was searched

• errors - Error description

Common causes:

• Transaction reference doesn't exist

• Typo in reference number

• Attempting to query a failed transaction (which doesn't exist in our system)

500 - Internal Server Error

{
  "success": false,
  "status": 500,
  "message": "An error occurred while processing your request"
}

Error Handling Example

async function safeTransactionQuery(reference) {
  try {
    const response = await fetch(
      `/api/v1/merpi/transaction/${reference}`
    );
    
    const data = await response.json();
    
    if (!data.success) {
      switch (data.status) {
        case 400:
          throw new Error('Invalid reference format. Please check the reference number.');
        case 404:
          throw new Error(`${data.errors} - Reference: ${reference}`);
        case 500:
          throw new Error('Server error. Please try again later.');
        default:
          throw new Error(data.errors || data.message || 'Unknown error occurred');
      }
    }
    
    return data.data;
    
  } catch (error) {
    console.error('Transaction query error:', error.message);
    throw error;
  }
}

---

Important Notes

Why Only Successful Transactions Exist

Our platform follows a strict "success-only" transaction model:

1. Validation happens BEFORE wallet debit: We check availability (seats, rooms, event status) before attempting payment

2. Atomic operations: Payment and booking confirmation happen together

3. No partial states: Either the entire transaction succeeds, or nothing is recorded

4. Wallet safety: Your wallet is never debited unless the booking is confirmed

This means:

• ✅ If you can query a transaction, it was successful

• ✅ If payment was debited, the booking was confirmed

• ❌ Failed attempts don't appear in transaction queries

• ❌ No "pending" or "processing" states exist

Transaction Reference Patterns

Experience transactions:

• Format: EX + 9 digits

• Example: EX142799733

Transportation transactions:

• Format: TR + 9 digits

• Example: TR196608948

Hospitality transactions:

• Format: HTL + 9 digits

• Example: HTL103088777

Date Format Handling

The API returns dates in different formats depending on the field:

• purchased_at: DD-MM-YYYY HH:MM AM/PM (e.g., "07-08-2024 12:59 PM")

• departure_date: Day, DD Mon YYYY HH:MM AM/PM (e.g., "Wed, 09 Apr 2025 08:21 PM")

• checkin_date / checkout_date: YYYY-MM-DD (e.g., "2026-03-03")

• start_date / end_date: ISO 8601 (e.g., "2023-03-05T17:30:00")

Always parse dates appropriately based on the field you're working with.

---

Next Steps

After querying a transaction, you can:

• Generate confirmation emails - Send booking details to customers

• Print tickets/vouchers - Use transaction details to generate printable tickets

• Track bookings - Build a dashboard to monitor all transactions

• Process refunds - Verify transaction details before issuing refunds

• Customer support - Quickly look up transaction details for support inquiries

• Reconciliation - Match transactions with payment records

---

Related Endpoints

• Get Experience Details - View full experience information

• Get Bus Schedules - Browse available bus schedules

• Get Hotel Rooms - View available hotel rooms

• Create Booking - Make new bookings/purchases