---
title: "Create payment"
method: POST
path: "/payments"
tags: ["Reservation Payments"]
---

# Create payment

`POST /payments`

## Request

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

Creates a payment on a reservation.

Replaces the deprecated [Record or process a reservation payment](https://open-api-docs.guesty.com/reference/reservationsv2paymentcreate) for processor payments.

## Request body

- object
  - `reservationId` string, required: Guesty reservation id
  - `paymentMethodId` string, required: Guesty payment method id. Recorded payment methods must use the recorded-payment endpoints.
  - `amount` number, required: Amount to charge, in the reservation currency. Must be at least 1. Cannot exceed the reservation balance unless `isSecurityDeposit` is true.
  - `shouldBePaidAt` string, date-time: When to charge. Must not be in the past. Omit to charge immediately. Format: `YYYY-MM-DDTHH:mm:ss.SSSZ`.
  - `isAuthorizationHold` boolean: When true, creates an authorization hold instead of a charge. Cannot be true together with `isSecurityDeposit`. Capture a non-deposit hold with `POST /payments/{paymentId}/capture`.
  - `isSecurityDeposit` boolean: When true, creates a security deposit authorization hold. Requires `releaseAuthorizationHold`, released at `releaseAuthorizationHold.shouldTriggerAt`. Cannot be true together with `isAuthorizationHold`.
  - `releaseAuthorizationHold` object: Release schedule for a security deposit. Required when isSecurityDeposit is true.
    - `shouldTriggerAt` string, date-time, required: When to release the security deposit authorization hold. Must not be in the past. Format: `YYYY-MM-DDTHH:mm:ss.SSSZ`.
  - `note` string: Note stored on the payment

## Response `201`

The created 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.
- `402`: The payment cannot proceed.
- `422`: The request cannot be processed.
- `500`: Internal server error. Try again later.
- `503`: The reservation is not ready for payments yet. This happens right after the reservation is created, before its payment data is available. No payment was created. Retry the same request later.

## Changes

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

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