Payments API Webhooks

Applies to: Payments API | Orders API

Learn about the Square webhook notifications supported by the Payments API.

Link to section


The Payments API supports webhook events that notify you when a payment is created or updated. For example, when a payment is completed (paid), a payment.updated event is generated. These notifications are sent on payment events for your seller, regardless of which Square product or Square API application the seller used for the payment activity. For more information about using webhooks, see Square Webhooks.

Link to section

Webhook events

The Payments API uses these webhook events:

payment.createdPAYMENTS_READA Payment was created.
payment.updatedPAYMENTS_READA Payment field was updated. For example, the payment.status or card_details.status field is updated when a payment is authorized, canceled, or completed.

Did you know?

On the Webhook logs page in the Developer Dashboard, you can see webhook events posted to your application in real time. Use API Explorer to create a payment and then complete it. You see a payment.created event, followed by a payment.updated event. Before you try it, be sure you have a webhook subscription set up for all payment and refund events.

On the following Webhook logs page, a developer used API Explorer in Sandbox mode to create an Order and a new unpaid Payment object. They then paid the order, which updated the Order and Payment.

An image of the Developer Dashboard webhook logger showing order and payment events.

Link to section

payment.created webhook event

The payment.created event notification is sent:

  • On either of these Square API requests: the Payments API (CreatePayment endpoint) and the V2 Transactions API (Charge endpoint).

  • When a payment is taken by a seller through the Point of Sale application, Square Terminal, a Square invoice, or other Square products.


    For Point of Sale payments, the webhook notification doesn't include information added as a Note. However, a note added in a CreatePayment call is returned in the webhook notification.

Link to section

payment.updated webhook event

The payment.updated event is generated when any field in a Payment is updated, such as when it's completed (paid). You get one webhook notification for the change event, which encompasses all field updates in the event.

The following are examples of when you receive a payment.updated webhook event:

  • When you create a delayed capture payment by authorizing a payment but not processing it. When you're ready to process the payment, call CompletePayment or CancelPayment. The payment.status is then updated. If an authorized payment isn't completed or canceled within the time limit, Square voids the payment, which also results in a payment.updated event.
  • When a payment is associated with a Square Invoice and the buyer has paid the invoice.
  • When a payment is part of an Order and you call PayOrder, the Payment.status is changed to COMPLETED.
  • When you update a payment.
  • When Square adds additional information to a payment, such as when payment processing fees are calculated and added to the payment.
Link to section

Webhook event behavior for ACH payments

The Payments API processes ACH payments asynchronously. As a result, it triggers a payment.updated webhook with the status of COMPLETED or FAILED. Creating an ACH payment results in a payments.created webhook with the status of PENDING and when the payment completes or fails.