GUguesty
Reservation Payments

Record chargeback

Changed on

Records a chargeback on a succeeded processor payment and returns that payment. Pending payments on the same reservation that used this payment method are detached. Recorded payments are not supported.

post/payments/{paymentId}/chargeback

Request

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

Path parameters

paymentIdstring required
Example:64ad4e764c9a5d00328e79fe

Guesty payment id

Request body

amountnumber required

Chargeback amount, in the reservation currency. Must be at least 1 and cannot exceed the payment balance.

chargebackAtstring date-time

When the chargeback occurred. Must be in the past. Format: YYYY-MM-DDTHH:mm:ss.SSSZ.

reasonstring

Reason stored on the chargeback

notestring

Note stored on the chargeback

caseIdstring

Processor dispute case id. This is not a Guesty id.

Example request

{
  "amount": 50,
  "chargebackAt": "2026-09-01T12:00:00.000Z",
  "reason": "Fraudulent transaction",
  "note": "Guest disputed stay dates",
  "caseId": "CB-123456"
}

Response

The payment with the recorded chargeback

_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