Bacs Direct Debits

A Direct Debit Instruction (DDI) is an authorisation to collect future payments from a nominated account. A DDI can be submitted to ClearBank® by Service Users electronically via the Bacs Automated Direct Debit Instruction Service (AUDDIS) or sent as a paper instruction to your address to be entered via the ClearBank® API after you have validated it. A DDI can be set up against real and virtual accounts held with ClearBank®.

If you are transferring an existing sort code to ClearBank® that already has DDIs set up, you will need to use the API to inform us of these.

Create DDI for an account

post/v1/Accounts/{accountId}/Mandates

This endpoint is only required if you have received a validated Paper DDI and need to inform ClearBank of its existence. All other DDIs are set up through AUDDIS.

Requests creation of a Direct Debit Instruction

This endpoint uses a combination of the SUN and reference as a duplicate check and to ensure the request is idempotent.

Parameters

accountId string, path, Required
The unique identifier for the account. This can be retrieved from GET /v1/Accounts
Authorization string, header, Required
Your API Token, retrieved from the web portal
DigitalSignature string, header, Required
Signed hash of the body of the request. The hash is signed by your private key
X-Request-Id string, header, Required
A unique identifier for the request

Request Payload (application/json)

serviceUserNumber string, Required
The service user number.
Pattern
^\d{6}$
originatorName string
The originator name.
Minimum length
0
Maximum length
18
Pattern
^[A-Z0-9\.\&\/\-\ ]*$
reference string, Required
The Service User's reference.
Minimum length
1
Maximum length
18
Pattern
^[A-Z0-9\.\&\/\-\ ]*$
payerName string
The payer name.
Minimum length
0
Maximum length
18
Pattern
^[A-Z0-9\.\&\/\-\ ]*$
counterpartAccount object
Information about the counterpart in a given transaction
mandateType string
The specified Instruction type for the request. (You will only use “Origination” and “Migrated” if you are transferring a sort code from another Direct Participant to the ClearBank® domain. “Migrated” indicates that the DDI was initially received as a paper item but later re-lodged in AUDDIS format by the Service User)
Enum array
PaperMandate, Origination, Migrated

request

{
  "serviceUserNumber": "string",
  "originatorName": "string",
  "reference": "string",
  "payerName": "string",
  "counterpartAccount": {
    "identification": {
      "iban": "string",
      "other": {
        "identification": "string",
        "schemeName": {
          "code": "BBAN",
          "proprietary": "string"
        },
        "issuer": "string"
      }
    }
  },
  "mandateType": "PaperMandate"
}

Code copied

Response (application/json)

202 Success
400 Bad Request
403 Forbidden
404 Not Found
500 Server Error
503 Server Error

Success

{
  "halLinks": [
    {
      "name": "string",
      "href": "string",
      "templated": true
    }
  ]
}

Code copied

Bad Request

{
  "errors": {
    "property1": [
      "string"
    ],
    "property2": [
      "string"
    ]
  },
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string"
}

Code copied

Get all DDIs for an account

get/v2/Accounts/{accountId}/Mandates

Gets all of the Direct Debit Instructions associated with the account

Parameters

accountId string, path, Required
The unique identifier for the account. This can be retrieved from GET /V2/Accounts
pageNumber integer, query
The page number to control returned results into manageable sets. Default if not supplied: 1
pageSize integer, query
The page size to control returned results into manageable sets. Default if not supplied: 50
Authorization string, header, Required
Your API Token, retrieved from the web portal

Response (application/json)

200 Success
400 Bad Request
403 Forbidden
409 Conflict
500 Server Error
503 Server Error

Success

{
  "directDebitMandates": [
    {
      "mandateId": "string",
      "payerName": "string",
      "payerBban": "string",
      "payerAccountNumber": "string",
      "payerSortCode": "string",
      "reference": "string",
      "serviceUserNumber": "string",
      "originatorName": "string",
      "state": "Active"
    }
  ],
  "halLinks": [
    {
      "name": "string",
      "href": "string",
      "templated": true
    }
  ]
}

Code copied

Bad Request

{
  "errors": {
    "property1": [
      "string"
    ],
    "property2": [
      "string"
    ]
  },
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string"
}

Code copied

Amend a DDI for an account

patch/v1/Accounts/{accountId}/Mandates/{mandateId}

Requests amendments to Direct Debit Instruction

Supported reason codes are: C - Account transfered to a different branch of bank/building society E - Instruction amended

Parameters

accountId string, path, Required
The unique identifier for the account. This can be retrieved from GET /v1/Accounts
mandateId string, path, Required
The unique Direct Debit Instruction identifier
Authorization string, header, Required
Your API Token, retrieved from the web portal
DigitalSignature string, header, Required
Signed hash of the body of the request. The hash is signed by your private key
X-Request-Id string, header, Required
A unique identifier for the request

Request Payload (application/json)

reasonCode string, Required
Reason code for requesting the amendment
Pattern
^[EC]{1}$
newDebtorAccount object, Required
Information about the counterpart in a given transaction

request

{
  "reasonCode": "string",
  "newDebtorAccount": {
    "identification": {
      "iban": "string",
      "other": {
        "identification": "string",
        "schemeName": {
          "code": "BBAN",
          "proprietary": "string"
        },
        "issuer": "string"
      }
    }
  }
}

Code copied

Response (application/json)

202 Success
400 Bad Request
403 Forbidden
404 Not Found
500 Server Error
503 Server Error

Success

{
  "halLinks": [
    {
      "name": "string",
      "href": "string",
      "templated": true
    }
  ]
}

Code copied

Bad Request

{
  "errors": {
    "property1": [
      "string"
    ],
    "property2": [
      "string"
    ]
  },
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string"
}

Code copied

Return a DDI for an account

post/v1/Accounts/{accountId}/Mandates/{mandateId}/Returns

Requests rejection for the supplied Direct Debit Instruction identifier

Parameters

accountId string, path, Required
The unique identifier for the account. This can be retrieved from GET /v1/Accounts
mandateId string, path, Required
The unique Direct Debit Instruction identifier
Authorization string, header, Required
Your API Token, retrieved from the web portal
DigitalSignature string, header, Required
Signed hash of the body of the request. The hash is signed by your private key
X-Request-Id string, header, Required
A unique identifier for the request

Request Payload (application/json)

rejectionReason string, Required
The reason why the DDI is being returned
Pattern
^[BCFGHIK12356]{1}$

request

{
  "rejectionReason": "string"
}

Code copied

Response (application/json)

202 Success
400 Bad Request
403 Forbidden
409 Conflict
500 Server Error
503 Server Error

Success

{
  "halLinks": [
    {
      "name": "string",
      "href": "string",
      "templated": true
    }
  ]
}

Code copied

Bad Request

{
  "errors": {
    "property1": [
      "string"
    ],
    "property2": [
      "string"
    ]
  },
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string"
}

Code copied

Cancel a DDI for an account

delete/v1/Accounts/{accountId}/Mandates/{mandateId}

Requests cancellation for a Direct Debit mandate

Supported reason codes are:
0 - Institution cancelled - refer to payer. Paying bank has cancelled instruction.
1 - Instruction cancelled by payer. Payer has instructed the paying bank to cancel the DirectDebit Instruction.
2 - Payer deceased.
B - Account closed. Payer has closed their account for an unknown reason.

Parameters

accountId string, path, Required
The unique identifier for the account. This can be retrieved from GET /v1/Accounts
mandateId string, path, Required
The unique Direct Debit Instruction identifier
Authorization string, header, Required
Your API Token, retrieved from the web portal
DigitalSignature string, header, Required
Signed hash of the body of the request. The hash is signed by your private key
X-Request-Id string, header, Required
A unique identifier for the request

Request Payload (application/json)

reasonCode string, Required
The reason code
Pattern
^[0-2B]{1}$

request

{
  "reasonCode": "string"
}

Code copied

Response (application/json)

202 Success
400 Bad Request
403 Forbidden
404 Not Found
500 Server Error
503 Server Error

Success

{
  "halLinks": [
    {
      "name": "string",
      "href": "string",
      "templated": true
    }
  ]
}

Code copied

Bad Request

{
  "errors": {
    "property1": [
      "string"
    ],
    "property2": [
      "string"
    ]
  },
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string"
}

Code copied

Create a DDI for a virtual account

post/v1/Accounts/{accountId}/Virtual/{virtualAccountId}/Mandates

This endpoint is only required if you have received a validated Paper DDI and need to inform ClearBank of its existence. All other DDIs are set up through AUDDIS.

Requests creation of a Direct Debit Instruction

This endpoint uses a combination of the SUN and reference as a duplicate check and to ensure the request is idempotent.

Parameters

accountId string, path, Required
The unique identifier for the account. This can be retrieved from GET /v1/Accounts
virtualAccountId string, path, Required
The unique identifier for the virtual account. This can be retrieved from GET /v1/Accounts/{accountId}/Virtual
Authorization string, header, Required
Your API Token, retrieved from the web portal
DigitalSignature string, header, Required
Signed hash of the body of the request. The hash is signed by your private key
X-Request-Id string, header, Required
A unique identifier for the request

Request Payload (application/json)

serviceUserNumber string, Required
The service user number.
Pattern
^\d{6}$
originatorName string
The originator name.
Minimum length
0
Maximum length
18
Pattern
^[A-Z0-9\.\&\/\-\ ]*$
reference string, Required
The Service User's reference.
Minimum length
1
Maximum length
18
Pattern
^[A-Z0-9\.\&\/\-\ ]*$
payerName string
The payer name.
Minimum length
0
Maximum length
18
Pattern
^[A-Z0-9\.\&\/\-\ ]*$
counterpartAccount object
Information about the counterpart in a given transaction
mandateType string
The specified Instruction type for the request. (You will only use “Origination” and “Migrated” if you are transferring a sort code from another Direct Participant to the ClearBank® domain. “Migrated” indicates that the DDI was initially received as a paper item but later re-lodged in AUDDIS format by the Service User)
Enum array
PaperMandate, Origination, Migrated

request

{
  "serviceUserNumber": "string",
  "originatorName": "string",
  "reference": "string",
  "payerName": "string",
  "counterpartAccount": {
    "identification": {
      "iban": "string",
      "other": {
        "identification": "string",
        "schemeName": {
          "code": "BBAN",
          "proprietary": "string"
        },
        "issuer": "string"
      }
    }
  },
  "mandateType": "PaperMandate"
}

Code copied

Response (application/json)

202 Success
400 Bad Request
403 Forbidden
404 Not Found
500 Server Error
503 Server Error

Success

{
  "halLinks": [
    {
      "name": "string",
      "href": "string",
      "templated": true
    }
  ]
}

Code copied

Bad Request

{
  "errors": {
    "property1": [
      "string"
    ],
    "property2": [
      "string"
    ]
  },
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string"
}

Code copied

Get all DDIs for a virtual account

get/v2/Accounts/{accountId}/Virtual/{virtualAccountId}/Mandates

Gets all of the Direct Debit Instructions associated with the virtual account

Parameters

accountId string, path, Required
The unique identifier for the account. This can be retrieved from GET /V2/Accounts
virtualAccountId string, path, Required
The unique identifier for the virtual account. This can be retrieved from GET /V2/Accounts/{accountId}/Virtual
pageNumber integer, query
The page number to control returned results into manageable sets. Default if not supplied: 1
pageSize integer, query
The page size to control returned results into manageable sets. Default if not supplied: 50
Authorization string, header, Required
Your API Token, retrieved from the web portal

Response (application/json)

200 Success
400 Bad Request
403 Forbidden
409 Conflict
500 Server Error
503 Server Error

Success

{
  "directDebitMandates": [
    {
      "mandateId": "string",
      "payerName": "string",
      "payerBban": "string",
      "payerAccountNumber": "string",
      "payerSortCode": "string",
      "reference": "string",
      "serviceUserNumber": "string",
      "originatorName": "string",
      "state": "Active"
    }
  ],
  "halLinks": [
    {
      "name": "string",
      "href": "string",
      "templated": true
    }
  ]
}

Code copied

Bad Request

{
  "errors": {
    "property1": [
      "string"
    ],
    "property2": [
      "string"
    ]
  },
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string"
}

Code copied

Amend a DDI for a virtual account

patch/v1/Accounts/{accountId}/Virtual/{virtualAccountId}/Mandates/{mandateId}

Requests amendments to Direct Debit mandate for virtual account

Supported reason codes are: C - Account transfered to a different branch of bank/building society E - Instruction amended

Parameters

accountId string, path, Required
The unique identifier for the account. This can be retrieved from GET /v1/Accounts
virtualAccountId string, path, Required
The unique identifier for the virtual account
mandateId string, path, Required
The unique Direct Debit Instruction identifier
Authorization string, header, Required
Your API Token, retrieved from the web portal
DigitalSignature string, header, Required
Signed hash of the body of the request. The hash is signed by your private key
X-Request-Id string, header, Required
A unique identifier for the request

Request Payload (application/json)

reasonCode string, Required
Reason code for requesting the amendment
Pattern
^[EC]{1}$
newDebtorAccount object, Required
Information about the counterpart in a given transaction

request

{
  "reasonCode": "string",
  "newDebtorAccount": {
    "identification": {
      "iban": "string",
      "other": {
        "identification": "string",
        "schemeName": {
          "code": "BBAN",
          "proprietary": "string"
        },
        "issuer": "string"
      }
    }
  }
}

Code copied

Response (application/json)

202 Success
400 Bad Request
403 Forbidden
404 Not Found
500 Server Error
503 Server Error

Success

{
  "halLinks": [
    {
      "name": "string",
      "href": "string",
      "templated": true
    }
  ]
}

Code copied

Bad Request

{
  "errors": {
    "property1": [
      "string"
    ],
    "property2": [
      "string"
    ]
  },
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string"
}

Code copied

Return a DDI for a virtual account

post/v1/Accounts/{accountId}/Virtual/{virtualAccountId}/Mandates/{mandateId}/Returns

Requests rejection for the supplied Instruction identifier

Parameters

accountId string, path, Required
The unique identifier for the account. This can be retrieved from GET /v1/Accounts
virtualAccountId string, path, Required
The unique identifier for the virtual account
mandateId string, path, Required
The unique Direct Debit Instruction identifier
Authorization string, header, Required
Your API Token, retrieved from the web portal
DigitalSignature string, header, Required
Signed hash of the body of the request. The hash is signed by your private key
X-Request-Id string, header, Required
A unique identifier for the request

Request Payload (application/json)

rejectionReason string, Required
The reason why the DDI is being returned
Pattern
^[BCFGHIK12356]{1}$

request

{
  "rejectionReason": "string"
}

Code copied

Response (application/json)

202 Success
400 Bad Request
403 Forbidden
409 Conflict
500 Server Error
503 Server Error

Success

{
  "halLinks": [
    {
      "name": "string",
      "href": "string",
      "templated": true
    }
  ]
}

Code copied

Bad Request

{
  "errors": {
    "property1": [
      "string"
    ],
    "property2": [
      "string"
    ]
  },
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string"
}

Code copied

Cancel a DDI for a virtual account

delete/v1/Accounts/{accountId}/Virtual/{virtualAccountId}/Mandates/{mandateId}

Requests cancellation for a Direct Debit mandate for virtual account

Supported reason codes are: 0 - Institution cancelled - refer to payer. Paying bank has cancelled instruction. 1 - Instruction cancelled by payer. Payer has instructed the paying bank to cancel the DirectDebit Instruction (Mandate). 2 - Payer deceased B - Account closed. Payer has closed their account for an unknown reason.

Parameters

accountId string, path, Required
The unique identifier for the account. This can be retrieved from GET /v1/Accounts
virtualAccountId string, path, Required
The unique identifier for the virtual account. This can be retrieved from GET /v1/Accounts/{accountId}/Virtual
mandateId string, path, Required
The unique Direct Debit Instruction identifier
Authorization string, header, Required
Your API Token, retrieved from the web portal
DigitalSignature string, header, Required
Signed hash of the body of the request. The hash is signed by your private key
X-Request-Id string, header, Required
A unique identifier for the request

Request Payload (application/json)

reasonCode string, Required
The reason code
Pattern
^[0-2B]{1}$

request

{
  "reasonCode": "string"
}

Code copied

Response (application/json)

202 Success
400 Bad Request
403 Forbidden
404 Not Found
500 Server Error
503 Server Error

Success

{
  "halLinks": [
    {
      "name": "string",
      "href": "string",
      "templated": true
    }
  ]
}

Code copied

Bad Request

{
  "errors": {
    "property1": [
      "string"
    ],
    "property2": [
      "string"
    ]
  },
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string"
}

Code copied

If a DDI has been set up against an account via AUDDIS, payments may be collected from the account on the third day; for paper instructions, payments may be collected from the following day. The timing of the payment is in the control of the service user and does not necessarily follow immediately.

ClearBank® will notify you with a Bacs Direct Debit Inbound Created webhook on Day 2 and confirmation of settlement will be provided with a Transaction Settled webhook on Day 3.

If the payment cannot be applied to the account, ClearBank® will automatically raise an Automated Return of Unpaid Direct Debits (ARUDD). If the payment has been applied, but you still want to return it, you should use these endpoints and specify the reason for return. ClearBank® will notify you with a Bacs Direct Debit Return Created webhook. Returns can only be initiated until 15:30 (UTC) the working day after settlement. The payment will be applied to your Bacs Suspense account on the same day and returned on Day 5.

Return a Direct Debit payment for an account

post/v1/Accounts/{accountId}/Transactions/Returns

Creates a return of one or more Direct Debit or Direct Credit transactions for the account. This is only valid on the Entry Day, or the working day after before 15:30 UTC.

Parameters

accountId string, path, Required
The unique identifier for the account. This can be retrieved from GET /v1/Accounts
Authorization string, header, Required
Your API Token, retrieved from the web portal
DigitalSignature string, header, Required
Signed hash of the body of the request. The hash is signed by your private key
X-Request-Id string, header, Required
A unique identifier for the request

Request Payload (application/json)

returns array, Required
Array of transactions to be returned

request

{
  "returns": [
    {
      "transactionId": "string",
      "reasonCode": "string"
    }
  ]
}

Code copied

Response (application/json)

202 Success
400 Bad Request
404 Not Found

Success

{
  "halLinks": [
    {
      "name": "string",
      "href": "string",
      "templated": true
    }
  ]
}

Code copied

Bad Request

{
  "errors": {
    "property1": [
      "string"
    ],
    "property2": [
      "string"
    ]
  },
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string"
}

Code copied

Return a Direct Debit payment for a virtual account

post/v1/Accounts/{accountId}/Virtual/{virtualAccountId}/Transactions/Returns

Creates a return of one or more Direct Debit or Direct Credit transactions for the virtual account

Parameters

accountId string, path, Required
The unique identifier for the account. This can be retrieved from GET /v1/Accounts
virtualAccountId string, path, Required
The unique identifier for the virtual account. This can be retrieved from GET /v1/Accounts/{accountId}/Virtual
Authorization string, header, Required
Your API Token, retrieved from the web portal
DigitalSignature string, header, Required
Signed hash of the body of the request. The hash is signed by your private key
X-Request-Id string, header, Required
A unique identifier for the request

Request Payload (application/json)

returns array, Required
Array of transactions to be returned

request

{
  "returns": [
    {
      "transactionId": "string",
      "reasonCode": "string"
    }
  ]
}

Code copied

Response (application/json)

202 Success
400 Bad Request
404 Not Found

Success

{
  "halLinks": [
    {
      "name": "string",
      "href": "string",
      "templated": true
    }
  ]
}

Code copied

Bad Request

{
  "errors": {
    "property1": [
      "string"
    ],
    "property2": [
      "string"
    ]
  },
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string"
}

Code copied