---
title: "List reservation payments"
method: GET
path: "/payments"
tags: ["Reservation Payments"]
---

# List reservation payments

`GET /payments`

## Request

- Base URL: `https://open-api.guesty.com/v1`
- URL: `https://open-api.guesty.com/v1/payments`
- Auth: API key in header `authorization`

Returns every payment on the given reservation, including authorization holds and their capture payments, plus reservation payment summary fields.

## Query parameters

- `reservationId` string, required

## Response `200`

The reservation payments and payment summary

- object
  - `payments` object[], required: Payments on the reservation
    - `_id` string, required: Guesty payment id
    - `reservationId` string, required: Guesty reservation id
    - `accountId` string, required: Guesty account id
    - `paymentMethodId` string, required: Guesty payment method id used for this payment
    - `paymentMethodStatus` 'ACTIVE' | 'INVALID' | 'PENDING_ACTIVATION' | 'INCOMPLETE' | 'CANCELLED' | 'FAILED' | 'DELETED': Status of the payment method at the time of the payment
    - `status` 'PENDING' | 'PENDING_AUTH' | 'FAILED' | 'SUCCEEDED' | 'PROCESSING' | 'CANCELLED' | 'AUTHORIZATION_HOLD_SUCCEEDED' | 'SECURITY_DEPOSIT_SUCCEEDED' | 'ERROR', required: Payment status. `PENDING` is not yet charged, including a future schedule. `PENDING_AUTH` is waiting for the guest to complete authentication. `PROCESSING` is accepted by the processor and not settled yet. `SUCCEEDED` is charged. `FAILED` is a processor decline. `CANCELLED` was cancelled before it was charged. `AUTHORIZATION_HOLD_SUCCEEDED` is an authorization hold. `SECURITY_DEPOSIT_SUCCEEDED` is a security deposit hold. `ERROR` cannot be charged.
    - `amount` number, required: Payment amount, in the reservation currency
    - `currency` string, required: ISO 4217 currency code of the reservation
    - `isAuthorizationHold` boolean: When true, this payment is an authorization hold rather than a charge. Cannot be true together with `isSecurityDeposit`. A non-deposit hold is captured with `POST /payments/{paymentId}/capture`.
    - `isSecurityDeposit` boolean: When true, this payment is a security deposit authorization hold. It requires `releaseAuthorizationHold`, released at `releaseAuthorizationHold.shouldTriggerAt`. Cannot be true together with `isAuthorizationHold`.
    - `type` 'REFUNDABLE_DEPOSIT': Set when this payment is a refundable deposit. Omitted otherwise.
    - `confirmationCode` string: On a processor payment, the processor payment-intent id (for example `pi_3UITWaE5puWDpHmg1fPNH1ZL`). On a recorded payment, the booking confirmation code sent when the payment was recorded (for example `GY-123456`).
    - `shouldBePaidAt` string, date-time: When the payment is scheduled. On a processor payment, a past value means it was charged immediately. On a recorded payment, a past value means it was recorded immediately (`SUCCEEDED`); a future value means `PENDING`. Format: `YYYY-MM-DDTHH:mm:ss.SSSZ`.
    - `paidAt` string, date-time: When the payment succeeded. Format: `YYYY-MM-DDTHH:mm:ss.SSSZ`.
    - `cancelledAt` string, date-time: When the payment was cancelled. Format: `YYYY-MM-DDTHH:mm:ss.SSSZ`.
    - `createdAt` string, date-time: When the payment record was created. Format: `YYYY-MM-DDTHH:mm:ss.SSSZ`.
    - `updatedAt` string, date-time: When the payment record was last updated. Format: `YYYY-MM-DDTHH:mm:ss.SSSZ`.
    - `note` string: Note stored on the payment
    - `receiptId` number: Receipt number generated after a successful charge
    - `createdBy` string: User who created the payment
    - `error` string: Guesty payment error key when the payment failed. Processor details are in `processorError`.
    - `processorError` object: Processor error details when the payment failed
      - `code` string, required: Processor error code
      - `message` string, required: Processor error message
    - `authenticationRequiredData` object: 3DS / authentication challenge data when guest authentication is required
      - `lastAuthMsgSentDate` string, date-time: When the last authentication message was sent. Format: `YYYY-MM-DDTHH:mm:ss.SSSZ`.
      - `authenticationUrl` string: URL the guest must open to complete payment authentication (e.g. 3DS)
    - `captureAuthorizationHold` object: Scheduled capture plan for an authorization hold. Created only by payments automation. A manual payment cannot have this plan.
      - `amount` number: Amount scheduled for capture, in the reservation currency. Release plans always release the full hold.
      - `status` 'PENDING' | 'PENDING_AUTH' | 'FAILED' | 'SUCCEEDED' | 'PROCESSING' | 'CANCELLED' | 'AUTHORIZATION_HOLD_SUCCEEDED' | 'SECURITY_DEPOSIT_SUCCEEDED' | 'ERROR', required: Status of the scheduled authorization-hold action
      - `shouldTriggerAt` string, date-time, required: When the scheduled capture or release should run. Format: `YYYY-MM-DDTHH:mm:ss.SSSZ`.
      - `cancelledAt` string, date-time: When the scheduled action was cancelled. Format: `YYYY-MM-DDTHH:mm:ss.SSSZ`.
      - `note` string: Note stored on the scheduled action
    - `releaseAuthorizationHold` object: Scheduled release plan for a security deposit authorization hold
      - `amount` number: Amount scheduled for capture, in the reservation currency. Release plans always release the full hold.
      - `status` 'PENDING' | 'PENDING_AUTH' | 'FAILED' | 'SUCCEEDED' | 'PROCESSING' | 'CANCELLED' | 'AUTHORIZATION_HOLD_SUCCEEDED' | 'SECURITY_DEPOSIT_SUCCEEDED' | 'ERROR', required: Status of the scheduled authorization-hold action
      - `shouldTriggerAt` string, date-time, required: When the scheduled capture or release should run. Format: `YYYY-MM-DDTHH:mm:ss.SSSZ`.
      - `cancelledAt` string, date-time: When the scheduled action was cancelled. Format: `YYYY-MM-DDTHH:mm:ss.SSSZ`.
      - `note` string: Note stored on the scheduled action
    - `authorizationHoldCaptures` object[]: Captures taken against an authorization hold
      - `_id` string: Guesty capture payment id
      - `amount` number, required: Captured amount, in the reservation currency
      - `status` 'PENDING' | 'PENDING_AUTH' | 'FAILED' | 'SUCCEEDED' | 'PROCESSING' | 'CANCELLED' | 'AUTHORIZATION_HOLD_SUCCEEDED' | 'SECURITY_DEPOSIT_SUCCEEDED' | 'ERROR', required: Capture status
      - `createdAt` string, date-time: When the capture was created. Format: `YYYY-MM-DDTHH:mm:ss.SSSZ`.
      - `note` string: Note stored on the capture
    - `refunds` object[]: Refunds applied to this payment
      - `_id` string: Guesty refund id
      - `amount` number, required: Refunded amount, in the reservation currency
      - `status` 'PENDING' | 'PENDING_AUTH' | 'FAILED' | 'SUCCEEDED' | 'PROCESSING' | 'CANCELLED' | 'AUTHORIZATION_HOLD_SUCCEEDED' | 'SECURITY_DEPOSIT_SUCCEEDED' | 'ERROR', required: Refund status
      - `createdAt` string, date-time: When the refund record was created. Format: `YYYY-MM-DDTHH:mm:ss.SSSZ`.
      - `refundedAt` string, date-time: When the refund completed. On a recorded refund this is the time sent as `refundedAt`, or the current date and time when that field was omitted. Format: `YYYY-MM-DDTHH:mm:ss.SSSZ`.
      - `note` string: Note stored on the refund
      - `paymentMethodId` string: Payment method used for the refund, when different from the original charge
      - `processorError` object: Processor error details when the refund failed
        - `code` string, required: Processor error code
        - `message` string, required: Processor error message
    - `chargebacksData` object: Chargeback data for this payment
      - `chargebackPaymentMethodId` string: Payment method attached for recovering chargeback funds, when one was set
      - `chargebacks` object[], required: Chargebacks recorded against this payment
        - `_id` string: Guesty chargeback record id
        - `amount` number, required: Chargeback amount, in the reservation currency
        - `type` 'CHARGEBACK' | 'REVERSAL_CHARGEBACK' | 'REPRESENTMENT' | 'ARBITRATION', required: Chargeback type recorded on this dispute. This operation records `CHARGEBACK`.
        - `chargebackAt` string, date-time: When the chargeback occurred. Format: `YYYY-MM-DDTHH:mm:ss.SSSZ`.
        - `createdAt` string, date-time: When the chargeback record was created. Format: `YYYY-MM-DDTHH:mm:ss.SSSZ`.
        - `source` string: Source that recorded the chargeback
        - `reason` string: Free-text reason provided when recording the chargeback
        - `reasonCode` string: Processor reason code
        - `reasonDescription` string: Processor reason description
        - `note` string: Note stored on the chargeback
        - `caseId` string: Processor dispute case id. This is not a Guesty id.
        - `transactionId` string: Processor transaction ID associated with the chargeback
    - `attempts` object[]: Charge attempts recorded for this payment
      - `_id` string: Guesty attempt id
      - `status` 'PENDING' | 'PENDING_AUTH' | 'FAILED' | 'SUCCEEDED' | 'PROCESSING' | 'CANCELLED' | 'AUTHORIZATION_HOLD_SUCCEEDED' | 'SECURITY_DEPOSIT_SUCCEEDED' | 'ERROR', required: Status of this charge attempt
      - `createdAt` string, date-time: When the attempt was created. Format: `YYYY-MM-DDTHH:mm:ss.SSSZ`.
      - `error` string: Guesty payment error key when the attempt failed. Processor details are in `processorError`.
      - `processorError` object: Processor error details when the attempt failed
        - `code` string, required: Processor error code
        - `message` string, required: Processor error message
    - `fees` object[]: Fees associated with this payment
      - `_id` string: Guesty fee id
      - `amount` number, required: Fee amount, in the reservation currency
    - `isInstantCharge` boolean: When true, the payment was charged immediately on creation
    - `payoutId` string: Channel payout ID for succeeded Airbnb payments
  - `balanceDue` number, required: Remaining balance due on the reservation
  - `paymentsDue` number, required: Sum of pending payments due on the reservation
  - `totalPaid` number, required: Total amount paid on the reservation
  - `totalRefunded` number, required: Total amount refunded on the reservation
  - `totalPaymentFees` number: Total payment fees on the reservation
  - `isFullyPaid` boolean, required: Whether the reservation is fully paid
  - `isTouchedPayments` boolean, required: Whether any payments have been created on the reservation
  - `invalidCreditCard` object: Details when the reservation has an invalid credit card
    - `at` object: When the card was marked invalid. Format: `YYYY-MM-DDTHH:mm:ss.SSSZ`.
    - `brand` string: Card brand
    - `last4` string: Last four digits of the card
    - `error` string: Guesty error key for the invalid card
    - `processorError` object: Processor error details
  - `currency` string, required: ISO 4217 currency code of the reservation
  - `hostPayout` number, required: Host payout amount for the reservation

## Other responses

- `400`: The request is invalid.
- `401`: Missing or invalid authentication.
- `404`: A resource was not found.

## Changes

- **2026-11-03** `3122b8618183`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/guesty/apis/guesty-open-api/changes/payments/get.md)

---

[API](https://skmtc.dev/guesty/apis/guesty-open-api.md) - [All operations](https://skmtc.dev/guesty/apis/guesty-open-api/llms.txt) - [OpenAPI document](https://skmtc.dev/guesty/apis/guesty-open-api/revisions/3122b8618183?raw)