NAV Navbar
  • Receiving a Bacs Direct Debit
  • Receiving a Bacs Direct Debit

    This tutorial shows you how to receive Bacs Direct Debit collection requests in the Form3 API. We first give an overview of how Direct Debit works in Bacs and then provide a step by step guide on how to receive a Direct Debit collection request.

    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.

    Bacs Direct Debit basics

    Direct Debit is a pull-based transaction method, meaning payments are collected rather than sent. A Direct Debit can be a recurring transaction (often used for subscriptions) or a one-time transaction (for example for invoicing). For recurring transactions, the collected amount and collection frequency can vary.

    Direct Debit Instructions / mandates

    To allow Direct Debit collections, the beneficiary sends a request to set up a mandate to the debtor’s bank after both beneficiary and debtor have agreed on the terms of the collection (such as amount and frequency). This mandate request (also called a Direct Debit Instruction or DDI in Bacs) authorises subsequent collections. The setup of a mandate has to happen in advance of any Direct Debit transactions.

    A version of the mandate is kept by both the debtor's and beneficiary's banks. The mandate contains a reference number that is present in each Direct Debit request to match requests against mandates.

    In the Form3 API, a mandate is represented by the Mandate resource. Once set up, mandates can also be cancelled and amended through the API.

    Direct Debit collection

    The debtor of a Direct Debit needs to be given advance notice before a collection request can be sent. The advance notice has to be provided once for recurring collections with unchanging amount and frequency. When either amount or frequency change, advance notice has to be given before the next transaction. The notification process happens directly between the debtor and the beneficiary of the Direct Debit and is outside the scope of Form3's services.

    To collect a Direct Debit, the beneficiary has to send a collection request. Once submitted, the request is processed by Bacs and sent to the debtor's bank. In the Form3 API, an inbound Direct Debit collection request is represented by a Direct Debit resource and a Direct Debit Admission resource.

    Like any other Bacs transaction, Direct Debits adhere to the Bacs 3-day cycle. The cycle starts when the beneficiary submits the Direct Debit request. The debtor bank will receive the inbound Direct Debit request on day 2 and the funds will be transferred on day 3.

    Bacs Cycle

    Error Handling

    Direct Debit Returns

    In case a Direct Debit cannot be applied, it has to be returned using the Automated Return of Unpaid Direct Debits (ARUDD) service. See this tutorial to learn how to do this with the Form3 API.

    Form3 automatically creates a return on your behalf in case it receives an inbound Direct Debit to an account number that is not registered with your sort code at Form3.

    When this happens, a Direct Debit Admission resource and a Direct Debit resource are created just like for any inbound Direct Debit. The status attribute of the Direct Debit Admission resource will say failed and the status_reason attribute will specify the reason as unknown_accountnumber.

    See our tutorial to learn more about how to register an account with Form3.

    Indemnity Claims

    The Direct Debit Guarantee protects customers from fraudulent or erroneous Direct Debits. As part of this guarantee, Bacs offers a way to request a refund for a collected Direct Debit. This process is called an Indemnity Claim and is modeled in the Form3 API through the Claim resource. See our indemnity claim tutorial to learn more.

    Direct Debits in the Form3 API

    In the Form3 API, a Direct Debit request is represented by the Direct Debit resource. Its design is similar to the Payment resource, containing the following key attributes (see the API documentation for a full list of attributes and further information):

    Note that the reference needs to start with the core reference of the Direct Debit instruction that the Direct Debit request should be collected against. It may contain additional characters to distinguish this collection requests from others agains the same Direct Debit Instruction. For example, if the core reference of the instruction is AB/12345 DC, the reference of a Direct Debit request for this instruction may be AB/12345 DC - 1.

    For inbound Direct Debits, a Direct Debit Admission resource is created to signal the arrival of the Direct Debit request. The admission resource contains information about the status of the Direct Debit request, when it was created (field admission_datetime) and other transmission-relation information.

    You can use Form3's Notification API to be notified when a new Direct Debit request arrives. See below to learn how to set up a subscription to these notifications.

    Step by step guide

    In this section, we'll walk you through each step of receiving a Direct Debit collection request using the Form3 API. In the guide, you will:

    Prerequisites

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

    Subscribe to Direct Debit Admission Events

    You can use Form3's Notification API to be notified when inbound transactions or other messages arrive. Create a subscription for an event type and record type to be notified through a webhook or SQS queue when this event occurs for a type of resource.

    When an inbound Direct Debit request arrives, Form3 creates a Direct Debit resource and a Direct Debit Admission resource. In order to be notified when this happens, subscribe to the creation of Direct Debit Admission resources using the following parameters:

    See this tutorial to learn how to create a subscription and receive notifications.

    Trigger an inbound Direct Debit request

    For this tutorials, we're using Form3's transaction simulator to receive a Direct Debit request. The simulator allows you to trigger an inbound Direct Debit by sending a payment with an amount of 700.00.

    To send a trigger payment, first create a Payment resource. Note the following key attributes:

    Take a look at this tutorial and example to learn how to create a Payment resource.

    Finally, to send the trigger payment, create a Payment Submission resource. See here to learn how.

    Receive the Direct Debit request

    Upon successful delivery of the trigger payment, the transaction simulator will generate a Direct Debit Admission resource to indicate an inbound Direct Debit request. Since you subscribed to the creation of Direct Debit Admissions above, check your webhook or SQS queue for a notification that an admission has been created. Note that it may take a few minutes to receive the notification.

    The notification contains a data section with the Direct Debit Admission resource embedded. There, you can also find the Direct Debit resource embedded in the relationships.direct_debit section of the Direct Debit Admission.

    The notification will look like this:

    Direct Debit Admission notification

    {
      "id": "f50a6966-6f19-497f-9c0a-51a4660d4f7a",
      "organisation_id": "c85f7096-168d-41ee-b399-8cc71b4853a4",
      "event_type": "created",
      "record_type": "direct_debit_admissions",
      "data": {
        "data": {
          "attributes": {
            "admission_datetime": "2019-02-08T15:56:12.300Z",
            "status": "confirmed",
            "status_reason": "accepted"
          },
          "id": "ee04f8b4-f68d-471f-a19c-f4c455ecdb75",
          "organisation_id": "c85f7096-168d-41ee-b399-8cc71b4853a4",
          "relationships": {
            "direct_debit": {
              "data": [
                {
                  "attributes": {
                    "amount": "700.00",
                    "beneficiary_party": {
                      "account_name": "MR SENDING TEST",
                      "account_number": "87654321",
                      "account_number_code": "BBAN",
                      "account_with": {
                        "bank_id": "333333",
                        "bank_id_code": "GBDSC"
                      }
                    },
                    "clearing_id": "112233",
                    "currency": "GBP",
                    "debtor_party": {
                      "account_name": "MRS RECEIVING TEST",
                      "account_number": "12345678",
                      "account_number_code": "BBAN",
                      "account_with": {
                        "bank_id": "123456",
                        "bank_id_code": "GBDSC"
                      }
                    },
                    "numeric_reference": "0001",
                    "payment_scheme": "BACS",
                    "processing_date": "2019-02-11",
                    "reference": "D/1234567890123456",
                    "scheme_payment_type": "DirectDebitFirst",
                    "scheme_processing_date": "2019-02-08",
                    "unique_scheme_id": "12345678",
                    "scheme_status": "AUDDIS"
                  },
                  "id": "7a331c26-ef8b-4fb4-8c92-9d82ea01554c",
                  "organisation_id": "c85f7096-168d-41ee-b399-8cc71b4853a4",
                  "type": "direct_debits",
                  "version": 0
                }
              ]
            }
          },
          "type": "direct_debit_admissions",
          "version": 0
        }
      }
    }
    


    In line with the Bacs 3-day cycle, the current day is day 2 of the cycle for the inbound Direct Debit (the day transaction data is processed and transmitted to the recipient). Consequently, the processing_date field of the Direct Debit resource shows the date of the next working day - day 3 - when the funds will be transferred.

    The reference field contains the reference to the mandate this Direct Debit request relates to. Always make sure you have a mandate with this reference number in your mandate management system when receiving a Direct Debit request.

    Retrieve the Direct Debit request via GET

    Instead of gathering the Direct Debit and Direct Debit Admission data from the notification, you can also perform GET requests using the IDs of the resources that are provided in the notification.

    To fetch the Direct Debit Admission resource use the GET v1/transaction/directdebits/{direct_debit_id}/admissions/{admission_id} call.

    The Direct Debit resource can be fetched using GET v1/transaction/directdebits/{direct_debit_id}

    Further Reading

    You now know how to receive a Direct Debit request. To learn more about how to use the Form3 API with Bacs, see our other tutorials: