Skip to main content

Using SmartDebit

FinDock supports collecting one-time and recurring direct debit payments in the UK using the Bacs Direct Debit scheme through SmartDebit. The role of FinDock is limited to creating payer and collection files and processing Bacs reports. Files and reports are transferred automatically between FinDock and SmartDebit.

SmartDebit vs. FinDock terminology

The following table highlights some key differences between SmartDebit and FinDock terminology.

SmartDebitFinDockExplanation
New payerMandateFinDock stores the new payer authorization to collect direct debits as a Mandate record.
Due dateCollection dateThe pay date communicated to the payer during the DDI sign up and/or in the advance notice. While the due date is not required to be the same as the collection date, in practice FinDock treats them as equal.
New payer fileMandate scheduleFinDock uses mandate schedules to generate and send new payer files to SmartDebit.
Collection filePayment scheduleFinDock uses payment schedules to generate and send collection files to SmartDebit.
CollectionInstallmentThe payment instruction is handled as a DDI transaction in the Bacs scheme. Each individual direct debit payment instruction is an Installment record in FinDock.
N/ADue dateInstallment records have a due date that is populated through different means depending on the context (e.g. recurring opportunity, one-time direct debit, etc.). This field is only used by FinDock internally in the installment selection process when running payment schedules.
Start dateSigned dateThe date a mandate record becomes active. FinDock adds 1 day when the mandate is created and then adds the DDI lead time value to that when a mandate schedule picks up the mandate record for registration.

SmartDebit file flow overview

Whether you are running a mandate schedule to register new payers or a payment schedule to collect payments, the overall flow is the same, as illustrated below.

SmartDebit data flow overview

  1. Payment or mandate schedule run collects and modifies payment data.
  2. Payment data is sent to ProcessingHub.
  3. ProcessingHub transforms data into a CSV file and sends it to SmartDebit.
  4. ProcessingHub regularly polls SmartDebit for Bacs reports.
  5. ProcessingHub parses Bacs reports and creates Inbound Report records.
  6. Inbound reports are matched and unmatched are put into Guided Matching.
  7. Guided Matching reconciles and enriches payment data.

New payer signup

A new payer is defined by a unique Contact and Payment Profile record combination. When a new payer is added to Salesforce, FinDock automatically creates a mandate record with a 7-character Id. The new record is assigned the status Pending Registration.

Sort code and account check

For Bacs Direct Debit payments initiated through the FinDock Payment API, FinDock performs a sort code & bank account check to avoid failed payments due to incorrect code or account values. The checking is done automatically, and the result is included in the synchronous response of the paymentIntent API call. If you are using your own payment form/page design, your need to ensure errors are handled gracefully invalid information is entered.

In addition to the automated API check, you can use the FinDock Lightning component Check Sort Code and Bank Account to your Payment Profile layout to do the same validation when manually entering payment information.

The component appears on payment profiles with UK bank accounts, but it is not visible for other payment profiles. To validate a sort code and bank account, just click the Validate button on the component.

Create new payers in SmartDebit

The new payer creation process is fulfilled using mandate schedules. The mandate schedule process creates the appropriate file and automatically sends the file to SmartDebit. Mandate records with Pending Cancellation or Pending Update are picked up by the mandate schedule for processing in addition to records with status Pending Registration.

Before you create and run a mandate schedule, you need to plan how to handle SmartDebit lead times. Mandate schedule run dates need to account for the lead time for submitting files. The lead time may be in Working Days or Calendar Days.

To create a new payer file:

  1. Create a mandate schedule as normal.
  2. Select your SmartDebit target.
  3. Leave the Processing date empty and click Start Generation.
  4. After the mandate schedule changes to ‘Generated,’ you can open the related list of the mandate schedule to check the selected records.
  5. Use the Mandate Schedule Path to finish processing the schedule.

When the schedule reaches Generated, the automatic mandate validation starts. FinDock checks if the selected mandates are complete according to the criteria outlined in the following table.

FieldCriteriumError message
Mandate IdMust be > 6 and \< 18 alphanumerical characters.Mandate Id must be between 6 and 18 characters
Mandate IdNon-alphanumeric characters must not be the sameMandate 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 Cancellation and Pending UpdateInvalid 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 Last Status Reason field on the mandate.

You can check and fix failed mandates as follows:

  1. Go to the Related tab of the mandate schedule and check for mandates with status Failed.
  2. Fix issues on the mandates (like add address line to Contact) based on the information in the Last Status Reason field.
  3. Put status of fixed mandates from status Failed to their previous status (e.g. Pending Registration).
  4. Go back to the mandate schedule.
  5. Click the Back to Generated button.
  6. Click the Start Validate & Processing button again.

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

Send new payer file and process reports

After you have completed the validation stage, use the mandate schedule path to move to the processing stage. This initiates a process which creates the new payer file and automatically sends it to SmartDebit. ProcessingHub also creates a PaymentHub File record to track the status of the generated file.

The mandate schedule, in turn, is updated to Pending Verification. When SmartDebit accepts the file, the mandate schedule is updated to Verified.

Please refer to Processing Bacs reports for a complete overview of reports that you may receive confirming or rejecting new payer records. ProcessingHub automatically polls SmartDebit for new reports and carries out certain actions. Some actions may require manual intervention.

Once all actions are taken and the mandate records are active (or cancelled), you can go back to the associated mandate schedule and click Closing next to the schedule path. This moves the schedule to Done, and FinDock sets the related mandates to active.

Collect direct debit payments

FinDock uses payment schedules to create and automatically send collection files to SmartDebit. Setting up payment schedules requires careful attention to dates. Whether you are running individual schedules manually or setting up recurring schedules and automated collection, each individual payment schedule has dates that you need to define in a way that fits your SmartDebit contract in terms of lead times and collection file submission frequency.

Payment Schedule fieldDescription
Processing dateLeave empty. This is not used in the collection files sent to SmartDebit.
Collection dateThe collection date needs to take into account your SmartDebit collection file lead time. You can do this be adding the lead time (working days or calendar days) to the schedule rule date to determine the collection date, i.e. Collection date = run date + collection lead time
Selection dateThe selection date tells FinDock which installments should be included in the payment schedule. Open installments with a due date on or before the selection date are included. For SmartDebit, the selection date can, for example, be equal to the collection date.
Run dateThis is the date the schedule process runs and is also the day that the collection file is submitted to SmartDebit.

Installment aggregation

The SmartDebit collection file format does not allow multiple collections (intstallments) for the same payer on the same date. If you have transactions like this in a given payment schedule run, FinDock automatically aggregates them into a single, aggregated direct debit installment that is then added to the collection file.

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 Grouped Installment.
  3. The individual installments are linked to the aggregated installment.
  4. The original installments are removed from the payment schedule.

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.

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 positive payment for the Aggregated Installment is created in order to keep the sum of all payments equal to the actual money flow.

  • 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.
  • 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.

Send collection file and process reports

As with new payer files, once a collection file is sent, you may receive Bacs reports that need to be handled. Please refer to Procsssing Bacs reports for details. ProcessingHub automatically polls SmartDebit for new reports and carries out certain actions.

note

Check ProcessingHub Manager on a regular basis. You should see a fairly steady flow of AutomatedReporting entries. If there is a break or other irregularity, check the reports from your SmartDebit Pulse account to see if something was missed.

Refunds

Refunds are not part of the technical transactions of the Bacs scheme. However, payer indemnity is permanent, so a refund can be requested at any time. This happens between the payer and the paying PSP (the payer’s bank).

If an indemnity claim process results in refunded payments, the paying PSP will issue you a Direct Debit Indemnity Claim (DDIC) report which FinDock automatically processes as explained in Procsssing Bacs reports.

If a payer requests a refund from you directly and you choose to refund the payer outside the Bacs process, you should manually update the associated record(s) in FinDock accordingly.

Example schedule setup

Criteria

  • Notification period (first payment collection lead time): 10 days
  • New payer lead time: 3 working days
  • Collection lead time: 5 working days
  • Target configuration, DDI Lead Time = 0

Recurring donations

  • Build customization to add 10 days to Start Date on new recurring donations

One-time donation

  • Build customization to add 10 days to Due Date

Mandate schedule

  • Recommend running daily
  • Use auto-create to automate mandate schedule runs

Payment schedule

  • Selection date = Collection date
  • Processing date = null
  • Run date: 5 working days before collection date
  • Frequency/automation: depends on SmartDebit contract, but run as frequently as possible (at least twice a month)