Guides

Mandate events are webhook notifications that GoCardless sends whenever a mandate's status changes. This guide covers the key events you should handle and what to do when they occur.

A webhook is a request that GoCardless sends to your server to alert you of an event. Adding support for webhooks allows you to receive real-time notifications from GoCardless when things happen in your account, so you can take automated actions in response.

Mandate lifecycle

A mandate moves through the following statuses:

Status	Meaning
`pending.submission`	Mandate created, not yet sent to the banks
`submitted`	Sent to the banks for processing
`active`	Confirmed by the banks, ready to collect against
`failed`	Could not be set up (e.g. invalid bank details)
`cancelled`	Cancelled by the customer, merchant, or GoCardless
`expired`	Expired due to inactivity (scheme-dependent)
`consumed`	Used for a one-off payment and can no longer be reused

Events to handle

Mandates can be cancelled by the customer via their bank, by you via the API, or by GoCardless. When this happens, you'll receive:

 {
    "events": {
      "id": "EV123",
      "resource_type": "mandates",
      "action": "cancelled",
      "links": {
        "mandate": "MD123"
      },
      "details": {
        "origin": "bank",
        "cause": "bank_account_closed",
        "description": "The bank account for this mandate has been closed."
      }
    }
  }

The details.cause field tells you why the mandate was cancelled. Common values:

Cause	Meaning
`bank_account_closed`	Customer's bank account has been closed
`invalid_bank_details`	Bank details were incorrect
`direct_debit_not_enabled`	Account doesn't support Direct Debit
`customer_approval_denied`	Customer cancelled at their bank
`mandate_cancelled`	Cancelled via the GoCardless dashboard or API

When you receive this event you should:

Update the mandate status in your database
Prevent further payment attempts against this mandate
Notify the customer that their Direct Debit has been cancelled and prompt them to set up a new one if needed

Cancelling a mandate yourself:

If you need to cancel a mandate programmatically:

<?php
require 'vendor/autoload.php';

$client = new \GoCardlessPro\Client([
    'access_token' => $currentUser->gocardlessAccessToken,
    'environment' => \GoCardlessPro\Environment::SANDBOX
]);

$mandate = $client->mandates()->cancel($mandate_id);
print("Status: " . $mandate->status);

Only cancel a mandate if the customer has explicitly requested it.

If the mandate cannot be set up, for example, because the bank account doesn't support Direct Debit or has been closed, you'll receive:

{
    "events": {
      "id": "EV124",
      "resource_type": "mandates",
      "action": "failed",
      "links": {
        "mandate": "MD123"
      },
      "details": {
        "origin": "bank",
        "cause": "bank_account_closed",
        "description": "The bank account for this mandate has been closed."
      }
    }
  }

When you receive this event, you should:

Update the mandate status in your database
Notify the customer and prompt them to set up a new mandate with a different bank account

Use details.cause to tailor your error message, the same cause values apply as for cancellations above

When a merchant enables the Merchant name on bank statement add-on, GoCardless moves their mandates from the GoCardless shared scheme identifier to the merchant's own identifier. For BACS mandates, this results in a new mandate ID.

You'll receive:

{
    "events": {
      "resource_type": "mandates",
      "action": "replaced",
      "links": {
        "mandate": "MD123",
        "new_mandate": "MD456"
      }
    }
  }

This requires immediate action. If you attempt to collect a payment against the old mandate ID, you'll receive an invalid_state error with the reason mandate_replaced. Update the mandate ID in your database to links.new_mandate as soon as you receive this event.

Full list of mandate events

For all possible mandate events and their details see the API reference - mandate event types.

Related Guides

Responding to Billing Requests events

Testing webhooks with the CLI

Supporting mandates set up outside of your product

Need help?

Guides

Responding to Mandate Events

What are mandate events?

Storing mandates

Mandate lifecycle

Events to handle

Mandate cancelled

Mandate failed

Mandate expired

Mandate replaced

Full list of mandate events

Related Guides