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:
| 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. |
| Event | Permission | Description |
|---|---|---|
| refund.created | PAYMENTS_READ | A Refund was created. |
| refund.updated | PAYMENTS_READ | A 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.
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 does not include information added as a
Note. However, anoteadded in aCreatePaymentcall 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.statusis then updated. If an authorized payment is not 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.
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 therefund.updatedevent after the refund isCOMPLETEDorFAILED.payment.updatedevent notification. ThePaymentobject 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.