Learn about the Square V2 webhook notifications supported by the Payments API and Refunds API.
Payments API and Refunds API

Payments API and Refunds API Webhooks

The Payments and Refunds APIs support 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 Overview.

The Payments API and Refunds API use 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.
refund.createdPAYMENTS_READA Refund was created.
refund.updatedPAYMENTS_READA Refund was updated. Typically, the refund.status field changes when a refund is 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

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 does not include information added as a Note. However, a note added in a CreatePayment call is returned in the webhook notification.

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

These are examples of when you receive payment.updated:

  • When you create a delayed capture payment by authorizing a payment but not processing it. When you are ready to process the payment, call CompletePayment or CancelPayment. The payment.status is then updated. If an authorized payment is not 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.

Because the API processes ACH payments asynchronously (creating an ACH payment results in a payments.created webhook with the status of PENDING and when the payment completes or fails), it triggers a payment.updated webhook with the status of COMPLETED or FAILED.

The same applies for ACH payment refunds. A RefundPayment request publishes refund.created and refund.updated events.

When you refund a payment (using the RefundPayment endpoint), you get the following event notifications:

  • refund.created initially indicates that the task is PENDING. Later, you get the refund.updated event after the refund is COMPLETED or FAILED.

  • payment.updated event notification. The Payment object in the notification includes the refund ID. The refund.updated event is sent any time a refund state changes.

If you need more assistance, contact Developer Support or ask for help in the Developer Forums.