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 Overview.
The Payments API uses these webhook events:
| Event | Permission | Description |
|---|---|---|
| payment.created | PAYMENTS_READ | A Payment was created. |
| payment.updated | PAYMENTS_READ | A 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.
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.
Note
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.
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.statusis then updated. If an authorized payment isn't completed or canceled within the time limit, Square voids the payment, which also results in apayment.updatedevent.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, thePayment.statusis changed toCOMPLETED.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.
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.