Inquiry Regarding Missing payment.updated Webhook After terminal.checkout.updated

Questions
1

Dear Square Support Team,

I am integrating Square’s Terminal API for processing payments and have encountered a discrepancy in webhook behavior when using await_next_action: true. I would appreciate your clarification on the following questions:

Background:

Previously, I used the Create Terminal Checkout API for initiating payments. In this setup, I received both:

  1. A terminal.checkout.updated webhook, which contained the checkout details.

  2. A subsequent payment.updated webhook, which contained the final payment details.

Recently, I have modified the flow to first use the Create Terminal Action API (for tip selection) before calling Create Terminal Checkout.

In this new setup, I enabled await_next_action: true in the Terminal Action, and now I no longer receive a payment.updated webhook.

Questions:

  1. Is it expected behavior that the payment.updated webhook is no longer triggered when using await_next_action: true?

• If so, could you point me to any official documentation that explains this behavior?

  1. If this is normal, how should I determine the final payment status?

• I noticed that terminal.checkout.updated webhook contains a payment_id, but the payment status is APPROVED, not COMPLETED.

• Should I call the Complete Payment API to finalize the transaction?

  1. How does accept_partial_authorization: true affect this behavior?

• Since I have enabled accept_partial_authorization: true and autocomplete: false, what happens if the customer has insufficient funds?

• Will the terminal.checkout.updated webhook indicate this, or do I need to poll for partial payments manually?

Example Data:

Before Using Create Terminal Action API

• :white_check_mark: Received terminal.checkout.updated

• :white_check_mark: Received payment.updated

After Using Create Terminal Action API with await_next_action: true

• :white_check_mark: Received terminal.action.updated

• :white_check_mark: Received terminal.checkout.updated

• :cross_mark: Did not receive payment.updated

Would appreciate any insights or documentation you can provide. Thank you for your time!

Best regards,

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

Use Webhooks to Integrate with a Payroll System
Square Developer
Update Payment and Tip Amounts

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

  1. Yes, it is expected behavior that the payment.updated webhook is not triggered when using await_next_action: true. This is because the payment is not yet completed when the Terminal Action is created. The payment.updated webhook is only triggered when a payment’s status changes, such as when it is completed or canceled.

  2. To determine the final payment status, you should call the RetrievePayment API endpoint using the payment_id from the terminal.checkout.updated webhook. This will return the current status of the payment. If the status is APPROVED, you can then call the CompletePayment API to finalize the transaction.

  3. The accept_partial_authorization: true setting allows a payment to be approved for less than the requested amount if the customer’s card has insufficient funds. If this happens, the terminal.checkout.updated webhook will still be triggered, but the payment’s status will be PARTIALLY_APPROVED. You would then need to decide whether to accept the partial payment (by calling CompletePayment) or to cancel it. If you have autocomplete: false set, you will need to manually complete or cancel the payment.

Please note that this information is not explicitly stated in the Square documentation, but is based on the general behavior of the Square APIs and webhooks.

This answer was reviewed by @Bryan-Square.

1 Like