GUguesty
Reservation Payments

Refund payment

Changed on

Refunds a succeeded processor payment in full or in part. Returns the payment with the refund included in refunds. The refund can still be PROCESSING until the provider settles it.

Replaces the deprecated Refund a payment.

post/payments/{paymentId}/refund

Request

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

Path parameters

paymentIdstring required
Example:64ad4e764c9a5d00328e79fe

Guesty payment id

Request body

amountnumber

Amount to refund, in the reservation currency. Must be at least 1. Omit to refund the original payment amount. After a partial refund, send the remaining amount explicitly.

notestring

Note stored on the refund

Example request

{
  "amount": 50,
  "note": "Guest cancelled remaining nights"
}

Response

The refunded 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