Webhook Notifications

Acquired.com dispatches webhook events to your server to notify you of status changes for Pay by Bank payments and VRP mandates in real time.

This page covers the webhook events specific to Pay by Bank. For general information on webhook structure, validation, retry behaviour, and configuration, refer to the Webhook Notifications guide.

Webhook events summary

Pay by Bank uses two webhook types across both one-off payments and the two stages of a VRP integration.

VRP payments in Stage 2 use the same status_update webhook as one-off payments. The payload includes a mandate_id field to allow you to associate each payment with its mandate.

One-off payment webhooks

status_update

A status_update webhook is sent whenever the status of a one-off Pay by Bank payment changes. This is the primary event to listen for when confirming whether a payment was successful.

For a full list of possible status values, refer to Pay by Bank Statuses.

Webhook parameters

Example payload

{
  "webhook_type": "status_update",
  "webhook_id": "bc25b699-ffb1-40d5-b508-f6a28aeb18eb",
  "timestamp": 1690897080,
  "webhook_body": {
    "transaction_id": "1d0483a7-6f84-4784-9fba-3c7553847be0",
    "order_id": "6234ae00-1352-4bd7-852a-f328df1b7096",
    "status": "executed"
  }
}

VRP mandate webhooks (Stage 1)

The following webhooks are dispatched during Stage 1 of a VRP integration — the one-time mandate setup flow. Your integration must handle all of these events, particularly mandate_cancelled, to prevent attempting payments against an inactive mandate.

Note: mandate_active, mandate_cancelled, and mandate_expired webhooks are also used for Direct Debit mandates. To distinguish Pay by Bank mandate events from Direct Debit, check the scheme field in the detail object - Pay by Bank mandate webhooks will carry "scheme": "variable_recurring_payment".

Webhook parameters

mandate_active

Sent when a customer has successfully authorised the mandate via their banking app. Once received, payments can be initiated against the mandate within the agreed constraints.

{
  "webhook_type": "mandate_active",
  "webhook_id": "019c9161-fa2f-7116-96b8-9760a066ad63",
  "timestamp": 1771965643,
  "webhook_body": {
    "mandate_id": "01HZ6XKQR4NJTV8S2BWMCEGP7Y",
    "customer_id": "019c9160-0f51-7397-af52-607141f8cea2",
    "order_id": "148cf3a0-c0b0-4d6a-b605-e434625157ec",
    "status": "activated"
  },
  "detail": {
    "scheme": "variable_recurring_payment"
  }
}

mandate_failed

Sent when a customer's authorisation attempt was unsuccessful or the mandate could not be created. You should consider contacting the customer to suggest they retry or make an alternative payment arrangement.

{
  "webhook_type": "mandate_failed",
  "webhook_id": "298467ac-1f5e-4fad-bc5d-5874bd841df3",
  "timestamp": 1771965643,
  "webhook_body": {
    "mandate_id": "01HZ6XMP5GQWJY3F7DCRATBK9N",
    "customer_id": "019c9160-0f51-7397-af52-607141f8cea2",
    "order_id": "148cf3a0-c0b0-4d6a-b605-e434625157ec",
    "status": "failed"
  },
  "detail": {
    "scheme": "variable_recurring_payment"
  }
}

mandate_cancelled

Sent when an activated mandate is cancelled. This can only occur after the mandate has been successfully authorised, and can be triggered by the customer revoking consent directly from their banking app, or by the merchant cancelling the mandate via the API.

Upon receiving this webhook, you should suspend any scheduled payment collection against the mandate. You should also consider:

• Consider deactivating the customer's access to any service dependent on the mandate.
• Contacting the customer to inform them and, where appropriate, prompting them to set up a new mandate.

{
  "webhook_type": "mandate_cancelled",
  "webhook_id": "a12f3c88-2d1e-4b77-9f3a-0e5d2c8ab19f",
  "timestamp": 1771965643,
  "webhook_body": {
    "mandate_id": "01HZ6XMP5GQWJY3F7DCRATBK9N",
    "customer_id": "019c9160-0f51-7397-af52-607141f8cea2",
    "order_id": "148cf3a0-c0b0-4d6a-b605-e434625157ec",
    "status": "cancelled"
  },
  "detail": {
    "scheme": "variable_recurring_payment"
  }
}

mandate_expired

Sent when a mandate's validity period ends — i.e. the end_date constraint defined at mandate creation has passed. No further payments can be collected against the mandate.

{
  "webhook_type": "mandate_expired",
  "webhook_id": "f93b4d11-8c2a-4e55-b17f-3d6e1a7bc04e",
  "timestamp": 1771965643,
  "webhook_body": {
    "mandate_id": "01HZ6XMP5GQWJY3F7DCRATBK9N",
    "customer_id": "019c9160-0f51-7397-af52-607141f8cea2",
    "order_id": "148cf3a0-c0b0-4d6a-b605-e434625157ec",
    "status": "expired"
  },
  "detail": {
    "scheme": "variable_recurring_payment"
  }
}

VRP payment webhooks (Stage 2)

status_update

Once a mandate is active, each individual payment collected against it triggers a status_update webhook — the same webhook type used for one-off Pay by Bank payments. The payload includes a mandate_id field to allow you to associate the payment with its mandate.

For a full list of possible status values, refer to Pay by Bank Statuses.

Example payload

{
  "webhook_type": "status_update",
  "webhook_id": "d91c3e47-5b2a-4f88-a03d-7e4f2b9cd15a",
  "timestamp": 1690897080,
  "webhook_body": {
    "transaction_id": "3f2a1b09-8e7d-4c56-b29a-1d0483a76f84",
    "order_id": "9a3c7d55-2f1e-4b88-a17c-6e5d0f2bc94a",
    "mandate_id": "01HZ6XKQR4NJTV8S2BWMCEGP7Y",
    "status": "executed"
  }
}

This page covers the webhook events specific to Pay by Bank. For general information on webhook structure, validation, retry behaviour, and configuration, refer to the Webhook Notifications guide.

Note: While webhooks provide real-time notifications, they can occasionally be missed due to network issues or deployment events. It is advisable to complement webhook handling with polling via the relevant GET endpoint to ensure reliable status retrieval.