Direct Debit mandates

This guide will walk you through working with Direct Debit mandates on your accounts: listing them, fetching one, cancelling one, and handling the cases where an expected mandate never appears. For the concepts behind mandates and the parties involved, see Direct Debits on Griffin accounts.

Mandates are created for you: when an organisation your customer has authorised lodges a Direct Debit Instruction through the scheme, Griffin checks it and the mandate appears on the account. There is no API for creating a mandate.

List the mandates on an account

To see the mandates on a bank account, list them using the account's mandates URL.

curl "https://api.griffin.com/v0/bank/accounts/ba.bihSK9VMQRCVhrFm5Rv7MA/mandates" \
  -H "Authorization: GriffinAPIKey $GRIFFIN_API_KEY"

The response contains a page of mandate resources. Each mandate identifies the originator (the creditor), the account being debited (the debtor), how often and how much the originator may collect, and the mandate's status.

{
  "mandates": [
    {
      "collection-amount": {
        "amount-type": "variable"
      },
      "collection-frequency": "monthly",
      "created-at": "2026-06-03T09:12:44.201Z",
      "creditor": {
        "account-holder": "Acme Energy Ltd",
        "account-number": "55779911",
        "account-number-code": "bban",
        "bank-id": "200000",
        "bank-id-code": "gbdsc",
        "creditor-type": "uk-domestic"
      },
      "debtor": {
        "account-url": "/v0/bank/accounts/ba.bihSK9VMQRCVhrFm5Rv7MA"
      },
      "last-used-at": "2026-07-01T09:14:22.310Z",
      "mandate-payments-url": "/v0/mandates/mn.Qy3vTfNhTvGYlG0mBv9WkQ/payments",
      "mandate-scheme-information": {
        "payment-scheme": "bacs"
      },
      "mandate-url": "/v0/mandates/mn.Qy3vTfNhTvGYlG0mBv9WkQ",
      "reference": "ACME-ENERGY-004417",
      "status": "active"
    },
    {
      "collection-amount": {
        "amount-type": "fixed",
        "amount": {
          "currency": "GBP",
          "value": "29.99"
        }
      },
      "collection-frequency": "monthly",
      "created-at": "2026-05-14T10:03:12.907Z",
      "creditor": {
        "account-holder": "FitLife Gyms Ltd",
        "account-number": "31926819",
        "account-number-code": "bban",
        "bank-id": "200000",
        "bank-id-code": "gbdsc",
        "creditor-type": "uk-domestic"
      },
      "debtor": {
        "account-url": "/v0/bank/accounts/ba.bihSK9VMQRCVhrFm5Rv7MA"
      },
      "mandate-payments-url": "/v0/mandates/mn.X0dKzp8cSByLM3o-cnbcpg/payments",
      "mandate-scheme-information": {
        "payment-scheme": "bacs",
        "unique-scheme-id": "FL0038291"
      },
      "mandate-url": "/v0/mandates/mn.X0dKzp8cSByLM3o-cnbcpg",
      "reference": "FITLIFE-8842",
      "status": "active"
    }
  ],
  "links": {
    "prev": null,
    "next": null
  }
}

A few fields worth noting:

The originator's name is the creditor's account-holder. This is usually the name your customer will recognise: show it when presenting mandates to end-users, alongside the reference the originator uses to identify the agreement.
collection-amount describes what the originator may collect: a fixed amount, or a variable amount with an optional max-amount.
mandate-payments-url lists the payments collected against the mandate.

Fetch a mandate

To fetch a single mandate, use its mandate-url.

curl "https://api.griffin.com/v0/mandates/mn.Qy3vTfNhTvGYlG0mBv9WkQ" \
  -H "Authorization: GriffinAPIKey $GRIFFIN_API_KEY"

The response is a single mandate resource with the same shape as the entries in the list above.

Track changes to mandates

Mandate changes are tracked by polling. New mandates appear in the account's mandates list as originators lodge them, and status changes (for example, an originator cancelling a mandate) are reflected in the status field. Poll the list endpoint for the accounts you care about and compare against your last known state.

info

Webhook events for mandate changes are coming soon. In the meantime, poll the mandates list to detect new, cancelled, or expired mandates.

Cancel a mandate

warning

Cancelling the mandate stops the collections, but it does not cancel whatever contract your customer has with the originator. Advise end-users to also tell the originator they are cancelling, so the originator can arrange another way to pay; otherwise the originator may treat the missed collections as arrears.

For customers using the Griffin app with an operational account, viewing and cancelling mandates is available in the app directly. For accounts you provide to your customers through the API, mandate viewing and cancellation is API-only: you provide the cancellation experience in your own product using the endpoints below.

Your customer can cancel a mandate at any time. To cancel it over the API, update the mandate's status:

curl "https://api.griffin.com/v0/mandates/mn.Qy3vTfNhTvGYlG0mBv9WkQ" \
  -X 'PATCH' \
  -H 'Content-Type: application/json' \
  -H "Authorization: GriffinAPIKey $GRIFFIN_API_KEY" \
  --data '
{
  "status": "cancelled",
  "cancellation-reason": "cancelled-by-debtor"
}'

A successful response has status 200. Fetch the mandate again to see the updated resource: its status is cancelled and the cancellation-reason records who cancelled it.

{
  "cancellation-reason": "cancelled-by-debtor",
  "reference": "ACME-ENERGY-004417",
  "status": "cancelled"
}

When a mandate is cancelled, Griffin notifies the originator automatically: there is nothing further for you to do at the scheme level. Any later collection the originator attempts against the cancelled mandate is returned to them unpaid.

caution

Cancellation is permanent and a cancelled mandate cannot be reinstated. To resume the Direct Debit the originator must set up a new instruction. This will appear as a new mandate.

Account closure

When an account is closed, all of its active mandates are cancelled automatically and the originators are notified. You do not need to cancel mandates before closing an account.

When a new Direct Debit doesn't appear

The most common mandate question from end-users is: "I set up a Direct Debit days ago, so why hasn't it shown up?"

When an originator lodges a new Direct Debit Instruction, Griffin checks it before creating the mandate. The instruction is rejected and returned to the originator automatically, through the scheme, if:

the sort code or account number doesn't match an account held with Griffin;
the account is closed, or is blocked from accepting Direct Debits;
there is already a Direct Debit on the account from the same originator with the same reference.

A rejected instruction leaves no trace on the account. The mandate is never created, so there is nothing for you to see in the mandates list and nothing to poll for; from your side, it is indistinguishable from the originator never having lodged the instruction. The originator is told about the rejection and why; the payer typically finds out when the originator contacts them, or when the expected collection never happens.

If an end-user reports a missing Direct Debit:

Check the account's mandates list to confirm the mandate really isn't there.
Confirm the account can accept Direct Debits: it is open and not blocked.
Advise the end-user to re-check the account details they gave the originator (sort code, account number, and account name) and ask the originator to set up the instruction again.

List the mandates on an account​

Fetch a mandate​

Track changes to mandates​

Cancel a mandate​

Account closure​

When a new Direct Debit doesn't appear​