Bacs Direct Debits

Managing Direct Debit Instructions

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

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.

  • originatorName string,

    The originator name.

  • reference string, Required

    The Service User's reference.

  • payerName string,

    The payer name.

  • 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)

    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

  • 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

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

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

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.

  • originatorName string,

    The originator name.

  • reference string, Required

    The Service User's reference.

  • payerName string,

    The payer name.

  • 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)

    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

  • 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

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

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

Returning Payments

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 maybe 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