Skip to main content

Configuring SmartDebit

The SmartDebit extension is part of the Bacs for FinDock package and supports collecting one-time and recurring payments using the FinDock Payment API and SmartDebit, an experienced and respected provider of Bacs Direct Debit services in the UK.

Multi-merchantMulti-currency
yesyes
Payment MethodOne-timeRecurringRefunds
BACS Direct Debityesyes--

Prerequisites

  • FinDock is installed and configured.
  • A working connection to ProcessingHub and WebHub.

Install and activate Bacs extension#

Follow the standard procedure for installing and activating the Bacs for FinDock extension.

Create a SmartDebit target#

To complete the SmartDebit configuration, you need to add at least one SmartDebit target (account).

To make creating targets easier, we recommend gathering the required details before you start creating targets. The following table includes all the settings for a SmartDebit target.

SettingDescription
NameThe name of the target should be something that is recognizable within your organization. This name is not shown outside of your organization, but it is used to distinguish easily among different accounts.
TargetThe payment extension to be used with this target. For Bacs targets, select PaymentHub Bacs.’
TypeThis is the Bacs implementation to be used with this target. The type affects which settings are needed for the target and how the target is used.
Collection file lead timeThe lead time between submission and processing of collection files; contact SmartDebit for this information.
DDI Lead timeThe lead time between submission and activation of your DDIs; contact SmartDebit for this information.
EndpointThe API endpoint for SmartDebit; value depends on whether you are using a sandbox or production environment from SmartDebit.
Initial Report DateThe first date the Bacs reports should be fetched from SmartDebit, typically this coincides with your go-live date.
DDIs per payer fileLimits the number of DDIs in a single payer or AUDDIS file.
Transactions per Collection fileLimit the number of transactions per collection file
Password, Service User & UsernameThese details are provided by SmartDebit and authenticate calls to the SmartDebit API.

To create a SmartDebit target:

  1. Launch the FinDock app and select Setup.
  2. Click the ProcessingHub tile to open up the ProcessingHub setup page.
  3. Click on the Targets tab and click Add Target to create a new target.
  4. Add the name for the new target, select ‘PaymentHub BACS’ for Target, and for type, select SMARTDEBIT.
    New SmartDebit target
  5. Once you select Type, you are taken to the target settings window where you can fill in the rest of the settings and click Save. New SmartDebit taget settings
  6. If you need to change the settings later, you can go back to the Targets tab, click the button to the right of the target and select Settings.
    Edit existing taget settings
  7. Repeat steps 1-5 for each new account.

Register Bacs mandates for SmartDebit#

The Bacs Direct Debit scheme requires you to register a DDI with your bank or service bureau before it can be used to collect direct debits. This process is supported in FinDock through the Mandate Schedule object.

The Bacs extension generates mandates as Direct Debit Instructions (DDIs) when required, such as for direct debit collection runs. The prefix as set in the FinDock mandate settings is combined with the customer’s bank account for the DDI record to create a unique mandate reference.

FinDock uses the Automated Direct Debit Instruction Service (AUDDIS) service to register DDIs with SmartDebit. Conversion of non-AUDDIS to AUDDIS DDIs is not supported by FinDock. If you have a non-AUDDIS DDI, you need to either convert it using an external service or create a new DDI through FinDock and register it as normal.

Schedule mandate creation#

To use the Mandate schedule for the registration process, you need to first add the Generate Mandates button component to the page layout of Mandate Schedule. Follow the standard Salesforce procedure to modify the Lighting page layout.

To create a new DDI registration file:

  1. In Findock, click the Mandate Schedules tab.
  2. Click New to create a new schedule record.
    New mandate schedule
  3. On the Mandate Schedule Detail page, enter your Bacs target and a processing date (date when the mandates should be active, taking DDI lead time into account).
  4. Set the status to ‘Scheduled’ and click Save. The detail page is refreshed with the values you entered.
  5. On the detail page of the mandate schedule, go to the buttons list at the right top of the page and click Generate Mandates.
  6. A success message is displayed and a Salesforce job is started in the background to select Bacs mandates that are pending registration.
    New mandate schedule generated
  7. After the job is finished, the mandate schedule status is set to ‘Generated.’

Once the mandate schedule status changes to ‘Generated,’ you can either validate first and then create the DDI files, or you can immediately create the DDI file.

Validate mandates#

To validate the mandates first, update the status of the mandate schedule to ‘Validate Mandates.’ This tells FinDock to first validate all the associated mandates and confirm the mandates are complete according to the criteria outlined in the following table.

You can also skip this step and set the mandate schedule status manually to ‘Process.’ Potential errors will be caught later and will still block the DDI registration.

FieldCriteriumError message
Mandate IdMust be > 6 and \< 18 alphanumerical characters. If the Target sub type = SmartDebit the mandateID must be of length 7.Mandate ID must be between 6 and 18 characters
Mandate IdAfter taking out nonalphanumeric characters should not contain only the same characters. (see example 2).Mandate ID must not contain only the same characters.
Mandate IdShould not contain “/”Mandate ID contains \/
Contact > Last nameContains at least 3 characters.Lastname must contain at least 3 characters
Contact > First Namenot empty, not spaces onlyFirst name cannot be empty
Contact > Address Linenot empty, not spaces onlyAddress line cannot be empty
Contact > Citynot empty, not spaces onlyCity cannot be empty
Contact > Post codenot empty, not spaces onlyPost code cannot be empty
Payment Profile > Sort codeLength 6Sort code must be 6 digits (and thus may not be empty)
Payment Profile > Sort codeOnly digitsSort code can only contain digits 0:9
Payment Profile > Account numberLength 8Account number must be 8 digits
Payment Profile > Account numberOnly digitsAccount number can only contain digits 0:9
TargetMust have a BACS targetMandate does not contain a valid target
StatusAllowed values are: “Pending registration” “Pending validation” “Pending update”Invalid mandate state
Payment Profile > Holdernamenot empty, not spaces onlyHoldername cannot be empty

If a mandate fails validation, the status of the mandate is set to ‘Failed,’ and the error(s) is added to the field Last Status Reason.

If no errors are found, FinDock automatically progresses to the file creation stage.

Create and send AUDDIS file#

The DDI file creation is triggered when the mandate schedule status changes to ‘Process.’ This initiates an outbound message which uploads the new DDIs directly to SmartDebit in an AUDDIS file.

Once ProcessingHub has generated the file, it is uploaded to Chatter, and a PaymentHub File record is created to track the status of the generated file.

The mandate schedule, in turn, is updated to ‘Pending Verification.’ Mandate schedule pending verification

Under Related on the mandate schedule, you will find a list of the DDIs that have been included in the Standard 18 file. Mandate schedule related mandates

SmartDebit scheduled Apex#

For SmartDebit, there is a scheduled job which automatically kicks off the DDI registration process. This automatic flow skips validation and registers any DDI directly with SmartDebit.

To enable this job:

  1. Open Salesforce Setup, in the quick find box enter "Apex Classes" and click on "Apex Classes" in the search results.
  2. On that page click Schedule Apex.
    SmartDebit Apex Class
  3. Next, give the job a recognizable name like “DDI Registration.”
  4. For the Apex Class, enter: "RegisterDDISchedule."
  5. Set the job to run every day of the week at a time of your choosing. It is recommended to do this in the evening as this ensures all new DDIs for that day will be included as soon as possible.
    SmartDebit schedule Apex Class
  6. Click Save to store the schedule.

Every day at the designated time, FinDock will create a mandate schedule for every SmartDebit target in your org, select the relevant mandates, and register them with SmartDebit.

If any mandate fails, the individual mandate record is marked with status "Failed." Make sure to review and correct these so they are not constantly failing.

Installment aggregation#

The Bacs Direct Debit scheme does not allow multiple transactions for the same mandate on the same date. If you have transactions like this, FinDock automatically aggregates to a single direct debit installment all transactions for each mandate-date combination.

Aggregation process#

After a payment schedule run for a Bacs target has generated and/or selected installments that meet the schedule’s criteria, FinDock checks if there are installments with the same mandate-date combination.

If such installments are found:

  1. An aggregated installment is created with an open amount equal to the sum of the open amounts of the individual installments.
  2. The payment method of the individual installments is set to Aggregated Installment.
  3. The individual installments are linked to the aggregated installment.
  4. The original installments are removed from the payment schedule.

Collection and payment#

If a payment is received for the aggregated installment, it is split and distributed to the original individual installment. Both the aggregated installment and linked individual installments are set to Collected, and all open amounts are set to zero. In addition, a corresponding negative payment is created for the aggregated installment to keep the sum of all payments equal to the actual direct debit payment amount.

Reversal#

If an aggregated installment is reversed, a negative payment is created and distributed across the original individual installments. The status of these installments is set to Reversed, and the open amount is set to the original value.

The payment method of the original installments is set back to direct debit, allowing them to be recollected. The for the Aggregated Installment positive payment is created in order to keep the sum of all Payments equal to the actual money flow.

Important notes#

  • Keep in mind when confirming the direct debit to the customer or donor that you mention the total amount rather than the amount of the single transaction.
  • Aggregated installments are not eligible for Gift Aid since they are not separate payments or donations.
  • In order to keep your reports in line with actual expected and/or realized cash flow, exclude aggregated installments from your reports. Use the field paybacs__IsAggregated__c to filter out installments that are aggregated installments.
  • For the same reporting reasons, NPSP Opportunities are not created for an aggregated installment.
  • Do not recollect Aggregated installments after a reversal, but recollect the Original Installments.

Match with Bacs processing date#

As part of the Bacs package a new field ‘Bacs processing date’ (paybacs__BACS_Processing_Date__c) is added to the Payment Schedule. You can enter a value in this field if you want to match incoming Bacs reports based on the Bacs processing date instead of the collection date noted on the payment schedule.

When a Bacs report is uploaded to ProcessingHub (via Chatter), the records in that file are matched against installments in the system. If a value is provided in the field ‘Bacs processing date’ on a payment schedule, then FinDock matches incoming Bacs reports on that.

Payment API#

To test your SmartDebit configuration, you can use the following messages with the Payment API.

One-time Bacs direct debit#

{
"SuccessURL": "https://www.example.com/success",
"FailureURL": "https://www.example.com/error",
"WebhookURL" : "https://webhook.site/181568ec-8830-4672-af01-8c99da8e044f",
"Payer": {
"Contact": {
"SalesforceFields": {
"FirstName": "Eric",
"LastName": "Johnson",
"Email": "eric@johnson.com"
}
}
},
"OneTime": {
"Amount": "30"
},
"PaymentMethod": {
"Name": "Direct Debit",
"Processor": "PaymentHub-BACS",
"Target" : "BACS-target",
"Parameters" : {
"bankAccount" : "13537846",
"sortCode": "205132",
"holderName" : "E. Johnson",
"description": "test"
}
},
"Settings": {
"SourceConnector": "PaymentHub"
}
}

Recurring Bacs direct debit#

{
"SuccessURL": "https://www.example.com/success",
"FailureURL": "https://www.example.com/error",
"Payer": {
"Contact": {
"SalesforceFields": {
"FirstName": "Eric",
"LastName": "Johnson",
"Email": "eric@johnson.com"
}
}
},
"Recurring": {
"Amount": "25",
"Frequency": "Monthly",
"StartDate": "2020-11-01"
},
"PaymentMethod": {
"Name": "Direct Debit",
"Processor": "PaymentHub-BACS",
"Target" : "BACS-target",
"Parameters" : {
"bankAccount" : "13537846",
"sortCode": "205132",
"holderName" : "E. Johnson",
"description": "test"
}
},
"Settings": {
"SourceConnector": "PaymentHub"
}
}