---
title: "Charge payment"
method: POST
path: "/payments/{paymentId}/pay"
tags: ["Reservation Payments"]
---

# Charge payment

`POST /payments/{paymentId}/pay`

## Request

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

Charges a payment now. The payment must be `PENDING` (including one scheduled for later) or `FAILED`. Recorded payments are not charged here. A provider decline returns 200 with status `FAILED`. When the provider requires guest authentication, the call returns 200 with status `PENDING_AUTH`. `authenticationRequiredData.authenticationUrl` is the URL the guest must open when the provider returns one.

## Path parameters

- `paymentId` string, required

## Response `200`

The charged payment

- object
  - `_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

## Other responses

- `400`: The request is invalid.
- `401`: Missing or invalid authentication.
- `404`: A resource was not found.
- `422`: The request cannot be processed.
- `500`: Internal server error. Try again later.

## Changes

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

[Operation history](https://skmtc.dev/guesty/apis/guesty-open-api/changes/payments/:paymentId/pay/post.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)