Payment webhooks

Overview

Stay on top of your reservation payments by subscribing to Guesty's payment events. When a payment-related action happens on a reservation, you'll receive a webhook so you can quickly access the latest booking details.

What Notifications Can I Receive?

The table below lists all available payment events you can subscribe to. Test the events that fit your workflow, then update your subscriptions to match your business needs. For step-by-step instructions, see how to subscribe to webhooks here.

Event	Description
`payments.authenticationRequired`	Sent when a payment provider requires the guest to authenticate themselves to process a payment.
`payments.authorizationHoldFailed`	Sent when an authorization hold fails.
`payments.disputes`	Sent when you receive a chargeback from your payment processor.
`payments.failed`	Sent when a payment processing attempt for a reservation fails.
`payments.method.received`	Sent when a valid payment method is added to the guest and reservation.
`payments.overcharged`	Sent when a guest is overcharged on a reservation.
`payments.overcharge.expected`	Sent when a guest is due to be overcharged on a reservation.
`payments.invalidPaymentMethod`	Sent when an invalid payment method is added to the guest and reservation
`payments.overdue`	Sent when a guest payment is overdue.
`payments.received`	Sent when a payment is successfully processed.
`payments.refunded`	Sent when a guest payment has been refunded.

Shapes and examples

Use these examples as a starting point. Because webhook payloads can vary, always test in your own environment to confirm the data matches your needs.

payments.authenticationRequired

Webhook Payload

Body Parameter	Data Type	Description
`payment`	object
`accountId`	string	The ID of your Guesty account.
`reservationId`	string	The Guesty ID of the affected reservation.
`paymentId`	string	The Guesty ID of the payment.
`ctx`	object	It contains the request ID you can share with Guesty support for additional troubleshooting.
`event`	string	`payments.authenticationRequired`

Payload Example

{
  "payment":{
    "accountId":"5213a2d206112710005d96ff",
    "reservationId":"646c9abf137b4c0032fb87fa",
    "paymentId":"668571319b9276d5f7caa5b9",
    "ctx":{
      "requestId":"c9ed719425bf59c4"
    }
  },
  "event":"payments.authenticationRequired"
}

payments.authorizationHoldFailed

Webhook Payload

Body Parameter	Data Type	Description
`payment`	object
`accountId`	string	The ID of your Guesty account.
`reservationId`	string	The Guesty ID of the affected reservation.
`paymentId`	string	The Guesty ID of the payment.
`ctx`	object	It contains the request ID you can share with Guesty support for additional troubleshooting.
`event`	string	`payments.authorizationHoldFailed`

Payload Example

{
  "payment":{
    "accountId":"5213a2d206112710005d96ff",
    "reservationId":"667ad00db904239ef0b9cbdd",
    "paymentId":"668520e93cac721c718e845f",
    "ctx":{
      "requestId":"9a55a5e6a0d18a7f"
    }
  },
  "event":"payments.authorizationHoldFailed"
}

payments.disputes

Webhook Payload

Body Parameter	Data Type	Description
`payment`	object
`accountId`	string	The ID of your Guesty account.
`reservationId`	string	The Guesty ID of the affected reservation.
`paymentId`	string	The Guesty ID of the payment.
`amount`	number	The amount that was refunded to the cardholder.
`chargebackAt`	string	The ISO 8601 date string with the date and time of the chargeback.
`source`	string	This will return `AUTO` for clear-cut cases such as a double charge, and `MANUAL` for situations where the dispute is reviewed before initiating a chargeback. Your payment processor is the channel for handling such disputes.
`reason`	string	Reason for the chargeback.
`type`	string	The dispute type. E.g., "CHARGEBACK"
`caseId`	string	The payment processor case ID for follow-up with their support.
`createdAt`	string	The ISO 8601 date when the case was opened.
`ctx`	object	It contains the request ID you can share with Guesty support for additional troubleshooting.
`event`	string	`payments.disputes`

Payload Example

{
  "payment":{
    "accountId":"5213a2d206112710005d96ff",
    "reservationId":"667ad00db904239ef0b9cbdd",
    "paymentId":"668520e93cac721c718e845f",
    "amount":234.72,
    "chargebackAt":"2024-02-07T23:59:59.000Z",
    "source":"AUTO",
    "reason":"FHS Partners L booking",
    "type":"CHARGEBACK",
    "caseId":"2024031111111",
    "createdAt":"2024-02-11T12:00:28.143Z",
    "ctx":{
      "requestId":"9a55a5e6a0d18a7f"
    }
  },
  "event":"payments.disputes"

payments.failed

Webhook Payload

Body Parameter	Data Type	Description
`payment`	object	Contains the unique object IDs relevant to the failed payment.
`accountId`	string	The ID of your Guesty account.
`reservationId`	string	The Guesty ID of the affected reservation.
`paymentId`	string	The Guesty ID of the failed payment attempt.
`failureReason`	string	The reason the payment failed.
`ctx`	object	It contains the request ID you can share with Guesty support for additional troubleshooting.
`event`	string	`payments.failed`

Payload Example

{
  "payment":{
    "accountId":"5213a2d206112710005d96ff",
    "reservationId":"667ad00db904239ef0b9cbdd",
    "paymentId":"668520e93cac721c718e845f",
    "failureReason":"Insufficient Funds",
    "ctx":{
      "requestId":"fea76539"
    }
  },
  "event":"payments.failed"
}

payments.method.received

Webhook Payload

Body Parameter	Data Type	Description
`payment`	object
`accountId`	string	The ID of your Guesty account.
`reservationId`	string	The Guesty ID of the affected reservation.
`paymentId`	string	The Guesty ID of the payment.
`ctx`	object	It contains the request ID you can share with Guesty support for additional troubleshooting.
`event`	string	`payments.method.received`

Payload Example

{
  "payment":{
    "accountId":"5213a2d206112710005d96ff",
    "reservationId":"667ad00db904239ef0b9cbdd",
    "paymentId":"668520e93cac721c718e845f",
    "ctx":{
      "requestId":"9a55a5e6a0d18a7f"
    }
  },
  "event":"payments.method.received"
}

payments.overcharged

Webhook Payload

Body Parameter	Data Type	Description
`payment`	object
`accountId`	string	The ID of your Guesty account.
`reservationId`	string	The Guesty ID of the affected reservation.
`paymentId`	string	The Guesty ID of the payment.
`balanceDue`	number	The overcharged amount (will always be negative).
`ctx`	object	It contains the request ID you can share with Guesty support for additional troubleshooting.
`event`	string	`payments.overcharged`

Payload Example

{
  "payment":{
    "accountId":"5213a2d206112710005d96ff",
    "reservationId":"667ad00db904239ef0b9cbdd",
    "paymentId":"668520e93cac721c718e845f",
    "balanceDue":-123,
    "ctx":{
      "requestId":"9a55a5e6a0d18a7f"
    }
  },
  "event":"payments.overcharged"
}

payments.overcharge.expected

Webhook Payload

Body Parameter	Data Type	Description
`payment`	object
`accountId`	string	The ID of your Guesty account.
`listingId`	string	The Guesty listing ID.
`reservationId`	string	The Guesty ID of the affected reservation.
`creditCardPaymentsStatus`	string	This is one of three enums; see the section below this table for more details.
`totalPaid`	number	The total amount paid/collected for the reservation.
`currency`	string	The payment currency.
`hostPayout`	number	The guest invoice total.
`totalExpectedCharge`	number	The amount the guest is expected to be charged for the reservation.
`totalExpectedOvercharge`	number	The amount above the guest invoice total that is expected to be collected.
`isOverchargeExpected`	boolean	This will be `true`.
`ctx`	object	It contains the request ID you can share with Guesty support for additional troubleshooting.
`event`	string	`payments.overcharge.expected`

Credit Card Payments Status Enums

Enum	Description
`NO_CREDIT_CARD_PAYMENTS`	The reservation has only “recorded” payments (like DEBIT, CREDIT, etc.), but no credit card payments are defined or expected to be processed by Guesty.
`HAS_PENDING_PAYMENT`	The reservation has at least one PENDING credit card payment that Guesty is expected to process in the future.
`HAS_SUCCEEDED_PAYMENT`	The reservation has at least one SUCCEEDED credit card payment processed by Guesty.

Payload Example

{
  "payment":{
    "accountId":"5213a2d206112710005d96ff",
    "listingId":"5f05dd00b5d317002b005134",
    "reservationId":"667ad00db904239ef0b9cbdd",
    "creditCardPaymentsStatus":"HAS_SUCCEEDED_PAYMENT",
    "totalPaid":262,
    "currency":"USD",
    "hostPayout":140,
    "totalExpectedCharge":262,
    "totalExpectedOvercharge":122,
    "isOverchargeExpected":true,
    "ctx":{
      "requestId":"9a55a5e6a0d18a7f"
    }
  },
  "event":"payments.overcharge.expected"
}

payments.invalidPaymentMethod

Event to Subscribe

payments.invalidPaymentMethod

Webhook Payload

Body Parameter	Data Type	Description
`payment`	object
`accountId`	string	The ID of your Guesty account.
`reservationId`	string	The Guesty ID of the affected reservation.
`paymentId`	string	The Guesty ID of the payment.
`invalidCreditCard`	object
`at`	string	The ISO 8601 date and time of the error.
`brand`	string	The credit card type. E.g., "Visa."
`last4`	string	The last four digits of the credit card number.
`error`	string	The error type.
`processorError`	object	This contains the specific error code and message.
`ctx`	object	This contains the request ID you can share with Guesty support for additional troubleshooting.
`event`	string	`payments.invalidPaymentMethod`

Payload Example

{
  "payment":{
    "accountId":"5213a2d206112710005d96ff",
    "reservationId":"667ad00db904239ef0b9cbdd",
    "paymentId":"668520e93cac721c718e845f",
    "invalidCreditCard":{
      "at":"2024-07-04T13:38:18.397Z",
      "brand":"visa",
      "last4":"5103",
      "error":"GENERAL",
      "processorError":{
        "code":"incorrect_zip",
        "message":"Your card could not be authorized using the postal code provided. Please update the postal code, or contact your card issuer for further details."
      }
    },
    "ctx":{
      "requestId":"9a55a5e6a0d18a7f"
    }
  },
  "event":"payments.invalidPaymentMethod"
}

payments.overdue

Webhook Payload

Body Parameter	Data Type	Description
`payment`	object
`accountId`	string	The ID of your Guesty account.
`reservationId`	string	The Guesty ID of the affected reservation.
`paymentId`	string	The Guesty ID of the payment.
`amount`	number	The amount paid.
`currency`	string	The currency of the payment.
`isAuthorizationHold`	string	Only returned if it's `true`.
`isSecurityDeposit`	string	Only returned if it's `true`.
`paymentMethodId`	string	The Guesty ID of the payment method used.
`ctx`	object	It contains the request ID you can share with Guesty support for additional troubleshooting.
`event`	string	`payments.overdue`

Payload Example

{
  "payment":{
    "accountId":"5213a2d206112710005d96ff",
    "reservationId":"667ad00db904239ef0b9cbdd",
    "paymentId":"668520e93cac721c718e845f",
    "amount":190,
    "currency":"USD",
    "isAuthorizationHold":true,
    "isSecurityDeposit":true,
    "paymentMethodId":"667ad2ade5969747f67ce303",
    "ctx":{
      "requestId":"9a55a5e6a0d18a7f"
    }
  },
  "event":"payments.overdue"
}

payments.received

Webhook Payload

Body Parameter	Data Type	Description
`payment`	Object
`accountId`	The ID of your Guesty account.
`reservationId`	The Guesty ID of the affected reservation.
`paymentId`	The Guesty ID of the payment.
`amount`	The amount paid.
`currency`	The currency of the payment.
`confirmationCode`	The payment processing confirmation code.
`paidAt`	The ISO 8601 date and time of the payment.
`paymentMethodId`	The Guesty ID of the payment method used.
`last4`	The last four digits of the credit card.
`brand`	The type of credit card. E.g., `"Visa"`
`name`	The name of the cardholder.
`address`	The cardholder's billing address.
`ctx`	It contains the request ID you can share with Guesty support for additional troubleshooting.
`event`	`payments.received`

Payload Example

{
  "payment":{
    "accountId":"5213a2d206112710005d96ff",
    "reservationId":"667ad00db904239ef0b9cbdd",
    "paymentId":"668520e93cac721c718e845f",
    "amount":190,
    "currency":"USD",
    "confirmationCode":"20407-fd791ba4-3923-11ef-84df-005056a5723f",
    "paidAt":"2024-07-03T10:07:02.468Z",
    "paymentMethodId":"667ad2ade5969747f67ce303",
    "last4":"4242",
    "brand":"Visa",
    "name":"Bill Bull",
    "address":"My street 12, My City, 123456 NY, US",
    "ctx":{
      "requestId":"fea76539"
    }
  },
  "event":"payments.received"
}

payments.refunded

Webhook Payload

Body Parameter	Data Type	Description
`payment`	object
`accountId`	string	The ID of your Guesty account.
`reservationId`	string	The Guesty ID of the affected reservation.
`paymentId`	string	The Guesty ID of the payment.
`amount`	number	The amount paid.
`refundedAmount`	number	The portion of the payment that was refunded.
`totalRefunded`	number	The total amount that was refunded.
`confirmationCode`	string	The payment processor payment confirmation code.
`refundConfirmationCode`	string	The payment processor refund confirmation code.
`paidAt`	string	The ISO 8601 date and time of the original payment.
`refundedAt`	string	The ISO 8601 date and time of the refund.
`paymentMethodId`	string	The Guesty ID of the payment method used.
`last4`	string	The last four digits of the credit card.
`brand`	string	The type of credit card. E.g., `"Visa"`
`name`	string	The name of the cardholder.
`address`	string	The cardholder's billing address.
`ctx`	object	It contains the request ID you can share with Guesty support for additional troubleshooting.
`event`	string	`payments.refunded`

Payload Example

{
  "payment":{
    "accountId":"5213a2d206112710005d96ff",
    "listingId":"5f05dd00b5d317002b005134",
    "reservationId":"667ad00db904239ef0b9cbdd",
    "paymentId":"667bd6394d0f0d8ea7bb1f7c",
    "amount":17,
    "refundAmount":1,
    "totalRefunded":2,
    "confirmationCode":"20407-dc61b933-3399-11ef-87d5-005056a5723f",
    "refundConfirmationCode":"20407-1d7a8c4e-3923-11ef-84df-005056a5723f",
    "paidAt":"2024-06-26T08:55:40.623Z",
    "refundedAt":"2024-07-03T10:00:46.759Z",
    "paymentMethodId":"667ad2ade5969747f67ce303",
    "last4":"4242",
    "brand":"Visa",
    "name":"Bill Bull",
    "address":"My street 12, My City, 123456 NY, US",
    "ctx":{
      "requestId":"9a55a5e6a0d18a7f"
    }
  },
  "event":"payments.refunded"
}

Retrieving payment information

📘
Best Practice
After receiving a webhook, we advise you to invoke the API to fetch the most recent reservation data and compare this fresh data with your locally stored records to determine the full extent of the changes when necessary.

To check the latest payment details and confirm if payment automations are active, use the legacy reservations endpoint with the request below.

GET /reservations/{id}?fields=money.payments%20money.isTouchedPayments

If money.isTouchedPayments returns false, your automation is intact. If it returns true, cancel and reschedule upcoming payments with the recalculated amounts as needed.

Guest folio financials can be retrieved from the following endpoints:

Troubleshooting

Scheduled payment for has the incorrect amount

Manual intervention in reservation payments disables payment automations, leaving scheduled payments unchanged. Validate the automation state by retrieving the money.isTouchedPayments parameter with your reservation using GET /reservations/{id}?fields?money.isTouchedPayments. If it returns false, your automation is intact; otherwise, true means you need to cancel and reschedule upcoming payments with the updated amounts.