The Payment Transactions API lets developers access transaction data from the GuestyPay payment processor. With this API, developers can retrieve transaction details and use filtering options like date ranges, reservation confirmation codes, and payment processor sub-accounts.
| Term | Definition |
|---|
| Account | A merchant account within the Guesty Payments platform. |
| Processing Account / Merchant account ID | A logical subdivision of a payment provider account for organizing transactions; format: accountId.subAccountId. |
| Reservation | The booking associated with a transaction, identified by the reservationConfirmationCode. |
| Transaction ID | Unique identifier generated by the payment processor for each transaction. |
- Payment Provider Configuration: Your account must have at least one (active) Guesty Pay provider configured.
| Method | Path |
|---|
| GET | /payment-transactions/report |
| Parameter | Description |
|---|
startDate | Start date of the transaction |
endDate | End date |
reservationConfirmationCode | The reservation confirmation code |
subAccountId | The sub-account ID of the payment provider |
skip | Items to skip for pagination |
take | The number of items on each page |
- Date Range: Maximum consecutive date range for transaction queries is 31 days
- Pagination: Maximum results per request is 100 items
- ReservationConfirmationCode: Simultaneous filtering by
reservationConfirmationCode and dates is not possible.
- Required filters: It is necessary to include the date range (
startDate & endDate) or reservationConfirmationCode filters.
| Scenario | HTTP Status | Error Message |
|---|
| No payment provider | 400 | Payment provider not found |
| Date range exceeds 31 days | 400 | Date range cannot exceed 1 month |
| End date before start date | 400 | End date cannot be before start date |
| Invalid sub-account format | 400 | Invalid sub account ID (format must be accountId.subAccountId) |
| Incompatible filter combination | 400 | Cannot filter by date range and confirmation code at the same time or Cannot use confirmation code with date range or sub account ID |
| Payment processor misconfiguration | 500 | Payment provider has no account or sub account |
| Field | Example | Description |
|---|
transactionId | "1387001358100142998" | Unique identifier for this transaction from the payment processor |
reservationConfirmationCode | "HA-123abc" | Guesty reservation confirmation code |
amount | 0.00 | Transaction amount in decimal format |
currency | "GBP" | Currency code |
last4 | 1234 | Last four digits of the payment card |
bin | 123456 | Bank Identification Number (first six digits of the payment card) |
subAccount | "1387.2 - My Company - GBP" | Payment processor account identifier - merchant account name |
merchantDate | "2025-09-15T02:20:45" | Transaction processing date and time by merchant |
systemDate | "2025-09-15T02:20:48" | Transaction processing date and time |
settlementDate | "2025-09-15T23:59:59" | Transaction settlement date and time |
paymentMethod | "Visa" | Payment method type/brand |
processorARN | "ProcessorARN" | Acquirer Reference Number for the transaction |
dynamicDescriptor | "DynamicDescriptor" | Business dynamic descriptor value |
status | "Processed" | Transaction status |
transactionType | "Verify" | Transaction type |
authorizationOrErrorCode | "275640" | Authorization or error code from the processor |
