Webhooks: Payments

Overview

Guesty's Open API allows you to send guest payment-related webhooks to your application's notification URL(s).

What Notifications Can I Receive?

Guesty sends payment webhooks for the following events:

When a payment has been received.
A failed payment.
A refunded payment.
An overdue payment.
An overcharged guest.
An expected overcharge.
When a payment requires authentication.
A failed authorization hold.
When a payment method has been received/added.
An invalid payment method.
An invalid Booking.com payment method and an invalid second Booking.com payment method.
When authentication of a payment fails.
A disputed payment.

Continue reading to learn more about each event and how to subscribe.

Received Payment

This webhook is sent when a payment is successfully processed. Learn how to subscribe to this webhook here.

Event to Subscribe

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"
}

Failed Payment

This notification is sent when a reservation payment processing attempt fails. Learn how to subscribe to this webhook here.

Event to Subscribe

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"
}

Refunded Payment

This webhook is sent when a guest payment has been refunded. Learn how to subscribe to this here.

Event to Subscribe

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"
}

Overdue Payment

This webhook is sent when a guest payment is overdue. Learn how to subscribe to this webhook here.

Event to Subscribe

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, // Only returned if it’s true
    "isSecurityDeposit":true, // Only returned if it’s true
    "paymentMethodId":"667ad2ade5969747f67ce303",
    "ctx":{
      "requestId":"9a55a5e6a0d18a7f"
    }
  },
  "event":"payments.overdue"
}

Overcharged Payment

This webhook is sent when a guest is overcharged on a reservation. Learn how to subscribe to this webhook here.

Event to Subscribe

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 a negative number).
`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"
}

Overcharge is Expected

This webhook is sent when a guest is due to be overcharged on a reservation. Learn how to subscribe to this webhook here.

Event to Subscribe

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"
}

Authentication Required

This webhook is sent when a payment requires authentication by the guest. Learn how to subscribe to this webhook here.

Event to Subscribe

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"
}

Failed Authorization Hold

This webhook is sent when an authorization hold fails. Learn how to subscribe to this webhook here.

Event to Subscribe

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"
}

Payment Method Received

This webhook is sent when a valid payment method is added to the guest and reservation. Learn how to subscribe to this webhook here.

Event to Subscribe

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"
}

Invalid Payment Method

This webhook is sent when an invalid payment method is added to the guest and reservation. Learn how to subscribe to this webhook here.

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"
}

Invalid Booking.com Credit Card

This webhook is sent when Guesty cannot process the payment on Booking.com reservations with the supplied Booking.com credit card. Learn how to subscribe to this webhook here.

Event to Subscribe

payments.invalidBcomCard

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.invalidBcomCard`

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.invalidBcomCard"
}

Invalid Second Booking.com Credit Card

This webhook is sent when Guesty cannot process the payment on Booking.com reservations with a second supplied Booking.com credit card. Learn how to subscribe to this webhook here.

Event to Subscribe

payments.invalidSecondBcomCard

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.invalidSecondBcomCard`

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.invalidSecondBcomCard"
}

Failed Authentication

This webhook is sent when the authentication step for the credit card payment fails. Learn how to subscribe to this webhook here.

Event to Subscribe

payments.authenticationFailed

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.authenticationFailed`

Payload Example

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

Disputed Payment

This webhook is sent when you receive a chargeback from your payment processor. Learn how to subscribe to this webhook here.

Event to Subscribe

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"
}