Payments API and Refunds API Webhooks
The Payments API and Refunds API support a set of webhook events. A webhook is a subscription that notifies you when a Square event occurs. For more information about using webhooks, see Webhooks Overview.
The Payments API and Refunds API use the following webhook events:
| Event | Description |
|---|---|
| payment.created | A Payment was created. |
| payment.updated | A Payment was updated. Typically the payment.status or card_details.status field is updated when a payment is canceled, authorized, or completed. |
| Event | Description |
|---|---|
| refund.created | A Refund was created. |
| refund.updated | A Refund was updated. Typically the refund.status field changes when a refund is completed. |
Note the following about these webhook events.
payment.created event. The payment.created event notification is sent when:
Square processes these endpoint requests: the Payments API (CreatePayment endpoint) and the v2 Transactions API (Charge endpoint).
All payments (card, cash, and external) are taken by a seller through other means, such as the Point of Sale application or invoices.
Note
For Point of Sale payments, the published notification does not include information added as a
Note. However, anoteadded in aCreatePaymentcall is returned in the webhook notification.
payment.updated event. The payment.updated event is generated when the state of a payment changes. For example:
In a delayed capture scenario, the payment is only authorized. Later, when you call CompletePayment (or CancelPayment), the payment state changes. In addition, if an authorized payment is not completed (or canceled) within the time limit, the payment is automatically voided (Square cancels the payment) and you get the
payment.updatedevent notification.If you call UpdatePayment, you get the
payment.updatedevent notification.Additional information is added to a payment. For example, Square calculates and add payment processing fees to the payment.
payment.created webhook event
The payment.created event notification is sent when:
Square processes these endpoint requests: the Payments API (CreatePayment endpoint) and the v2 Transactions API (Charge endpoint).
All payments (card, cash, and external) are taken by a seller through other means, such as the Point of Sale application or invoices.
Note
For Point of Sale payments, the published notification does not include information added as a
Note. However, anoteadded in aCreatePaymentcall is returned in the webhook notification.
payment.updated webhook event
The payment.updated event is generated when the state of a payment changes. For example:
In a delayed capture scenario, the payment is only authorized. Later, when you call CompletePayment (or CancelPayment), the payment state changes. In addition, if an authorized payment is not completed (or canceled) within the time limit, the payment is automatically voided (Square cancels the payment) and you get the
payment.updatedevent notification.If you call UpdatePayment, you get the
payment.updatedevent notification.Additional information is added to a payment. For example, Square calculates and add payment processing fees to the payment.
ACH payment-related webhook event behavior
Because the API processes ACH payments asynchronously (creating an ACH payment results in a payments.created webhook with status 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.
Refund-related webhook event behavior
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 completed or failed.payment.updatedevent notification. ThePaymentobject in the notification includes the refund ID.
The refund.updated event is sent any time a refund state changes.