UK Direct Debit

This functionality handles the direct debit payment operations for UK area.

Below are the journeys, entities, libraries and scripts related to this functionality:

Digital Journeys

Journey DirectDebitADDACS

After importing the data from the ADDACS file, the user is redirected to this form. This form has to steps (tabs). In the first tab, the user finds information about the ADDACS file - the name of the file and the import date. In the second tab, the user can see the direct debit mandates details contained by that specific ADDACS file.

The form also allows the user to make changes related to the business status of the direct debit mandates. According to the updates received through the ADDACS file, the user can cancel, modify or reactivate existing mandates. However, these modifications can only be performed if the effective date of the record is equal with import date of the file.

NOTE  
The generation of a new UK direct debit mandate can be done only through FTOS_PYMT_GenerateMandate endpoint which is described in the Generate UK Direct Debit Mandate API page.

Journey DirectDebitADDACSInsert

This form is used to manually upload an ADDACS file, by pressing the Import Data upload button.

Journey FTOS_PYMT_DirectDebitMandate_UK

This form is used to see all the details about the UK direct debit mandates registered - on step 1 and the history of changes for a mandate - on step 2.

This form is used to see all the details related to the direct debit mandates from the imported ADDACS file. On this page, this entity is further called buffer.

View FTOS_PYMT_DIDEReadOnly

This view displays the list of all the DIDE UK payments instruction files generated by the FTOS_PYMT_DIDEInstructionFile scheduled job. From this view, the user can select any file, by double-clicking the FTOS_PYMT_DIDEReadOnly form, in order to see the file details.

Journey FTOS_PYMT_DIDEReadOnly form

This form displays the details (file name and date of generation) of the DIDE UK payments instruction files generated by the FTOS_PYMT_DIDEInstructionFile scheduled job. Also, from this form the user can download the generated file.

View Default

This view allows the user to see the list of all the UK direct debit payments files ever uploaded in the system. From this view, the user double-clicks the FTOS_PYMT_ARUDD form in order to see the details of the selected record.

Journey FTOS_PYMT_ARUDDInsert form

This insert form allows the user to manually upload a file containing direct debit payments (not confirmed yet) by pressing the Import Data upload button.

Journey FTOS_PYMT_ARUDD form

After uploading and importing the data from the ARUDD file, the user will be redirected to this form which represents the registration of the unconfirmed payments of direct debit mandates.

This form has to steps (tabs). In the first tab, the user finds the file confirmation details: the name of the ARUDD file and the import date. In the second tab, the user has a view of the payments contained by that specific ARUDD file.

View Default

This view displays the list with some details for all the records from the unconfirmed payments file (the ARUDD file). From this view, the user double-clicks the FTOS_PYMT_ARUDDDetail_ReadOnly form in order to see the details of the selected record.

Journey FTOS_PYMT_ARUDDDetail_ReadOnly form

This form is used to see all the details about the unconfirmed payments from the ARUDD file.

View default

This view displays the list of all the DIDE UK mandate instruction files generated by the DIDEUK_Instructions scheduled job. From this view, the user double-clicks the FTOS_PYMT_DIDEMandateInstructionReadOnly form in order to see the details of the selected record.

Journey FTOS_PYMT_DIDEMandateInstructionReadOnly form

This form displays the details (file name and date of generation) of the DIDE UK mandate instruction files generated by the DIDEUK_Instructions scheduled job. Also, from this form the user can download the generated file.

On Demand Scripts

On demand script that is triggered when a file is uploaded during either of the FTOS_PYMT_ARUDDInsert or DirectDebitADDACSInsert journeys. After the user presses the Import Data button, the script validates that the file is in .txt format. The script also restricts the upload to only one file.

Input parameters: file - The DIDE payments file that needs to be uploaded.

Output parameters: fileValidation (boolean) - The result of the validation (true/ false).

This on demand script calls the runDIDEInstructionFileUK() function from the FTOS_PYMT_DIDE server side script library, in order to generate the payments instructions file for direct debit payments.

Input parameters: N/A

Output parameters: N/A

This on demand script calls the processUKMandates function from FTOS_PYMT_Mandate server side library in order to run different status changes for the mandates, according to the received updates. The following actions can be performed on the existing mandates: canceling, modifying or reactivating.

Input parameters: N/A.

Output parameters: N/A.

This on demand script calls the runDIDEInstructionFileUK function from the FTOS_PYMT_DIDE server side script library, in order to generate the payment instructions file for the UK direct debit mandates.

Input parameters: mandates - A string containing the file type.

Output parameters: N/A.

Business Workflow Configuration Actions

Business Workflow: FTOS_PYMT_DirectDebitMandate

Transition Description
_proposal The initial status of any mandate issued in the system.
active_cancelled The transition to this status is made according to the 0, 1, 2, 3, B, C Reason Codes. These values, received in the ADDACS file, are specific for mandates deletion.
active_expired When the current date passed the end date of the mandate. The expiration triggers the automatic change of the payment type on the policy, from Direct Debit to Bank Transfer (OP).
active_versionClosed When a version of the mandate is closed.
approved_active When a version of the mandate is approved and the current date is the begin date or is passed the begin date, already.
approved_draft When a new mandate version is created.
approved_expired When the current date passed the end date of the mandate. The expiration triggers the automatic change of the payment type on the policy, from Direct Debit to Bank Transfer (OP).

cancelled_active

The transition to this status is made according to the R Reason Code. The R value, received in the ADDACS file, is specific for mandates reactivation.

draft_active When the current date is the begin date.
This transition is triggered by the DIDEUK_Instructions job, which verifies if the current date is the mandate begin date and changes the status to Active for all eligible mandates.
draft_cancelled The transition to this status is made according to the 0, 1, 2, 3, B, C Reason Codes. These values, received in the ADDACS file, are specific for mandates deletion.
draft_expired When the current date passed the end date of the mandate. The expiration triggers the automatic change of the payment type on the policy, from Direct Debit to Bank Transfer (OP).
draft_versionDraft When the users initiates the mandate versioning process.
proposal_active  
proposal_draft When the direct debit mandate is registered in the system but its begin date is greater than the current date.
proposal_expired  
versionDraft_approved When a version of the mandate is approved.
versionDraft_versionUnapproved When a version of the mandate is not approved.

Endpoints

The FTOS_PYMT_GenerateMandate endpoint calls the FTOS_PYMT_GenerateMandate on demand script in order to generate a new UK direct debit mandate. This endpoint is described in the Generate UK Direct Debit Mandate API page.

Processors

The FTOS_PYMT_DIDEProcessor is used for setting the following parameters:

This is an object containing the following settings:

  • numberOfDaysInAdvance - This parameter sets the date for invoice generation with N days before the payment due date (for example, the invoice can be generated with 3 or 5 or 10 days before the payment due date).

  • runningOnBankHolidays - This parameter determines whether the DIDE instruction file is generated on bank holidays or not (true or false). Set to true if the DIDE instruction file is to be generated on a bank holiday.

  • excludeWeekDays - This parameter defines the week days in which the DIDE instruction file is not generated (for example, the invoice is not generated on Saturday or Sunday).

  • type - This parameter sets the type of direct debit processing: either SEPA (for European area) or UK.

If the type option configured in the processor is Sepa - the DIDE process will take in consideration the functionality implemented for DIDE Sepa. Otherwise, the DIDE process will take into consideration the flow implemented for DIDE UK.

This is an object containing static values for the UK DD Payments Instruction File. The values are:

  • destinationSort - Destination sort

  • destinationAcct - Destination acct

  • destinationType - Destination type

  • usersName - Users name

This is an object containing static values for the DD Mandate Instructions file. The values are:

  • destinationSort - Destination sort

  • destinationAcct - Destination acct

  • destinationType - Destination type

  • transaction - Transaction

  • freeFormat - Free Format

  • amount - Amount

  • usersName - Users name

Below is an example of processor settings:

Processor Example

Server Side Script Libraries

From the FTOS_PYMT_Mandate library, the following functions are used:

This function wraps a series of functions which perform actions on the FTOS_PYMT_DIDE_ADDACSDetail entity or interpret data received by it. Inside the PYMT_Buffer function, the following functions are used:

This function updates the directDebitMandateId processed attributes on a buffer that triggered an action for a mandate (deletion, modification or reactivation).

Input parameters:

  • bufferId - The Id of the buffer on which the update needs to be made.

  • mandateId - The Id of the mandate on which the buffer performed an action.

Output parameters: N/A.

This function detects the type of action that the buffer needs to perform on a mandate, based on the stageId that the buffer has. If there is no stageId set on the buffer, the function throws an exception, with an error message.

Input parameters:

  • bufferObj - The object containing the data added in the buffer.

  • isJob - (boolean) - Tells whether the function is called by a job or not.

Output parameters: mandateId - The Id of the mandate which was modified, cancelled, or reactivated.

Inside the PYMT_Mandate function, the following functions are used:

This function updates the mandate business status.

Input parameters:

  • mandateId - The mandate unique identifier.

  • statusId - The business status unique identifier.

Output parameters: N/A.

This function returns the mandate details based on reference or account holder name and account number.

Input parameters: bufferObj - The object containing the following attributes reference, or accountHolder and accountNumber.

Output parameters: Returns the fetch.

This function returns the reason code details from FTOS_PYMT_ADDACSReasonType entity based on the reason code received as input.

Input parameters: reasonCode - The reason code (0, 1, 2, 3, B, C, D, E, R).

Output parameters: Returns the fetch.

This function makes status changes (canceling, modifying or reactivating) on the existing mandates.

Input parameters: N/A.

Output parameters: N/A.

This function executes the following:

  • It updates the business status of the mandate to Cancelled.

  • It updates the stageId attribute to the one received from the buffer.

  • It calls the updateUKBufferMandateId function to update the directDebitMandateId and processed attributes of the buffer.

  • If no mandate is found based on the reference, the function throws an error.

Input parameters:

  • bufferObj - The object containing the data added in the buffer.

  • isJob - (boolean) - Tells whether the function is called by a job or not.

Output parameters: mandateId - The Id of the cancelled mandate.

This function executes the following:

  • It inserts a new mandate record, with the data received from the FTOS_PYMT_GenerateMandate endpoint.

  • If there is already a mandate with the same reference from the data object, the function throws an error.

  • It calls the updateUKBufferMandateId function to update the directDebitMandateId and processed attributes of the buffer.

Input parameters: bufferObj - The object containing the data received from FTOS_PYMT_GenerateMandate endpoint.

Output parameters: mandateId - The Id of the mandate which was created.

This function executes the following:

  • Creates a new version for a mandate with a specific reference.

  • Updates the mandate with the new data received from the buffer.

  • If no mandate is found having the same reference as the one received from the data object, the function throws an error.

  • After the insert and update, the function updates the business status of the old mandate version to versionClosed.

  • Calls the updateUKBufferMandateId function to update the directDebitMandateId and processed attributes of the buffer.

Input parameters:

  • bufferObj - The object containing the data added in the buffer.

  • isJob - (boolean) - Tells whether the function is called by a job or not.

Output parameters: mandateId - The Id of the modified mandate.

This function executes the following:

  • Reactivates a cancelled mandate based on a specific reference, received through the buffer object.

  • If no cancelled mandate or no mandate is found having the same reference as the one received from the data object, the function throws an error.

  • Calls the updateUKBufferMandateId function to update the directDebitMandateId and processed attributes of the buffer.

Input parameters:

  • bufferObj - The object containing the data added in the buffer.

  • isJob - (boolean) - Tells whether the function is called by a job or not.

Output parameters: mandateId - The Id of the modified mandate.

This function sets the Id of all three business statuses that the function needs. Next, by calling the updateFileMandateId() function, we update the directDebitMandateId attribute of the buffer records. Next, the function checks if the found mandate is in one of the two statuses - either Pending or Active, and changes its business status to cancelled.

Input parameters:

  • bufferObj - The object containing the data added in the buffer.

  • fileType - The type of the file that has been imported.

Output parameters: N/A

For a policy reference received as parameter, this function returns the statement in Generated or On Grace status and verifies if the payment method is set to direct debit.

Input parameters: policyNo - The policy number (string).

Output parameters: The result of the query.

From the FTOS_PYMT_DIDE library, the following functions are used:

Inside the General() function, the following functions are used:

This function verifies if an input value is null or empty.

Input parameters: value - The value that needs validation.

Output parameters:true/ false - The result of the validation.

This functions transforms the format of an input date to the ddmmyy format. Next, it adds a number of days to the received date.

Input parameters:

date

noOfDays - How many days to add to the date received as an input.

Output parameters: Date formated.

This function returns the static values stored in the FTOS_PYMT_DIDEProcessor processor.

Input parameters: setting - The processor’s object key name.

Output parameters: The object containing values from the processor:

  • destinationSort

  • destinationAcct

  • destinationType

  • usersName

  • transaction

  • freeFormat

  • amount

This function wraps a series of functions which perform actions on the FTOS_PYMT_DIDE and FTOS_PYMT_DIDEDetail entities, generate and validate some data or generate .txt files, as follows:

This function executes the following:

  • Verifies that the DIDE instruction file can be generated according the rules defined in the FTOS_PYMT_DIDEProcessor processor (runningOnBankHolidays, numberOfDaysInAdvance, and excludeWeekDays).

  • Generates the details needed for the file type wanted.

  • Saves the statementId and directDebitMandateId details into the FTOS_PYMT_DIDEDetail entity.

  • Saves the directDebitMandateId details in FTOS_PYMT_DIDEMandateInstructionDetail entity, according to the file type.

  • Generates the .txt file.

  • Saves the file into the FTOS_PYMT_DIDE entity or into the FTOS_PYMT_DIDEMandateInstruction entity.

  • It also saves the file on the server UploadEBS folder.

This function also uses all the functions mentioned below.

Input parameters: instructionFileType - Optional parameter. This parameter has two possible values:

  1. statements - for files dealing with payments - DIDEPaymentsInstructionFile (for SEPA) and, respectively, DD_BACSPayments file (for UK).

  2. mandates - for files dealing with creation of new DIDE mandates - NEW_DIDE_Mandates_BACSInstructions file (for UK).

Output parameters: N/A.

This function gets the configuration details of a processor.

Input parameters:

  • flowSettingsName - The name of the flow setting.

  • processorSettingsType - The type of the Digital Processor Type.

  • processorSettingsName - The name of the processor setting.

Output parameters: processorDetails - An object containing the processor settings runningOnBankHolidays, excludeWeekDays and numberOfDaysInAdvance.

This function returns the name of a weekday (ex. Monday).

Input parameters: date - The date parameter.

Output parameters: dayName - The name of the week day.

This function verifies if the current day is a bank holiday or a day defined in the FTOS_PYMT_DIDEProcessor. If one condition is meet the function returns a true value.

Input parameters: settings - The object with the processor settings - runningOnBankHolidays, excludeWeekDays and numberOfDaysInAdvance.

Output parameters: True or false.

This function returns all the UK direct debit mandates in Draft status.

Input parameters: mandateTypeUk - The mandateTypeId has the UK value.

Output parameters: Returns the query result.

This function imports the FTOS_PYMT_GetPolicyDataAPI library in order to call the FTOS_GetPolicyData_API API. The function sends an object containing a list of policies as mandates references (where the reference is the policy number) and receives the information about the specified policies, in return. This function also parses the result.

Input parameters: mandateObj - The list of policies.

Output parameters: Information result about the specified policies.

This function returns statements (invoices) to be included in the DIDE instruction file, based on the following conditions:

  • businessStatus of the statement = Generated

  • paymentType of the statement = directDebit

  • businessStatus of the direct debit mandate = active

  • scheduledDate of the statement = null

  • dueDate of the statement <= current date + numberOfDaysInAdvance

  • businessStatus of the policy = Enforced or Suspended

  • mandateTypeId = SEPA or UK

Input parameters:

  • numberOfDaysInAdvance - The number of days in advance for generating an invoice (for a policy installment), before the due date for the payment.

  • mandateTypeId = SEPA or UK

Output parameters: resultStatements - Returns the fetch.

This function is specific for SEPA direct debit. This function executes the following:

  • Inspects the results of the getStatementsDetails function.

  • Inserts the statementId, directDebitMandateId, and name details into the FTOS_PYMT_DIDEDetail entity.

  • Populates the CSVContentArray with all the details necessary for the generation of the DIDE instruction file.

  • Updates the scheduledDate from the FTOS_PYMT_Statement entity.

Input parameters:

  • result - The fetch result of the getStatementsDetails (numberOfDaysInAdvance, mandateTypeId) function.

  • CSVContentArray - An empty array.

Output parameters: N/A.

This function executes the following:

  • Inspects the results of the query mandates.

  • Inserts the directDebitMandateId details into the FTOS_PYMT_DIDEMandateInstructionDetail entity.

  • Populates the CSVContentArray with all the details necessary for the generation of the mandate instruction file.

  • Sets the beginDate on the specified mandates.

  • Sets the status on the mandates to Active.

In the CSVContentArray file, the information is concatenated as follows:

  • First column: destination sort + destination acct + destination type + transaction + bank Sort Code + account number.

  • Second column: free format + amount + users name.

  • Third column: reference + payer last name.

  • Fourth column: BACS Processing day.

Input parameters:

  • resultMandates - The mandates that respect all conditions for being included in the file.

  • CSVContentArray - An empty array.

Output parameters: N/A.

This function executes the following:

  • Inspects the results of the getStatementsDetails function.

  • Inserts the statementId, directDebitMandateId, and name details into the FTOS_PYMT_DIDEDetail entity.

  • Populates the CSVContentArray with all the details necessary for the generation of the UK_DIDE instruction file.

  • Updates the scheduledDate from the FTOS_PYMT_Statement entity

In the CSVContentArray file, the information is concatenated as follows:

  • First column: destination sort + destination acct + destination type + transaction + bank Sort Code + account number.

  • Second column: free format.

  • Third column: amount + users name.

  • Fourth column: reference + payer last name.

  • Fifth column: BACS Processing day.

Input parameters:

  • result - The fetch result of the getStatementsDetails (numberOfDaysInAdvance, mandateTypeId) function.

  • CSVContentArray - An empty array.

Output parameters: N/A.

This function returns the installment number for an invoice reference, received as parameter.

Input parameters: statementReference - The invoice reference.

Output parameters: Returns the query result.

This function executes the following:

  • Generates the .txt DIDE instruction file based on csvContentArray populated by the processPaymentsInstruction(result, csvContentArray) function.

  • Saves the file into FTOS_PYMT_DIDE entity.

  • Saves the file on the UploadEBS folder from the portal.

Input parameters:

  • csvContentArray - The array with all the records for direct debit instructions.

  • instructionFileType - Optional parameter, with two possible values: 1. statements for DIDEPaymentsInstructionFile (SEPA) and DD_BACSPayments (UK) file and 2. mandates for NEW_DIDE_Mandates_BACSInstructions file (UK).

Output parameters:

  • idInstructionFile - The Id of the new file inserted in FTOS_PYMT_DIDE entity or FTOS_PYMT_DIDEMandateInstruction entity.

  • entityName - FTOS_PYMT_DIDE - for DIDEPaymentsInstructionFile (SEPA) and DD_BACSPayments (UK) file OR FTOS_PYMT_DIDEMandateInstruction for the NEW_DIDE_Mandates_BACSInstructions file (UK).

This function searches all the records from FTOS_PYMT_DIDEDetail or FTOS_PYMT_DIDEMandateInstructionDetail entities (depending on the file type) which have dideId (id of the file) with nullvalues and updates them with the id of the recently generated file.

Input parameters: instructionFileObj - This object has the following properties:

  • instructionFileId - The id of the new generated file.

  • entityName - The name of the entity.

Output parameters: N/A

This server side script library contains methods that help in the process of generating an ARUDD unconfirmed payments file for UK type. From the FTOS_PYMT_ARUDD library, the ReasonForReturn function is used. Inside theReasonForReturn function, the following generic methods are used:

This function trims, transforms into lowercase and removes the spaces from a string.

Input parameters: text - string

Output parameters: text - formatted string

For the correlated mandates which contain these denied payments with Reason for return code = 1- Instruction cancelled in the file, the function triggers the Cancellation process - making just the transition of the Mandate from Active to Cancelled. The invoices correlated with the mandates which contain denied payments - and changed status to Cancelled, become Cancelled, also.

For the mandates which contain denied payments with Reason for return code = 0 - Refer to payer in the file, the correlated invoices that contain those denied payments become Unpaid, also.

Input parameters: records - The records inserted in FTOS_PYMT_ARUDDDetail.

Output parameters: The query result.

Scheduled Jobs

This job is scheduled to run every day at 5:15 AM, to perform status changes (canceling, modifying or reactivating) on the existing mandates, based on the unprocessed records from the buffer (FTOS_PYMT_DIDE_ADDACS entity).

Schedule Services: FTOS_PYMT_DIDE_ADDACS - on demand server automation script.

The job is scheduled to run every day at 3:00 AM to generate the .txt instruction file. Depending on the configuration, it generates the DIDEPaymentsInstructionFile (for SEPA) and DD_BACSPayments (for UK), also.

Schedule Services: FTOS_PYMT_DIDEInstructionFile - on demand server automation script.

The job is scheduled to run every day at 4:00 AM to generate the .txt DIDE UK mandates instruction file.

Schedule Services: FTOS_DIDEUK_Instructions - on demand server automation script.