Generate UK Direct Debit Mandate API

This functionality adds new UK direct debit mandates in the system, based on API requests received from other FintechOS solutions, from other systems or external applications (like digital journeys). On the FTOS_PYMT_GenerateMandate entity, for the newly generated UK direct debit mandate, the API response populates the following attributes: Account Holder First Name, Account Holder Last Name, Bank Sort Code, Account Number, and Reference (the policy number). All mandates are registered in Draft status, with mandateStage =N (new) and Begin Date = null. See more below.

The system registers a new direct debit mandate request, containing details from one policyholder.

Copy 
let inputData = {
    "accountHolderFirstName": "John",
    "accountHolderLastName": "Doe",
    "bankSortCode": "04-00-26",
    "accountNumber": "55743513",
    "reference": "80001033"
}

ebs.callActionByNameAsync('FTOS_PYMT_GenerateMandate', inputData).then(function(e) {
    console.log(e)
});

The following is the list of data parameters included in the request:

Parameter Description
accountHolderFirstName The first name of the payer.
accountHolderLastName The last name of the payer.
bankSortCode Sort code of the bank - it specifies the bank branch.
accountNumber The account number used for the direct debit payment.
reference The policy number.

The following is an example of a response:

Copy 
{
    "isSuccess": true,
    "errorMessage": null,
    "errorCode": null,
    "result": null
}

Response description:

Key Description
errorCode Error code.
isSuccess Marks weather the request is successful or not.
errorMessage Error message.

result

An object containing the following key: mandateId - the Id of the newly generated mandate OR a confirmation message, when a mandate for the input reference already exists. If so, the following message is displayed: "There is already a mandate with the reference number... (x)... for addition!" (The message also includes the specific mandate reference number.)

The following are the error messages that can be encountered during the API invoice generation process:

Code Text Description
ERR.BL.50201 The input parameters keys are wrong or missing! inputData doesn’t have all the properties or some properties are wrong.
ERR.BL.50202 There are no input parameters! This error appears when provided empty data.
ERR.BL.50103 The input parameters should not contain null or empty values! inputData has properties with null or empty values.

The FTOS_PYMT_GenerateMandate endpoint is used to run the FTOS_PYMT_GenerateMandate server automation script.

FTOS_PYMT_GenerateMandate - Script called with a data object.

This script calls the BillingCollectionAPIs library and, also, executes the following:

  • Validates the request data object.

  • If all the necessary conditions are met, it uses the input parameters to generate a new direct debit mandate.

From the BillingCollectionAPIs library, the GenerateDIDEMandate function is used. This function wraps all the functions from bellow:

This function validates the request fields.

Input parameters: inputData - The object containing the keys needed to call the endpoint.

Output parameters - An object containing the keys to describe the result of the validation:

  • isSuccess - true/ false.

  • errorMessage - null or error message as described in the error messages list.

  • errorCode - null or error code as described in the error messages list.

  • result = [] - An array containing the result of the request.

This function inserts the data from the inputData object into FTOS_PYMT_DirectDebitMandateBuffer entity and calls the function performActionsOnMandate from the PYMT_Mandate library which adds a new direct debit mandate into the FTOS_PYMT_DirectDebitMandate entity.

Input parameters: inputaData - An object containing the keys needed to call the endpoint.

Output parameters: result - An object containing the following key: mandateId - the Id of the newly generated mandate OR a confirmation message, when a mandate for the input reference already exists. If so, the following message is displayed: "There is already a mandate with the reference number... (x)... for addition!" (The message also includes the specific mandate reference number.)