GUguesty
Recorded Payments

Update recorded payment

Changed on

Updates a recorded payment. Sending a recorded payment method on a failed processor payment marks it as recorded: status becomes SUCCEEDED and paidAt is set to the current date and time.

patch/payments/{paymentId}/record

Request

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

Path parameters

paymentIdstring required
Example:64ad4e764c9a5d00328e79fe

Guesty payment id

Request body

shouldBePaidAtstring date-time

When to record the payment. On create, omit this field or send a past date to record it now (SUCCEEDED, paidAt set to that time, or the current date and time when omitted). A future date schedules it as PENDING. On update, omit this field to leave the existing time unchanged. Format: YYYY-MM-DDTHH:mm:ss.SSSZ.

amountnumber

Recorded payment amount, in the reservation currency. Must be at least 1.

confirmationCodestring

Booking confirmation code of the reservation (for example GY-123456). This is not a processor payment id.

notestring

Note stored on the recorded payment

Example request

{
  "shouldBePaidAt": "2026-10-01T12:00:00.000Z",
  "amount": 150,
  "paymentMethod": {
    "method": "RECORDED_CASH"
  },
  "confirmationCode": "GY-123456",
  "note": "Paid in cash at check-in"
}

Response

The updated recorded payment

_idstring required

Guesty payment id

reservationIdstring required

Guesty reservation id

accountIdstring required

Guesty account id

paymentMethodIdstring 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.

amountnumber required

Payment amount, in the reservation currency

currencystring required

ISO 4217 currency code of the reservation

isAuthorizationHoldboolean

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.

isSecurityDepositboolean

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.

confirmationCodestring

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).

shouldBePaidAtstring 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.

paidAtstring date-time

When the payment succeeded. Format: YYYY-MM-DDTHH:mm:ss.SSSZ.

cancelledAtstring date-time

When the payment was cancelled. Format: YYYY-MM-DDTHH:mm:ss.SSSZ.

createdAtstring date-time

When the payment record was created. Format: YYYY-MM-DDTHH:mm:ss.SSSZ.

updatedAtstring date-time

When the payment record was last updated. Format: YYYY-MM-DDTHH:mm:ss.SSSZ.

notestring

Note stored on the payment

receiptIdnumber

Receipt number generated after a successful charge

createdBystring

User who created the payment

errorstring

Guesty payment error key when the payment failed. Processor details are in processorError.

isInstantChargeboolean

When true, the payment was charged immediately on creation

payoutIdstring

Channel payout ID for succeeded Airbnb payments

Example response

{
  "_id": "64da25d683ad1500284bd0ef",
  "reservationId": "6213b03e7f0ba50032296f4a",
  "accountId": "5f293ca69fa6bd01659b645e",
  "paymentMethodId": "5f92cbf10cf217478ba93561",
  "paymentMethodStatus": "ACTIVE",
  "status": "SUCCEEDED",
  "amount": 150,
  "currency": "USD",
  "type": "REFUNDABLE_DEPOSIT",
  "confirmationCode": "pi_3UITWaE5puWDpHmg1fPNH1ZL",
  "shouldBePaidAt": "2026-10-01T12:00:00.000Z",
  "paidAt": "2026-10-01T12:00:05.000Z",
  "cancelledAt": "2026-10-01T12:00:05.000Z",
  "createdAt": "2026-10-01T12:00:00.000Z",
  "updatedAt": "2026-10-01T12:00:05.000Z",
  "note": "Charge remaining balance",
  "receiptId": 146928316,
  "createdBy": "host@example.com",
  "error": "CARD_DECLINED",
  "processorError": {
    "code": "card_declined",
    "message": "Your card was declined."
  },
  "authenticationRequiredData": {
    "lastAuthMsgSentDate": "2026-10-01T12:00:00.000Z",
    "authenticationUrl": "https://hooks.stripe.com/redirect/authenticate/..."
  },
  "captureAuthorizationHold": {
    "amount": 150,
    "status": "PENDING",
    "shouldTriggerAt": "2026-10-15T12:00:00.000Z",
    "cancelledAt": "2026-10-10T12:00:00.000Z",
    "note": "Guest checked out early"
  },
  "releaseAuthorizationHold": {
    "amount": 150,
    "status": "PENDING",
    "shouldTriggerAt": "2026-10-15T12:00:00.000Z",
    "cancelledAt": "2026-10-10T12:00:00.000Z",
    "note": "Guest checked out early"
  },
  "authorizationHoldCaptures": [
    {
      "_id": "64da25d683ad1500284bd0ef",
      "amount": 100,
      "status": "SUCCEEDED",
      "createdAt": "2026-10-01T12:00:00.000Z",
      "note": "Partial capture for remaining balance"
    }
  ],
  "refunds": [
    {
      "_id": "64da267d83ad1500284bd109",
      "amount": 50,
      "status": "SUCCEEDED",
      "createdAt": "2026-10-01T12:00:00.000Z",
      "refundedAt": "2026-10-01T12:00:05.000Z",
      "note": "Guest cancelled",
      "paymentMethodId": "5f92cbf10cf217478ba93561",
      "processorError": {
        "code": "card_declined",
        "message": "Your card was declined."
      }
    }
  ],
  "chargebacksData": {
    "chargebackPaymentMethodId": "5f92cbf10cf217478ba93561",
    "chargebacks": [
      {
        "_id": "64da267d83ad1500284bd109",
        "amount": 150,
        "type": "CHARGEBACK",
        "chargebackAt": "2026-10-01T12:00:00.000Z",
        "createdAt": "2026-10-01T12:00:00.000Z",
        "source": "MANUAL",
        "reason": "Fraudulent charge",
        "reasonCode": "10.4",
        "reasonDescription": "Fraud – Card-Absent Environment",
        "note": "Disputed by guest",
        "caseId": "dp_1N...",
        "transactionId": "ch_3N..."
      }
    ]
  },
  "attempts": [
    {
      "_id": "64da267d83ad1500284bd109",
      "status": "FAILED",
      "createdAt": "2026-10-01T12:00:00.000Z",
      "error": "CARD_DECLINED",
      "processorError": {
        "code": "card_declined",
        "message": "Your card was declined."
      }
    }
  ],
  "fees": [
    {
      "_id": "64da267d83ad1500284bd109",
      "amount": 2.5
    }
  ],
  "isInstantCharge": true,
  "payoutId": "PO-123456"
}

Changes