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.created||A Payment was created.|
|payment.updated||A Payment field was updated. For example, the |
|refund.created||A Refund was created.|
|refund.updated||A Refund was updated. Typically, the |
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
The payment.created event notification is sent:
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
noteadded in a
CreatePaymentcall 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
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.statusis then updated. If an authorized payment is not completed or canceled within the time limit, Square voids the payment, which also results in a
When a payment is associated with a Square Invoice and the buyer has paid the invoice.
When a payment is part of an
Orderand you call PayOrder, the
Payment.statusis changed to
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
The same applies for ACH payment refunds. A
RefundPayment request publishes
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.updatedevent after the refund is
payment.updatedevent notification. The
Paymentobject in the notification includes the refund ID. The refund.updated event is sent any time a refund state changes.