Does the Terminal Checkout Webhook Include Tip Information?

Questions
1

Hello everyone,

I’m currently integrating Square Terminal Checkout for my application and I have a question regarding the webhook notifications, specifically the “terminal.checkout.updated” event.

According to the documentation and sample webhook payloads I’ve seen, the webhook contains details such as “amount_money”, “payment_ids”, “status”, etc., but I have not found any explicit mention of tip information (e.g., a “tip_money” field).

My main questions are:

  1. Does the “terminal.checkout.updated” webhook include any tip information directly?

  2. If tip information is present, which key should I look for in the webhook payload?

  3. If tip information is not present, how can I retrieve it?

Any clarification, official documentation references, or implementation examples would be greatly appreciated.

Thank you in advance for your help!

Best regards,
Enes Bulut

2

:waving_hand: I’m Square Dev AI, here to help answer your question!
Based on the information you’ve provided, the following documentation will help answer your question:

Additional Documentation

Refunds API Webhooks
Update Payment and Tip Amounts
Use Customer Webhooks

If this documentation helped you find a solution, please check the box indicating that this reply solves the problem.
Otherwise one of our Developer Advocates will provide additional assistance shortly.

3

The “terminal.checkout.updated” webhook event does not directly include tip information. However, you can retrieve tip information by using the “payment_ids” field in the webhook payload.

The “payment_ids” field contains an array of payment IDs associated with the checkout. You can use these payment IDs to call the RetrievePayment endpoint of the Payments API. The response from RetrievePayment includes a “tip_money” field in the “Payment” object, which represents the tip amount for the payment.

So, to retrieve tip information for a terminal checkout, you would need to:

  1. Extract the payment IDs from the “terminal.checkout.updated” webhook event.
  2. For each payment ID, call the RetrievePayment endpoint of the Payments API.
  3. In the response from RetrievePayment, look for the “tip_money” field in the “Payment” object. This field represents the tip amount for the payment.

This answer was reviewed by @Bryan-Square.