Payment Operation Failure

Every operation you trigger on a payment deserves a clear answer. These webhooks deliver one instantly - so you can act before a missed capture or failed refund becomes a problem you discover too late.

Primer notifies you with a failure webhook whenever a payment operation attempt does not succeed and the payment status has not changed as a result. The following event types are supported:

• PAYMENT.CAPTURE.FAILED - a capture attempt did not succeed
• PAYMENT.REFUND.FAILED - a refund attempt did not succeed
• PAYMENT.CANCELLATION.FAILED - a cancellation attempt did not succeed
• PAYMENT.AUTHORIZATION_ADJUSTMENT.FAILED - an authorization adjustment attempt did not succeed

These events are operational signals, not status changes. Receiving a PAYMENT.CAPTURE.FAILED event, for example, means the capture attempt was unsuccessful - it does not mean the payment has failed or that the authorization has been lost.

When does a failure webhook fire? Common scenarios include:

• Amount mismatch - you attempt to capture £100, but the remaining authorised amount is only £80
• PSP-side error - the processor returns a technical error or the request times out before a response is received

Particularly useful with Primer Workflows. If you trigger captures or refunds automatically through a Workflow, failure webhooks are the signal you need to keep your own systems in sync. Because the action happened upstream, your backend won’t know it failed unless Primer tells you - these events close that gap.

A webhook is emitted for every individual failed attempt. If the same operation fails multiple times, you will receive a separate event each time.

The webhook payload is intentionally minimal. To retrieve the full context - including the error reason, timeline, and processor response - call GET /payments/{id}?expand=transactions.events after receiving the event.

What to do when you receive a failure event

The right action depends on the failure type: for amount mismatches, you may want to retry the capture with a corrected amount; for PSP errors or timeouts, a retry after a short delay is often appropriate. In all cases, make sure your internal systems reflect the outcome - update your order management, notify your operations team if needed, and avoid leaving the payment in an ambiguous state on your end.