Using the API (with FAQs)

For Direct Debit Collections

Once set up with access to Sandbox, you will be able start looking at integrating with the Modulr Direct Debit Collection endpoints.

To arrive at this point we assume you have:

  • Been onboarded as a customer on Sandbox.
    • As part of this have a collection account set up as well as a general account and users set up that can access Direct Debit Collections. For help contact us.
  • Worked out how to securely connect to the Modulr API using the credentials you received in the onboarding process.

📘

Sandbox and Direct Debit collection endpoints

Please note that in the Sandbox environment we do not connect to the Direct Debit scheme, as this is just a test environment. In Sandbox we do offer the ability to use all the endpoints available in our production environment, but some of these need to have data set up by you prior to using them. How to do this is detailed below.

Creating your first mandate in the Sandbox

Once set up, the first logical step is to try to use the POST /accounts/{id}/mandates endpoint to create a mandate. Typically, when you have built your user interface, your app will be using this endpoint to send through the information to Modulr that was entered by your customers in your mandate form.

Please note that reference for each mandate needs to be provided. This will be the reference lodged with BACS scheme.

Reference field requirements are:
-Must be between 6 and 10 characters long, inclusive. May only contain alphanumeric characters.
-Must be unique.
-Only upper case characters are allowed, so any alphabetic characters supplied in this string will be converted to upper case before processing.

Mandate setup form example

1440

First Mandate and collection timings

2000

Direct Debit Mandate Creation

1154

Setting up collections

For the Direct Debit Collections service you create a scheduled collection; you ask if the collection can try to be made on the date you provide. You can ask for a single collection, or multiple. If you ask for multiple, you will need to provide the period, e.g. monthly or weekly.

When you ask for multiple collections, then these need to be for the same amount. If the amount of the collection will be variable, then a new request for a scheduled collection needs to be made. In production every time a new single collection is requested the person you are wanting to get the money from needs to be notified of this new amount; this is something you will need to make sure happens, as it is a rule of the Direct Debit scheme.

For details on all the parameters needed for the POST /mandates/id/collectionschedules endpoint the documentation is here: Create a scheduled collection

Direct Debit Collection Schedules

1154

Monitoring the mandates and collections

You will receive a single payment into your collection account in production for all collections in a day. You will need to know which collections are included in this payment, so you can reconcile against what is expected.

Expecting a payment

There is a GET /collections endpoint which should be used to find out which collections (or the collection activity) to expect in which daily payment and whether there is any other activity - such as any indemnities (where the payer has requested a refund). get collections

Mocking collection activity

Since there are no actual collections on Sandbox, there needs to be some way to test the integration. In order to achieve this we have a Sandbox-only endpoint, POST /external-services-mock/collections, that allows you to add the required collections and then call GET /collections to retrieve the expected collection activity.

An example would be that a request using POST /external-services-mock/collections, such as:

[   
    {
      "activityDate": "2020-06-25",
      "amount": 50.00,
      "collectionScheduleBid": "Q120026P",
      "customerReference" :  "DDI12347",
      "originalActivityDate": "2020-06-25",
      "reconciliationReference" : 14,
      "reconciliationDate" : "2020-06-25",
      "status" : "H",
      "type": "COLLECTION",
      "payerName": "Arakere"
    }
]

Things to note:

The dates in the call should be tomorrow's date, or date for which you will attempt to GET collections. We process mocked collections on daily schedule. I.e. if you create a mock call today, you will be able to retrieve the collections through the GET call tomorrow.

Please note:

  • There can only be 1 collection for a given combination of activityDate & customerReference
  • collectionScheduleBid should be a valid schedule ID ("Q bid"), in a format of Qxxxxxxx
  • customerReference should be a valid mandate customer reference and mandate should be ACTIVE
  • status: Valid statuses are “H” Success, “F” Failed
  • activityDate must be the currentDate, if the GET call has to return the collection

The aforementioned POST request would then produce, when calling GET /collections, the following response:

{
      "activityDate": "2018-01-09",
      "amount": 100,
      "collectionScheduleId": "Q9200001",
      "mandateId": "G0000001",
      "message": "Instruction Cancelled",
      "originalActivityDate": "2021-01-09",
      "payerName": "Mr John Doe",
      "reconciliationDate": "2021-01-09",
      "reconciliationReference": "2021-01-09",
      "status": "FAILED",
      "type": "COLLECTION"
    }

Getting notified of a payment

You should set up an inbound webhook on the collection account. When this webhook is triggered you can check the total of the inbound payment against the amount you expected.


FAQs

📘

What name will appear on the bank statement of the payer?

The client's name - which will also appear on the Direct Debit mandate that is set up

📘

How "real-time" is the process, can the mandate be changed / cancelled at the last minute? If the customer wants to repay in full 1 day early and logs in to make the payment by debit card through the website, can the customer then cancel the direct debit collection that will otherwise remain scheduled for the next day?

The mandate is the overarching contract and would only change if the details of the payer changed. For changing collection schedules, this can be done using the 'cancel collection schedule' endpoint, but after a certain time this cannot be done. This boils down to a 1-3 working day period between the collection being submitted and actually taken from the bank account, during which it can't be reversed.

📘

How are returned direct debits treated?

If there is a collection failure due to any reason (such as insufficient funds), you will typically know this 3 days after the original collection request was submitted / the day after the collection was actually attempted on the customer's bank account.
On rare occasions, you might be made aware of a rejected one more day later. This is referred to as a "late cancellation" and is deemed an exceptional scenario, but one that the BACS scheme allows to happen. The funds of that return will be deducted from the settlement account.

📘

Are there any charges for failed direct debits? Do banks tend to still charge their clients if direct debits fail?

Modulr does not charge for failed collections but there is a fair use policy on this as per the pricing section on this page. Banks may or may not charge a customer for a failed DD, however this is the case in the majority of cases. I personally was charged £25 when a DD bounced as I had moved some savings to the wrong current account.

📘

If a customer cancels a direct debit mandate directly with their bank is the customer notified by the bank in any way when they come to collect the payment?

Yes a message will be returned via Modulr saying the DD mandate has been cancelled.

📘

There is no longer any paperwork involved, this is all automated. Correct?

Absolutely!

📘

What are the timelines of Mandate and Collection creation?

Please see the image above (A Mandate takes 3 working days to set up from the time the API call is posted on the Modulr platform. A collection can happen at the soonest 2 days after requested on the platform. Therefore the first collection can be a minimum of 6 working days from the Mandate request.)

📘

Can we submit Direct Debit requests via file?

That is not a supported method (You can build a UI that enables the upload of a file that then parses it, and then connects to our API if you like, but Modulr will not support the UI)

📘

When are unsuccessful collections due to low funds known about?

The day after the collection date

📘

How do I get notification of cancelled or amended collections?

As part of the activity is response to GET /collections

📘

When are collection funds available in the Modulr collection account?

We credit funds 2 days after collection.

📘

What types of checks are done/guarantees required to be a DD customer?

We already do checks on our clients and the people involved and no further checks are needed to be able to use DD collections. There is a separate onboarding process where your Direct Debit collection experience is verified and a SUN is provided.

📘

What online DD management tools are available?

We have a web based client portal where mandates and collections set up via API can be viewed & reconciled

📘

Can we transfer our current SUN?

We can work with your current provider to transfer ownership of the SUN. If we can't transfer ownership of your existing SUN to Modulr, we can set up one of our own SUNs and migrate your existing Direct Debit Instructions over.

📘

Can our customers use online forms to submit mandates?

Yes, in fact this is the way that is supported by us; you would need to build the pages which would use our API to submit the mandate. These pages need to be approved.

📘

What is the indemnity claim process?

You should contact Modulr customer services (after having found out about the indemnity via API) to challenge the claim. Modulr will then pass on to the Direct Debit scheme.

📘

Do we provide native bank return reason codes?

We include, in the message field in the activity response for GET /collections, the BACS reason - but we do not supply the code.

📘

Is the Direct Debit collection account only able to be used for Direct Debit collections?

Technically the account is a Faster Payments account that has the Direct Debit collection product added to it, and the collection payments are actually Faster Payments. Also payments out would be Faster Payments and can be made as needed. Payments in should be restricted to DD collections as otherwise other payments will confuse any reconciliation. If you need another way to get funds, e.g. for customers to make non DD ad-hoc payments, then you should create other accounts for that purpose (ideally one per one of your customers).

📘

Are custom schedules (different amounts per collection) available?

Yes, but not in the same collection schedule; to collect a different amount you will need to set up a new scheduled collection for each different amount under the same mandate. Alternatively, the collection amount could amended as required ahead of the collection date.

📘

How do you handle retries?

If a collection should fail for certain reasons, the transaction status will be updated to 'REPRESENTABLE. You will then be able to retry the collection using the POST /collections/{id}/represent

📘

When does collection activity get updated?

We get activity updated from at 10:00 every morning.