NAV Navbar
  • Returning Inbound Bacs Direct Debits (ARUDD)
  • Returning Inbound Bacs Direct Debits (ARUDD)

    This guide explains how to use the Form3 API to return an inbound Bacs Direct Debit based on the Automated Return of Unpaid Direct Debits (ARUDD).

    We will first go over the mechanics of Direct Debit returns in Bacs. Then follows a step-by-step guide on how to send a Direct Debit return with the Form3 API including a code example.

    About ARUDD and Returning Bacs Direct Debits

    The ARUDD service handles the return of unpaid Bacs Direct Debit payments in case of an error or when the Direct Debit payment cannot be collected. The most common reasons for this to happen include insufficient funds on the debited account, a cancelled mandate, and others.

    If you discover that an inbound Direct Debit cannot be collected, you have to return it through ARUDD. Using the Form3 API, you can do this by creating a Direct Debit Return resource and sending it by creating a Direct Debit Return Submission resource.

    Note that the Direct Debit Return resource needs to reference the original Direct Debit resource it returns, so you can only issue returns for Direct Debits that have been received through the Form3 API.

    Bacs Direct Debit returns follow Bacs' 3-day cycle just like any other Bacs transaction. Although you will receive the notice of the inbound Direct Debit on day 2 of the Bacs cycle, you will not be able to issue the return until day 3 when the Direct Debit is entered. As soon as the return is submitted, a new 3-day cycle begins, meaning the Direct Debit return will arrive at the original creditor on day 5 of the original Direct Debit's Bacs cycle.

    Bacs Cycle

    Automatic Returns

    This tutorial focuses on manual returns. 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.

    Below is an example of a failed inbound Direct Debit with the Direct Debit resource, as well as the related Direct Debit Admission.

    Failed Direct Debit due to an unknown account number

    "data": {    
        "id": "6cb873d0-a747-459b-8dbd-854d7d17c2bf",
        "organisation_id": "2ffed0e3-876a-cb70-06b1-a27dd0884449",
        "attributes": {
            "amount": "23.40",
            "beneficiary_party": {
                "account_name": "O2",
                "account_number": "12345678",
                "account_number_code": "BBAN",
                "account_with": {
                    "bank_id": "654321",
                    "bank_id_code": "GBDSC"
                },
                "address": [
                    "1 Clarence Mew",
                    "Horsforth",
                    "Leeds Ls18 4EP"
                ],
            },
            "clearing_id": "757871",
            "currency": "GBP",
            "debtor_party": {
                "account_name": "TEST",
                "account_number": "87654321",
                "account_number_code": "BBAN",
                "account_with": {
                    "bank_id": "123456",
                    "bank_id_code": "GBDSC"
                },
                "address": [
                    "2 Alexandra Crescent",
                    "Ilkley",
                    "LS29 9ER"
                ],
            },
            "numeric_reference": " 341",
            "payment_scheme": "BACS",
            "processing_date": "2018-12-10",
            "reference": "05761374/001",
            "scheme_payment_type": "DirectDebit",
            "scheme_processing_date": "0001-01-01",
            "unique_scheme_id": "008630DD",
            "scheme_status": "AUDDIS"
        },
        "relationships": {
            "direct_debit_admission": {
                "data": [
                    {
                        "attributes": {
                            "admission_datetime": "2018-12-07T00:45:48.016Z",
                            "status": "failed",
                            "status_reason": "unknown_accountnumber"
                        },
                        "id": "ce473c71-2dc3-449e-90d3-56b45946ba94",
                        "organisation_id": "2ffed0e3-876a-cb70-06b1-a27dd0884449",
                        "type": "direct_debit_admissions",
                        "version": 0
                    }
                ]
            },
            "direct_debit_return": {
                "data": []
            },
            "direct_debit_reversal": {
                "data": []
            }
        },
        "type": "direct_debits",
        "version": 0
    }
    
    


    Note that this Direct Debit never actually reached you, despite there being a Direct Debit resource. The resource is only created for bookkeeping purposes.

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

    Contras

    Bacs uses contras to sum up return transactions for the originator account. This means that when sending one or more Direct Debit returns, you will receive a contra on Bacs day 4. Because a contra "counters" the Direct Debit return, it is modeled in the API as a Payment resource and a Payment Admission resource. Note that although the contra appears as a regular transaction, no funds are transferred with it.

    Since Bacs is a bulk processing system, transaction are sent to Bacs in batches and a contra record is generated for each batch of Direct Debit returns. Form3 batches and sends transactions to Bacs a few times a day, so a contra can cover any number of Direct Debit returns between just one and all that have been submitted in a day. This includes automatic returns that have been created by Form3 on your behalf (see above).

    A contra will sum up all Direct Debit returns in a batch. For example, if you have created three Direct Debit returns with an amount of 10.00 each and Form3 has issued one automated return with an amount of 15.00, the contra amount would be 45.00.

    In contrast to a regular payment, the beneficiary and debtor account of a contra is identical and points to your main settlement account that you have registered with Bacs.

    You can distinguish a contra from a regular payment by looking at the reference attribute of the Payment resource. For a contra, it will contain the value               BACS (the word BACS preceded by 14 spaces).

    Below is an example of a Payment resource for a contra:

    Payment resource and admission for a contra

    {
      "data": {
        "type": "payments",
        "version": 0,
        "id": "bff0fce7-c77d-47f8-92e1-a3e09042a65a",
        "organisation_id": "ace476a0-5523-e007-5613-ba145f151204",
        "attributes": {
          "amount": "2345.00",
          "beneficiary_party": {
            "account_name": "ABCD SUSPENSE",
            "account_number": "00000051",
            "account_number_code": "BBAN",
            "account_with": {
              "bank_id": "040012",
              "bank_id_code": "GBDSC"
            },
            "address": null
          },
          "clearing_id": "100026",
          "currency": "GBP",
          "debtor_party": {
            "account_name": "ABCD SUSPENSE",
            "account_number": "00000051",
            "account_number_code": "BBAN",
            "account_with": {
              "bank_id": "040012",
              "bank_id_code": "GBDSC"
            },
            "address": null
          },
          "numeric_reference": "0001",
          "payment_scheme": "BACS",
          "processing_date": "2018-12-05",
          "reference": "              BACS",
          "scheme_payment_type": "Credit",
          "unique_scheme_id": "12345678"
        },
        "relationships": {
          "payment_admission": {
            "data": [
              {
                "attributes": {
                  "admission_datetime": "2018-12-04T15:37:12.809Z",
                  "status": "confirmed",
                  "status_reason": "accepted"
                },
                "id": "65ae72a9-1f8c-4e3c-bdc6-e9d2a56fc5a2",
                "organisation_id": "ace476a0-5523-e007-5613-ba145f151204",
                "type": "payment_admissions",
                "version": 0
              }
            ]
          },
          "payment_return": {
            "data": []
          },
          "payment_reversal": {
            "data": []
          }
        },
      }
    }
    


    Note that contras are also issued for Direct Credit returns (ARUCS). In this case, the Form3 API models them as a Direct Debit and Direct Debit Admission resource. See here for more information on returning Direct Credits with ARUCS.

    Step by Step Guide

    Now we'll walk you through each step of creating and sending an ARUDD return. Code examples are provided to illustrate the steps. You will:

    The code example is written in Python using the requests package to access the Form3 API. Each code snippet is a standalone Python program, but make sure to paste the required data for each program at the top. The snippets are tested with Python 3.5, but most likely will also work with other Python versions.

    Prerequisites

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

    Subscribe to Direct Debit Admission and Contra Events

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

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

    Direct Debit Admissions

    When an inbound Direct Debit 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 POST /v1/notification/subscriptions call:

    Contras

    Contras for Direct Debit returns are modeled as Payment and Payment Admission resources. To be notified when a contra arrives, create a subscription for the creation of Payment Admission resources using the POST /v1/notification/subscriptions call:

    Receive a Direct Debit

    In order to return a Direct Debit, you need to receive it first. In Form3's sandbox environment, the transaction simulator allows you to trigger an inbound Direct Debit by sending a payment with an amount of 700.00.

    Upon acceptance of the trigger payment, the simulator issues an inbound Direct Debit.

    Send a Trigger Payment

    To send a trigger payment, first create a Payment resource. Make sure to set 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.

    Get the Incoming Direct Debit

    Upon successful delivery of the trigger payment, the transaction simulator will generate a Direct Debit Admission resource to indicate an inbound Direct Debit. 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 the admission_datetime field of the Direct Debit Admission is adjusted to fit the 3-day Bacs cycle and thus shows the date of the next working day.

    The notification should look similar to this:

    Direct debit admission notification

    {
      "id": "12d85468-6b57-4588-85c3-968a9524d247",
      "organisation_id": "6da00442-545f-4131-9a63-3cdd30c2b83a",
      "event_type": "created",
      "record_type": "direct_debit_admissions",
      "data": {
        "data": {
          "attributes": {
            "admission_datetime": "2018-11-01T16:16:14.838Z",
            "status": "confirmed",
            "status_reason": "accepted"
          },
          "id": "a6879704-655a-4272-a8e6-b6769555ce4f",
          "organisation_id": "6da00442-545f-4131-9a63-3cdd30c2b83a",
          "relationships": {
            "direct_debit": {
              "data": [
                {
                  "attributes": {
                    "amount": "700.00",
                    "beneficiary_party": {
                      (...)
                      }
                    },
                    "clearing_id": "112233",
                    "currency": "GBP",
                    "debtor_party": {
                      (...)
                      }
                    },
                    "numeric_reference": "0001",
                    "payment_scheme": "BACS",
                    "processing_date": "2018-11-02",
                    "reference": "D/1234567890123456",
                    "scheme_payment_type": "DirectDebitFirst",
                    "unique_scheme_id": "12345678",
                    "scheme_status": "AUDDIS"
                  },
                  "id": "143610ac-f875-4e7c-86c1-19c9eb3bcd21",
                  "organisation_id": "6da00442-545f-4131-9a63-3cdd30c2b83a",
                  "type": "direct_debits",
                  "version": 0
                }
              ]
            }
          },
          "type": "direct_debit_admissions",
          "version": 0
        }
      }
    }
    


    The message body of the notification contains the admission data. The status attribute says confirmed and the status_reason attribute contains accepted, indicating the Direct Debit has been received without errors.

    The admission data references the Direct Debit resource in its relationships section. Note that it has the same debtor and beneficiary as the trigger payment and uses the same amount, 700.00.

    Return the Direct Debit

    To return the Direct Debit, create a Direct Debit Return resource and send it by creating a Direct Debit Return Submission resource.

    Bacs returns have to adhere to the 3-day Bacs processing cycle. Although you will receive the Direct Debit information on Bacs day 2, Form3 will hold any submitted return transactions until Bacs day 3 of the original inbound Direct Debit's cycle.

    Since the transaction simulator issued the inbound direct debit for the next working day, you won't be able to submit the return until that day. Creating a Direct Debit Return Submission before the day mentioned in the admission_datetime attribute of the Direct Debit Admission of the direct debit you want to return will result in a failed delivery for the return.

    Note that since return transactions are always issued to Bacs on day 3, the Direct Debit Return resource has no processing_date attribute like the Direct Debit resource does.

    Create the Direct Debit Return

    To create a Direct Debit Return resource, use the following API call: POST v1/transaction/directdebits/{direct_debit_id}/returns

    Note that the API call requires the ID of the original Direct Debit resource in the direct_debit_id URL parameters.

    The resource itself requires just one attribute: return_code: contains the reason for the return. See here for a list of valid reason codes for ARUDD. In the example below we're using 1, which translates to "Instruction cancelled".

    Direct debit return resource example

    {
      "data": {
        "type": "direct_debit_returns",
        "id": "792dca39-a928-49fa-817c-5b6978a553bf",
        "version": 0,
        "organisation_id": "3f381bf0-f62e-461c-98a8-0b896493f344",
        "attributes": {
          "return_code": "1",
        }
      }
    }
    

    Create the Return Submission

    Finally, send the return by creating a Direct Debit Return Submission resource with POST v1/transaction/directdebits/{direct_debit_id}/returns/{direct_debit_return_id}/submissions.

    The call requires the ID of the original Direct Debit in the direct_debit_id URL parameter, as well as the ID of the Direct Debit Return resource created above in the direct_debit_return_id parameter.

    Keep in mind that you won't be able to submit the return until the admission date of the direct debit you want to return.

    Direct debit return submission resource example

    {
      "data": {
        "type": "direct_debit_return_submissions",
        "version": 0,
        "id": "04a29217-12ed-41da-a456-75a3c76a4c32",
        "organisation_id": "3f381bf0-f62e-461c-98a8-0b896493f344",
        "attributes": {
          "scheme_status_code": "",
          "scheme_status_code_description": "",
          "status": "delivery_confirmed",
          "status_reason": "Accepted without qualification",
          "submission_datetime": "2018-10-04T08:43:19.370Z",
          "transaction_start_datetime": "2018-10-04T08:43:19.370Z"
        },
        "relationships": {
          "direct_debit": {
            "data": [
              {
                "id": "1bd9b998-813d-49c1-9ccd-ca42ff0ad453",
                "type": "direct_debits"
              }
            ]
          },
          "direct_debit_return": {
            "data": [
              {
                "id": "792dca39-a928-49fa-817c-5b6978a553bf",
                "type": "direct_debit_returns"
              }
            ]
          }
        }
      }
    }
    


    This Python example creates a return transaction for an existing inbound Direct Debit:

    import math, requests, time, uuid
    
    ### Replace these variables with your own data! ###
    client_id = 'YOUR CLIENT ID HERE'
    client_secret = 'YOUR CLIENT SECRET HERE'
    organisation_id = 'YOUR ORGANISATION ID HERE'
    direct_debit_id = 'ID OF THE ORIGINAL DIRECT DEBIT HERE'
    
    base_url = 'https://api.staging-form3.tech/v1'
    
    # Generate IDs
    return_id = uuid.uuid4()
    print("Return ID: %s" % return_id)
    
    submission_id = uuid.uuid4()
    print("Submission ID: %s" % submission_id)
    
    # Obtain authentication token
    print("Obtaining bearer token...")
    auth_payload = "grant_type=client_credentials"
    auth_url = '%s/oauth2/token' % base_url
    auth_headers = {'Content-Type': 'application/x-www-form-urlencoded'}
    auth_request = requests.auth.HTTPBasicAuth(client_id, client_secret)
    
    auth = requests.request('post', auth_url, data=auth_payload, auth=auth_request, headers=auth_headers)
    auth_token = auth.json().get('access_token')
    
    # Create the return resource
    return_url = "%s/transaction/directdebits/%s/returns" % (base_url, direct_debit_id) 
    return_payload = """
    {
      "data": {
        "id": "%s",
        "type": "direct_debit_returns",
        "organisation_id": "%s",
        "attributes": {
          "return_code": "1",
        }
      }
    }  
    """ % (return_id, organisation_id)
    
    return_headers = {
        'authorization': "bearer " + auth_token,
        'accept': "application/json",
        'content-type': "application/json",
        'cache-control': "no-cache"
        }
    
    direct_debit_return = requests.request("POST", return_url, data=return_payload, headers=return_headers)
    print(direct_debit_return.text)
    
    # Create the submission resource
    print("Creating Direct Debit Return Submission resource...")
    submission_url = "%s/transaction/directdebits/%s/returns/%s/submissions" % (base_url, direct_debit_id, return_id)
    submission_payload = """
    {
      "data": {
        "id": "%s",
        "type": "direct_debit_return_submissions",
        "organisation_id": "%s"
      }
    }
    """ % (submission_id, organisation_id)
    
    submission_headers = {
        'authorization': "bearer %s" % auth_token,
        'accept': "application/json",
        'content-type': "application/json",
        'cache-control': "no-cache",
        }
    
    submission = requests.request("POST", submission_url, data=submission_payload, headers=submission_headers)
    print(submission.text)
    

    Track the Direct Debit Return

    You can follow the path of your return transaction through the system by fetching the submission resource: GET v1/transaction/directdebits/{direct_debit_id}/return/{direct_debit_return_id}/submissions/{direct_debit_return_submission_id}

    The following attributes can be helpful to determine the status of the return:

    See this example to learn how to poll a submission resource.

    Here's how you can fetch the submission resource to check the status attributes:

    Track the return submission status

    import requests
    
    ### Replace these variables with your own data! ###
    client_id = 'YOUR CLIENT ID HERE'
    client_secret = 'YOUR CLIENT SECRET HERE'
    direct_debit_id = 'A VALID DIRECT DEBIT ID HERE'
    return_id = 'A VALID RETURN ID HERE'
    submission_id = 'A VALID SUBMISSION ID HERE'
    
    base_url = 'https://api.staging-form3.tech/v1'
    
    # Obtain authentication token
    print("Obtaining bearer token...")
    auth_payload = "grant_type=client_credentials"
    auth_url = '%s/oauth2/token' % base_url
    auth_headers = {'Content-Type': 'application/x-www-form-urlencoded'}
    auth_request = requests.auth.HTTPBasicAuth(client_id, client_secret)
    
    auth = requests.request('post', auth_url, data=auth_payload, auth=auth_request, headers=auth_headers)
    auth_token = auth.json().get('access_token')
    
    get_subm_url = "%s/transaction/directdebits/%s/returns/%s/submissions/%s" % (base_url, direct_debit_id, return_id, submission_id)
    get_subm_headers = {
        'authorization': "bearer %s" % auth_token,
        'cache-control': "no-cache",
        }
    
    get_subm = requests.request("GET", get_subm_url, headers=get_subm_headers)
    
    print(get_subm.text)
    


    You now know how to send a Bacs Direct Debit return. See our other tutorials to learn more about: