SEPA Direct Debit

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

SEPA refers to the Single Euro Payments Area - a payment scheme which facilitates cashless payments (bank transfers via credit transfer and direct debit) anywhere inside the European Union.

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

Digital Journeys

Journey DirectDebitNotification

After uploading and importing the data from the Notification file, the user is redirected to the direct debit mandate Registration form. This form has to steps(tabs). In the first tab, the user finds information about the notification file - the name of the file and the import date. In the second tab, the user can see the direct debit mandates buffer activated by that specific notification file.

Journey DirectDebitNotificationInsert

This is a user journey aimed at implementing the Notification Manual Insert functionality. The journey has a form that allows the user to upload a Notification file by pressing the Import Data button.

Journey FTOS_PYMT_DirectDebitMandate

This form is used to see all the details about the direct debit mandates registered, on step 1 and the history of changes logged on the selected mandate, on step 2. Also, the form allows the user to manually select and cancel an Active mandate, by using the Cancel Mandate button.

This form is used to see all the details related to the direct debit mandates from the imported file.

View Default

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

Journey FTOS_PYMT_DirectDebitConfirmationInsert 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_DirectDebitConfirmation form

After uploading and importing the data from the file, the user is redirected to this form which represents the confirmation of registering new direct debit mandate payments in the system. This form has to steps (tabs). In the first tab, the user finds the file confirmation details: the name of the file and the import date. In the second tab, the user has a view of the payments contained by that specific file.

Journey DirectDebitConfirmationDetail _ReadOnly form

This form is used to see all the details about the payments confirmation records from the payments confirmation file.

View Default

This view displays the list of payments confirmation files. From this view, the user can select any file, by double-clicking the DirectDebitConfirmationDetail _ReadOnly form, in order to see the file details.

Journey FTOS_PYMT_DIDEReadOnly form

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

View FTOS_PYMT_DIDEReadOnly

This view displays the list of all the DIDE 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.

On Demand Server Automation Scripts

On demand script that is triggered when a file is uploaded during the DirectDebitNotificationInsert journey. 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 changeMandateBusinessStatus(mandateId) function from FTOS_PYMT_Mandate server side library. The mandateId parameter is passed as null value in order to run the status changes for all the mandates.

Input parameters: N/A.

Output parameters: N/A.

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

Input parameters: N/A.

Output parameters: N/A.

This on demand script calls the changeBusinessStatus function, in order to apply the Cancelled business status to the selected record.

Input parameters:

recordID - Where the recordID is the mandateId. This parameter is passed from the context of the client-side process that called this script.

statusID = cancelled - The value to be set for the mandate business status.

Output parameters: N/A.

Business Workflow Configuration Actions

FTOS_PYMT_DirectDebitMandate is the master business workflow that handles the different types of changes affecting a direct debit mandate during its lifetime. For more details about the mandate behavior, its states and the business workflow diagram consult the Direct Debit page.

Transition Description
_Proposal Initial state.
Active_Cancelled When the system registers a notification about the mandate cancellation.
Active_Expired When the mandate reaches its end day. 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. Used for mandate versioning.
Approved_Active When the mandate reaches its start day.
Approved_Draft When a change of the policy payment type from Bank Transfer (OP) into Direct Debit is performed on a policy.
Approved_Expired When the number of days for the activation of a mandate were exhausted.
Draft_Active When the mandate reaches its start day.
This transition is triggered automatically by a specific job that verifies if the current date is the mandate begin date and changes the status to Active for all eligible mandates.
Draft_Cancelled When the system registers a notification about the mandate cancellation.
Draft_Expired When the number of days for the activation of a mandate were exhausted. The expiration triggers the automatic change of the payment type on the policy, from Direct Debit to Bank Transfer (OP).
Draft_Pending After the instruction file for the mandate's activation is generated, and the mandate is pending approval from the bank.
Draft_VersionDraft When the mandate versioning process starts.
Pending_Active When the mandate reaches its start day.
Pending_Cancelled When the system registers a notification about canceling the mandate, or a user manually cancels the mandate.
Proposal_Active When the mandate reaches its start day.
Proposal_Draft When the mandate is registered in the system but it is not activated yet, or its begin date is yet to come.
Proposal_Expired When the number of days for the activation of a draft mandate were exhausted.
VersionDraft_Approved When a version of the mandate is approved. Used for mandate versioning.
VersionDraft_VersionUnapproved When the opened version is not approved. Used for mandate versioning.
HINT  
To check out this business workflow open the Innovation Studio and go to Fintech Automation >> Business Workflow Designer. For more details, consult also the Business Workflow Design documentation.

Endpoints

FTOS_PYMT_DirectDebitMandate_cancelMandate

This endpoint calls the FTOS_PYMT_DirectDebitMandate_cancelMandate script to change the mandate business status into Cancelled, when clicking the Cancel Mandate button.

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.

Sequencers

FTOS_PYMT_DIDE sequencer

This sequencer is used to set the Order Number value used for generating DIDE instruction files.

  • Range Min = 1

  • Range Max = 999,999,999

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_DirectDebitMandateBuffer entity or interpret data received by it. Inside the PYMT_Buffer function, the following functions are used:

This function updates the directDebitMandateId attribute on a buffer that triggers an action for a mandate (insertion, deletion or modification).

Input parameters:

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

  • mandateId - The Id of the mandate on which the buffer performed the specified 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.

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

Inside the PYMT_Mandate function, the following functions are used:

This function gets the stage of the mandate - that is whether the mandate is N(New), M(Modified) or D(Deleted).

Input parameters: mandateId - The mandate unique identifier.

Output parameters: N/A.

This function updates the mandate business status according to the logic from the getMandateNewBusinessStatus function (see below).

Input parameters: mandateId - The mandate unique identifier.

Output parameters: N/A.

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 Id of the new business status according to the logic between begin date, end date and current date.

Input parameters:

  • beginDate - The beginning date for the mandate.

  • endDate - The ending date for the mandate.

Output parameters: Returns the newBusinessStatusId.

This function returns the mandate details based on the reference.

Input parameters: reference - The mandate reference (expected policy number).

Output parameters: Returns the fetch.

This function updates the mandate business status to Cancelled.

Input parameters:

  • mandateRef - The mandate reference (expected policy number).

  • stageId - The mandate stage.

Output parameters: N/A.

This function returns the Id of the currency based on the code.

Input parameters: currencyCode - The currency code.

Output parameters: The currencyId or null.

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 updateBufferMandateId function to update the directDebitMandateId attribute 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.

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

This function receives a date in a string format. Next, the function converts the date to a date object, with the correct server time.

Input parameters: date - The string containing a date.

Output parameters: dateWithOffset - The date object.

This function executes the following:

  • It inserts a new mandate record, filling in with the data received from the buffer.

  • It also calls the updateBufferMandateId function to update the directDebitMandateId attribute of the buffer.

  • If a mandate with the same reference from the data object already exists in the system, the function throws an error.

Input parameters: bufferObj - The object containing the data added in the buffer.

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

This function fetches from the FTOS_PYMT_DirectDebitMandate entity the Id of the last version for a specified mandate.

Input parameters: mandateId - The Id of the mandate for which the last version was requested.

Output parameters: buffers - The mandate list that has been found.

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.

  • Changes the business status of the new version, depending on the beginDate and endDate attributes.

  • Changes the business status of the old version of the mandate with the versionClosed status.

  • Calls the updateBufferMandateId function to update the directDebitMandateId attribute of the buffer.

Input parameters: bufferObj - The object containing the data added in the buffer.

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

This function changes the business status for SEPA mandates.

Input parameters: N/A.

Output parameters: N/A.

This function changes the business status of the specified mandate.

Input parameters: mandateId - The Id of the mandate.

Output parameters: N/A

This function returns all the SEPA mandates that are in Draft, Active or Expired business status.

Input parameters: N/A.

Output parameters: The query object.

This function gets the details of the specified mandate.

Input parameters: mandateId - The id of the mandate.

Output parameters: The query object.

From the FTOS_PYMT_DirectDebitMandateConfirmation library, the following functions are used:

This function inserts a payment confirmation record into the FTOS_PYMT_DirectDebitMandateConfirmation entity.

Input parameters: input - The object containing details about the new payment confirmation.

Output parameters: directDebitMandateConfirmationId - The Id of the newly inserted payment confirmation.

This function saves the contents of the uploaded payments confirmation file.

Input parameters:

  • fileArr - The object containing the payments confirmation file.

  • confirmationObj - The object containing the Id of the new file inserted and details about the user who performed the insert of the file.

Output parameters: N/A.

Also, inside this function, the following functions are used:

  • getTabularDataFromFile - To get data from the payments confirmation file.

  • saveToTemporaryTable - To save the values in a temporary table called DirectDebitConfirmationTempTable.

The contents of the file are saved with the FTOS_InsertDirectDebitConfirmationDetail stored procedure which returns an array of payments confirmation from the FTOS_PYMT_DirectDebitConfirmationDetail entity.

This server side script library contains methods that help in the process of generating a direct debit payments instruction file for both SEPA and UK types.

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 is specific for DIDE UK. It 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 is specific for DIDE UK. 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 is specific for DIDE UK. 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 is specific for DIDE UK. 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 is specific for DIDE UK. 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 -

  • instructionFileId - The id of the new generated file and entityName - the name of the entity.

Output parameters: N/A

From the FTOS_PYMT_DirectDebitDenied library, the following functions are used.

This function wraps smaller functions which perform actions necessary for the process of importing the payments denied file in the system.

This function updates the status of the mandates found by the getMandateDetailsByReference function to Cancelled.

Input parameters: operationReference - The reference of a mandate.

Output parameters: N/A.

This function fetches the statements (invoices) with the Generated or Unpaid business statuses from a policy, selected by its specific policy number.

Input parameters: policyNo - The number of the policy.

Output parameters: statements - The list of the statements (invoices) found.

This function updates the scheduledDate attribute of a statement (invoice).

Input parameters: policyNo - The number of the policy.

Output parameters: N/A.

This function updates the mandates and the statements (invoices) found based on the operation references received inside an object.

Input parameters: dideDeniedDetails - The object containing the operation references.

Output parameters: N/A.

Scheduled Jobs

This job is scheduled to run every day at 5:00 AM, to update mandate statuses according to the begin date and end date of the mandates.

Schedule Services: FTOS_PYMT_DirectDebitMandateStatusChange - 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.