How to retrieve transaction data from your GuestyPay payment processor.
Overview
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.
Core Concepts
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.
API Usage and Other Policies
Prerequisite
Payment Provider Configuration: Your account must have at least one (active) Guesty Pay provider configured.
Endpoint Path
Method
Path
GET
/payment-transactions/report
Query Parameters
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
Request Limitations
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.
Common Error Scenarios
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
API output
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
