NAV Navbar
  • Handling Direct Debit Instructions as a Direct Debit Originator
  • Handling Direct Debit Instructions as a Direct Debit Originator

    This tutorial explains how to use the Form3 API to send and cancel Bacs Direct Debit Instructions (DDI) as an originating bank. We'll begin with a quick introduction to Direct Debit Instructions in Bacs. Then follows a step by step guide for how to handle DDIs in the Form3 API.

    If you're looking for information on how to handle DDIs as a paying bank, we have a separate tutorial for that.

    For more detailed information about Bacs Direct Debit, please take a look at the Bacs scheme documentation available for members at https://www.bacs.co.uk.

    Terminology

    The terms Direct Debit Instruction and mandate are sometimes used interchangeably, which can cause confusion. To avoid this problem, this tutorial adheres to the following terminology: we will use Direct Debit Instruction or DDI to refer to the Bacs concept of an instruction that permits an originator to collect a Direct Debit. We'll use Mandate to refer to the Mandate resource in the Form3 API, which for Bacs represents a DDI at a specific point in time.

    Direct Debit Instructions in Bacs

    Direct Debit Instructions document an authorisation agreement between a debtor and a beneficiary to collect Direct Debits in Bacs.

    Before a Direct Debit collection can happen, the debtor and the beneficiary of the Direct Debit agree on the terms of the collection (such as amount and frequency). A Direct Debit Instruction is set up as a record of this agreement and stored by both the beneficiary's and the debtor's bank (the originating and paying bank, respectively).

    While Form3 keeps records of all received Direct Debit Instructions on its system, it is not suitable to use as a comprehensive Direct Debit Instruction management tool since instructions can also be issued in other ways (such as paper).

    Like any other Bacs transaction, Direct Debit Instructions adhere to the Bacs 3-day cycle. The cycle starts when the originating bank submits the Direct Debit Instruction. The paying bank will receive the inbound instruction on day 2 and the instruction will become effective on day 3. In case a Direct Debit Instruction is rejected and returned by the paying bank, the rejection needs to be submitted to the scheme on day 3.

    Bacs Cycle

    AUDDIS

    The AUtomated Direct Debit Instruction Service (AUDDIS) is used to notify the paying bank of the setup of a new Direct Direct Instruction or the cancellation of an existing DDI by the originating bank. When receiving a Direct Debit Instruction, the paying bank can reject the instruction if it is invalid.

    ADDACS

    ADDACS, the Automated Direct Debit Amendment and Cancellation Service‚Äč, is used to communicate when a DDI has been cancelled or changed. In the Form3 API, ADDACS works similar to creating a new DDI, by creating a Mandate resource and a Mandate Submission resource.

    Step by step guide

    In this section, we'll walk you through each step of handling Direct Debit Instructions as an originator using the Form3 API. In the guide, you will:

    Prerequisites

    Before getting started, make sure you have the following things ready to follow along:

    Creating a Direct Debit Instruction

    To create a new DDI, create a Mandate resource and send it by creating a Mandate Submission resource.

    For the Mandate resource, choose the following mandatory parameters:

    The Reference Attribute

    The Bacs core reference in the reference attribute has to be the same number that was mentioned on the paper or screen where the DDI was signed. The reference is also used when making a Direct Debit collection request against the DDI.

    Bacs requires the core reference to be between 6 and 18 characters long and only allows upper case alpha and numeric characters, as well as /, &, ., - and (space). It cannot contain DDIC as the first 4 characters. The core reference needs to be quoted in each Direct Debit collection request. Note that in a Direct Debit collection request, the reference field can contain additional characters to distinguish between different collection requests against the same instruction.

    For a full list of attributes, including optional parameters, see the API documentation.

    Create the Mandate Resource

    Create the Mandate resource using this request: POST v1/transaction/mandates.

    Request body for creating a Mandate resource

    {
      "data":{
        "id": "9e310adb-5ba1-477c-9197-7631e86246ed",
        "organisation_id": "cc03827b-1578-415c-8f02-aea094f34247",
        "attributes": {
          "amount": "0.00",
          "beneficiary_party": {
            "account_name": "Mrs Receiving Test",
            "account_number": "39927360",
            "account_number_code": "BBAN",
            "account_with": {
              "bank_id": "400302",
              "bank_id_code": "GBDSC"
            }
          },
          "clearing_id": "123456",
          "currency": "GBP",
          "debtor_party": {
            "account_name": "Mr Sending Test",
            "account_number": "20621803",
            "account_number_code": "BBAN",
            "account_with": {
              "bank_id": "112233",
              "bank_id_code": "GBDSC"
            }
          },
          "payment_scheme": "BACS",
          "reference": "D/1234567890123456",
          "scheme_payment_type": "DirectDebitInstructionNew"
        }
      }
    }
    

    Create the Mandate Submission resource

    To send the DDI, create a Mandate Submission resource for the Mandate resource. Use this request to do so: POST v1/transaction/mandates/{mandate_id}/submissions

    Note that the mandate_id URL parameter is the ID of the Mandate resource you created above.

    The Submission resource doesn't require any body attributes beyond the resource ID, type and organisation ID.

    Request body for creating a Mandate Submission resource

    {
      "data": {
        "id": "64d16433-bff5-4257-8dec-439bffa6c3cd",
        "type": "mandate_submissions",
        "organisation_id": "cc03827b-1578-415c-8f02-aea094f34247"
      }     
    }
    


    The response shows the status of the Mandate Submission as well as the content of the Mandate resource in both the original_mandate and submitted_mandate structures:

    {
      "data": {
        "id": "64d16433-bff5-4257-8dec-439bffa6c3cd",
        "organisation_id": "cc03827b-1578-415c-8f02-aea094f34247",
        "type": "mandate_submissions",
        "version": 1,
        "attributes": {
          "status": "validation_pending",
          "status_reason": "accepted",
          "submission_datetime": "2019-06-27T20:42:09.646Z",
          "last_payment_date": "0001-01-01",
          "original_mandate": {
            "amount": "0.00",
            "beneficiary_party": {
              "account_name": "Mrs Receiving Test",
              "account_number": "39927360",
              "account_number_code": "BBAN",
              "account_with": {
                "bank_address": null,
                "bank_id": "400302",
                "bank_id_code": "GBDSC"
              },
              "address": null
            },
            "clearing_id": "123456",
            "currency": "GBP",
            "debtor_party": {
              "account_name": "Mr Sending Test",
              "account_number": "20621803",
              "account_number_code": "BBAN",
              "account_with": {
                "bank_address": null,
                "bank_id": "112233",
                "bank_id_code": "GBDSC"
              },
              "address": null
            },
            "payment_scheme": "BACS",
            "processing_date": "2019-06-27",
            "reference": "D/1234567890123456",
            "scheme_payment_type": "DirectDebitInstructionNew",
            "scheme_processing_date": "0001-01-01"
          },
          "submitted_mandate": {
            "amount": "0.00",
            "beneficiary_party": {
              "account_name": "Mrs Receiving Test",
              "account_number": "39927360",
              "account_number_code": "BBAN",
              "account_with": {
                "bank_address": null,
                "bank_id": "400302",
                "bank_id_code": "GBDSC"
              },
              "address": null
            },
            "clearing_id": "123456",
            "currency": "GBP",
            "debtor_party": {
              "account_name": "Mr Sending Test",
              "account_number": "20621803",
              "account_number_code": "BBAN",
              "account_with": {
                "bank_address": null,
                "bank_id": "112233",
                "bank_id_code": "GBDSC"
              },
              "address": null
            },
            "payment_scheme": "BACS",
            "processing_date": "2019-06-27",
            "reference": "D/1234567890123456",
            "scheme_payment_type": "DirectDebitInstructionNew",
            "scheme_processing_date": "0001-01-01"
          }
        }
      },
      "links": {
        "self": "/v1/transaction/mandates/9e310adb-5ba1-477c-9197-7631e86246ed/submissions/64d16433-bff5-4257-8dec-439bffa6c3cd"
      }
    }
    

    Canceling a Direct Debit Instruction

    Cancelling a Direct Debit Instruction works similar to creating one: Create a Mandate resource and send it by creating a Mandate Submission resource. The only difference is that now the scheme_payment_type attribute needs to be DirectDebitInstructionCancel.

    Note that the paying bank will use the reference field to identify the Direct Debit Instruction to cancel. Because of the nature of Bacs, using an incorrect Bacs core reference will not lead to an immediate error. Instead, the paying bank will reject the mandate and issue a return if it cannot identify the DDI to cancel.

    Just like when setting up the DDI, use the following API request to create the Mandate resource: POST v1/transaction/mandates.

    Request body for creating a Mandate resource to cancel a DDI

    {
      "data":{
        "id": "9e310adb-5ba1-477c-9197-7631e86246ed",
        "organisation_id": "cc03827b-1578-415c-8f02-aea094f34247",
        "attributes": {
          "amount": "0.00",
          "beneficiary_party": {
            "account_name": "Mrs Receiving Test",
            "account_number": "39927360",
            "account_number_code": "BBAN",
            "account_with": {
              "bank_id": "400302",
              "bank_id_code": "GBDSC"
            }
          },
          "clearing_id": "123456",
          "currency": "GBP",
          "debtor_party": {
            "account_name": "Mr Sending Test",
            "account_number": "20621803",
            "account_number_code": "BBAN",
            "account_with": {
              "bank_id": "112233",
              "bank_id_code": "GBDSC"
            }
          },
          "payment_scheme": "BACS",
          "reference": "D/1234567890123456",
          "scheme_payment_type": "DirectDebitInstructionCancel"
        }
      }
    }
    


    To send the cancellation request, create a Mandate Submission resource using the following request: POST v1/transaction/mandates/{mandate_id}/submissions.

    Note that the mandate_id URL parameter is the ID of the Mandate resource you created above.

    Just like when creating DDI, the body required no further attributes beyond the resource ID, type and organisation ID.

    Further Reading

    This tutorial explained how to handle Bacs Direct Debit Instruction in the Form3 API as an originator bank. For more information on using Bacs as a paying bank with Form3, see our other tutorials: