Skip to main content

Webhooks

When a payment has been processed we can send you a webhook notification confirming the outcome of the payment so you can take action within your own systems, for example, fulfilling orders, notifying your customers or integrating with third-parties.

Setting the webhook URL​

The payment-related webhook URL is defined when initiating a payment, by setting the urls.webhook field:

{
  "amount_minor": 1000,
  "currency": "EUR",
  "reference": "ORD-123456",
  "description": "Your Haircutz appointment at Emma Stone Hair Salon",
  "payment_method": {...},
  "integration": {...},
  "routing": {...},
  "urls": {
    "redirect": "https://haircutz.co/checkout/complete?order_id=ORD-123456",
    "webhook": "https://webhooks.haircutz.co/getpaid"
  }
}

For more details on the Initiate Payment API call, see Accept Payments.

Webhook Events​

tip

For a comprehensive reference on the schema of the payment webhooks, please see our API Reference.

We currently send webhooks for the following events:

Payment Succeeded​

The payment_succeeded event occurs when a payment has been successfully processed and approved by the relevant scheme/issuer. By default it is triggered when a payment transitions to a captured state. For manual captures (not yet supported), it is triggered when the payment transitions to authorized.

Example Webhook​

{
  "id": "evt_4r8t310nhp2mferdc1waa07s5d",
  "type": "payment_succeeded",
  "occurred_at": "2019-08-24T14:15:22Z",
  "data": {
    "id": "pay_473cr1y0ghbyc3m1yfbwvn3nxx",
    "status": "captured",
    "reference": "ORD-123456"
  }
}

Payment Failed​

The payment_failed event occurs when a payment is not approved. You can inspect the data.status field of the webhook payload to determine the cause of failure. The most common reasons include failed authentication (3D-Secure) and declines.

note

We do not send this webhook for payments that cannot be processed due to invalid data being supplied. These scenarios are handled by returning error details in the appropriate API responses (see Getting Started for more details).

Example Webhook​

{
  "id": "evt_4y7rv0p7zqv0f9arfsyr50864t",
  "type": "payment_failed",
  "occurred_at": "2019-08-24T14:15:22Z",
  "data": {
    "id": "pay_473cr1y0ghbyc3m1yfbwvn3nxx",
    "status": "declined",
    "reference": "ORD-123456"
  }
}

Handling Webhooks​

All webhooks are submitted to the provided URL via a HTTP POST request. The content type of the request body is application/json.

To confirm that you have successfully handled the webhook, return any successful 2xx HTTP status code. Any other status code will be treated as a failure and the webhook will be retried.

Webhooks will be retried a maximum of 10 times.

Webhook Verification (coming soon)​

In order to verify incoming webhooks and ensure they have been generated by getpaid, the webhook request will include a GetPaid-Signature header that you can use to validate the authenticity of the provided data.