> For the complete documentation index, see [llms.txt](https://syticks.gitbook.io/merpi-by-syticks/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://syticks.gitbook.io/merpi-by-syticks/api-reference/general-endpoints-get-all-businesses-transaction-requery-etc/transaction-query-endpoint.md).
# Transaction Query Endpoint
This endpoint is how you fetch the complete details of any transaction made through your platform. Whether you need to verify a booking, pull up ticket information for a customer, or reconcile payments, this is where you come to get the full picture.
#### How Our Transaction System Works
One thing worth understanding before you start querying: our system only creates a transaction record when a purchase is fully successful. Payment and booking confirmation happen together as one atomic operation. If anything fails along the way, no record is created and your wallet is not debited.
What this means in practice:
* If a transaction exists in our system, it succeeded. There are no failed or pending records.
* If your wallet was debited, the booking was confirmed.
* If a purchase attempt fails (the event has passed, bus seats are full, room is unavailable), we return a failed response and nothing is recorded.
* There are no "pending" or "processing" states in our database.
This also has an important implication for how you use this endpoint. If you query a reference and get a 404, it does not mean something went wrong on our end. It means no successful transaction exists under that reference.
### Querying a Transaction
There are two ways to look up a transaction on this endpoint, and you must provide at least one.
**By transaction reference**
Every successful purchase returns a `reference` in the response (e.g., `EX142799733`). Pass it as a query parameter:
```
GET /api/v1/merpi/transaction?reference=EX142799733
```
**By merchant reference**
If you passed a `merchant_reference` when making a purchase, you can use that instead:
```
GET /api/v1/merpi/transaction?merchant_reference=YOUR_REFERENCE
```
{% hint style="info" %}
This is useful when you want to tie a lookup directly to your own internal order or record ID without storing the MERPI reference separately. Both query methods return the same full transaction response.
{% endhint %}
Keep in mind: if you query by `merchant_reference` and get a 404, it means no successful purchase was recorded under that reference. The purchase either failed or was never made.
***
#### Query Transaction Details
**GET** `/api/v1/merpi/transaction`
> Retrieves detailed information about a transaction. You must provide either `reference` or `merchant_reference` as a query parameter. 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).
## Query Transaction Details
> Retrieves detailed information about a transaction.\
> \
> You must provide at least one of the following query parameters: \`reference\` or \`merchant\_reference\`.\
> \
> \*\*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).
```json
{"openapi":"3.0.3","info":{"title":"Syticks API","version":"1.0.0"},"paths":{"/api/v1/merpi/transaction":{"get":{"summary":"Query Transaction Details","description":"Retrieves detailed information about a transaction.\n\nYou must provide at least one of the following query parameters: `reference` or `merchant_reference`.\n\n**Important**: Our system only creates transactions when they are successful. If a purchase attempt fails\n(e.g., experience has passed, bus seats are full, room unavailable), we return a failed response and\nDO NOT debit your wallet or create a transaction record.\n\nThis endpoint returns comprehensive transaction details including tickets, metadata, and pricing breakdowns.\nThe response structure varies based on the transaction type (Experience, Transportation, or Hospitality).\n","operationId":"queryTransaction","parameters":[{"name":"reference","in":"query","required":false,"schema":{"type":"string"},"description":"The MERPI transaction reference returned at the time of purchase. Format varies by transaction type:\n- Experience: `EX` + numbers (e.g., `EX142799733`)\n- Transportation: `TR` + numbers (e.g., `TR196608948`)\n- Hospitality: `HTL` + numbers (e.g., `HTL103088777`)\n\nRequired if `merchant_reference` is not provided.\n"},{"name":"merchant_reference","in":"query","required":false,"schema":{"type":"string"},"description":"Your own reference passed at the time of purchase. Required if `reference` is not provided.\n"}],"responses":{"200":{"description":"Transaction found successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"status":{"type":"integer"},"message":{"type":"string"},"data":{"type":"object","properties":{"reference":{"type":"string","description":"Unique transaction reference."},"status":{"type":"string","enum":["success"],"description":"Transaction status. Always 'success' since only successful transactions are stored."},"transaction_type":{"type":"string","enum":["Experience","Transportation","Hospitality"],"description":"Type of transaction."},"amount":{"type":"string","description":"Total transaction amount."},"charges":{"type":"string","description":"Convenience fee charged."},"business_commission":{"type":"string","description":"Commission paid to merchant."},"transaction_id":{"type":"string","description":"Internal transaction ID."},"customer_email":{"type":"string","description":"Email of the customer who made the purchase."},"purchased_at":{"type":"string","description":"Date and time of purchase."},"merchant_reference":{"type":"string","nullable":true,"description":"Your reference for this transaction if provided at the time of purchase, null otherwise."},"ticket":{"type":"array","description":"Ticket information. Structure varies by transaction type.","items":{"type":"object"}},"metadata":{"type":"object","description":"Additional transaction details. Structure varies by transaction type."}}}}}}}},"400":{"description":"Bad request. Neither reference nor merchant_reference was provided, or the value passed is invalid.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"status":{"type":"integer"},"message":{"type":"string"}}}}}},"404":{"description":"Transaction not found with the provided reference.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string","description":"Message including the reference that was searched."},"errors":{"type":"string"},"status":{"type":"integer"}}}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"status":{"type":"integer"},"message":{"type":"string"}}}}}}}}}}}
```
**Query Parameters**
| Parameter | Type | Required | Description |
| -------------------- | ------ | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `reference` | string | Conditional | The MERPI transaction reference returned at the time of purchase (e.g., `EX142799733`, `TR196608948`, `HTL103088777`). Required if `merchant_reference` is not provided. |
| `merchant_reference` | string | Conditional | Your own reference passed at the time of purchase. Required if `reference` is not provided. |
**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`). |
| `merchant_reference` | string | Your reference for this transaction, if you provided one at the time of purchase. `null` if not provided. |
| `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
**By transaction reference:**
```bash
curl -X GET "https://api.syticks.com/api/v1/merpi/transaction?reference=EX142799733" \
-H "Accept: application/json"
```
**By merchant reference:**
```bash
curl -X GET "https://api.syticks.com/api/v1/merpi/transaction?merchant_reference=your-order-id-123" \
-H "Accept: application/json"
```
**Using JavaScript (Fetch)**
**By transaction reference:**
```javascript
const reference = 'EX142799733';
fetch(`https://api.syticks.com/api/v1/merpi/transaction?reference=${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));
```
**By merchant reference:**
```javascript
const merchantReference = 'your-order-id-123';
fetch(`https://api.syticks.com/api/v1/merpi/transaction?merchant_reference=${merchantReference}`, {
method: 'GET',
headers: {
'Accept': 'application/json'
}
})
.then(response => response.json())
.then(data => {
if (data.success) {
console.log('Transaction details:', data.data);
} else {
console.error('Transaction not found');
}
})
.catch(error => console.error('Error:', error));
```
***
### 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"`
***
### 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 neither `reference` nor `merchant_reference` is provided, or when the value passed is invalid:
```json
{
"success": false,
"status": 400,
"message": "Invalid reference format"
}
```
**Common causes:**
* Neither `reference` nor `merchant_reference` was included in the request
* Invalid reference format
* Reference contains invalid characters
#### **404 - Not Found**
Occurs when no transaction exists with the provided reference:
```json
{
"success": false,
"message": "Transaction with Reference: EX142799733 Not Found",
"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)
* Querying a `merchant_reference` that was never used in a successful purchase
#### **500 - Internal Server Error**
```json
{
"success": false,
"status": 500,
"message": "An error occurred while processing your request"
}
```
***
### 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
**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 based on the specific field you are 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
* **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**](/merpi-by-syticks/api-reference/experience-ticketing-events-parties-conference-comedy-and-more/get-experience-details.md) - View full experience information
* [**Get Bus Schedules**](/merpi-by-syticks/api-reference/bus-ticketing-routes-terminals-schedules-buses-purchase-etc/get-schedules-endpoint.md) - Browse available bus schedules
* [**Get Hotel Rooms**](/merpi-by-syticks/api-reference/hospitality-ticketing-hotels-resorts-apartments/get-hotel-apartment-resort-rooms.md) - View available hotel rooms
* [**Create Booking**](/merpi-by-syticks/api-reference/hospitality-ticketing-hotels-resorts-apartments/book-hotel-apartment-room-tickets.md) - Make new bookings/purchases
***
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://syticks.gitbook.io/merpi-by-syticks/api-reference/general-endpoints-get-all-businesses-transaction-requery-etc/transaction-query-endpoint.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.