Payouts Reconciliation API Reference [Beta]

Introduction

The Payouts Reconciliation API retrieves payout data from Guesty Pay providers. It supports filtering by date range, payout ID, reservation confirmation code, and payment processor sub-accounts.

Core Concepts

Term	Definition
Sub-account ID	Payment processor sub-account in the format, `accountId.subAccountId` (e.g. `1234.1`).
Payout ID	Unique identifier of a payout generated by the payment processor.
Reservation	Booking associated with payout transactions, identified by, `reservationConfirmationCode`.

API Usage and Policies

The endpoint requires:

Authentication: Valid credentials for the Open API or Partners API
Payment Provider Configuration: Your account should have (active) Guesty Pay providers with payouts processed.

Endpoint Paths

Method	Path
GET	`payment-transactions/reports/payouts-reconciliation`

Query Parameters

Parameter	Description
`startDate`	Start date (ISO 8601), required when not using `reservationConfirmationCode`.
`endDate`	End date (ISO 8601), required when not using `reservationConfirmationCode`.
`subAccountId`	Optional sub-account filter, format: `accountId.subAccountId` (numeric `number.number`).
`payoutId`	Optional payout ID to narrow results within the date range.
`reservationConfirmationCode`	Reservation confirmation code; cannot be combined with any other filter.
`skip`	Items to skip for pagination (default `0`).
`take`	Page size (default `25`, max `100`).

Request Limitations

Date range requirement:
- Either (startDate & endDate) or reservationConfirmationCode must be provided
- When using reservationConfirmationCode, you must not send startDate, endDate, subAccountId, or payoutId
Date range length: Maximum consecutive date range is 31 days
Date ordering: endDate must be on or after startDate
Pagination: take must be between 1 and 100
Sub-account format: subAccountId must be number.number (e.g. 1234.1)

Common Error Scenarios

Scenario	HTTP Status	Error Message
Missing both the date range and the reservation code	`400`	`Date range is required`
Invalid date format	`400`	`Invalid date format`
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 `subAccountId` format	`400`	`subAccountId must be in the format number.number`
`reservationConfirmationCode` combined with any other filter	`400`	`reservationConfirmationCode cannot be combined with other filters`
Unauthenticated request	`401`	`You need to be authenticated to access this endpoint`

Response Payload

An array of transactions per payout. The following table describes a transaction object.

Field	Example	Description
`transactionId`	"1387001358100142998"	Unique identifier for this transaction from the payment processor
`reservationConfirmationCode`	"HA-123abc"	Guesty reservation confirmation code
`amount`	1000.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