Generate Outgoing Payments API

This functionality allows you to add outgoing payment requests in the system, through an API call. Once added, the system automatically populates the referenceNo attribute for the new outgoing payment request, by using a sequencer (OUGP).

When calling the API, the defaultBusinessStatus key is optional. However, if you fill it in, you must also fill in the scheduledDate key. See more details in the Request Data Parameters section, below.

NOTE  
All new requests are registered in Draft status, when no value is sent for the defaultBusinessStatus key.

A user registers a new outgoing payment request in the system:

Copy 
var p  = {
"paymentRequest":{
"paymentNo":"Pay0029.2",
"paymentType":"premiumReturn",
"paymentAmount":500,
"paymentDueDate":"2021-08-20",
"creationDate":"2021-08-20",
"proposedBy":"Jane.Doe",
"currency":"RON",
"scheduledDate":"2021-08-30",
"defaultBusinessStatus": "Approved", // available values: "Proposed", "Approved"
"comments":"This is the payment request."
},
"paymentBeneficiary":{
"beneficiaryType":"payer",
"beneficiaryCategory":"Individual person",
"uniqueID":"2920202020220",
"firstName":"Jane",
"lastName":"Doe",
"name":null,
"iban":"RO69BNKB000100000000000"
},
"payerDetails":{
"payerName":"CompanyName",
"iban":"RO69BNKB000100000000000"
}
} ;
ebs.callActionByNameAsync("FTOS_PYMT_AddOutgoingPaymentRequest", p).then(function(e){console.log(e)});
IMPORTANT!   When creating a new outgoing payment record, the following information should be sent in order for the action to be successful. All fields are mandatory, except when declared otherwise.
Parameter Description
paymentRequest Array with the payment request details.
paymentBeneficiary Array with details to identify the payment beneficiary.
payerDetails Array with details to identify the payer.
Field Observations
Payment No The unique number of the outgoing payment.
Payment Type The payment type. The option set can take the following values: paymentInAdvance, paymentOrder, paymentWriteOff, schedule, paymentReturn, paymentExternal, paymentClaim, paymentUnallocated, paymentPartner, brokerPremiumPayment, brokerCommissionPayment, brokerClaimPayment, brokerClientReturnPayment, brokerPaymentReturn, outgoingPayment, and bankCharges.
Payment Amount The outgoing payment amount.
Payment Due Date The outgoing payment due date.
Creation Date The outgoing payment request creation date.
Proposed by The user who makes the request.
Currency The currency of the outgoing payment.
Scheduled Date The date scheduled for the payment. Not mandatory for payments registered in Draft status.

Default Business Status

 The default business status for the payment request. The available values are: Proposed and Approved. This key is optional.
Comments Not a mandatory field.
Field Observations
Beneficiary Type Option set used to choose the beneficiary type. The option set values are as follows: payer, insured, contractor, policyBeneficiary, broker, serviceProvider, and other.
Beneficiary Category Set to Company or Individual.
Unique ID No The unique number of the outgoing payment beneficiary.
Name The name of the outgoing payment beneficiary.
IBAN The IBAN of the outgoing payment beneficiary.
Bank Must correspond to IBAN.
Field Observations
Payer Name The name of the payer.
Payer IBAN The IBAN of the payer.
Payer Bank Must correspond to IBAN.

This is an example of a response:

Copy 
{
    "UIResult": {
        "NavigateToEntityPage": false,
        "NavigateToEntityPageOnEdit": false,
        "NavigateToEntityFormName": null,
        "NavigateToEntityName": null,
        "NavigateToEntityId": null,
        "NavigateToEntityInsertDefaults": null,
        "NavigateToUrl": null,
        "DownloadFile": null,
        "ReloadPage": false,
        "Message": null,
        "IsSuccess": false,
        "Data": "{\"isSuccess\":true,\"errorMessage\":null,\"errorCode\":null,\"result\":{\"outgoingPaymentRequestId\":\"394cc3cf-5059-455f-8b6b-93054f201dd7\",\"paymentReference\":\"REF0000090\"}}",
        "NavigateToPageNo": null
    },
    "Message": null,
    "IsSuccess": true,
    "ClientScript": null,
    "Serialized": null,
    "ErrorCode": 0
}

Response description:

Key Description
errorCode Error code.
isSuccess Marks weather the request is successful or not.
errorMessage Error message.
outgoingPaymentRequestId The unique id of the outgoing payment request that was added.
paymentReference The payment reference of the request that was added.

The following are the error messages that can be encountered during outgoing payments generation process:

Code Text Description
ERR01.01 ERR01.01 - Invalid paymentType! This payment type is not found in the FTOS_PYMT_OutgoingPaymentType option set.  
ERR01.02 ERR01.02 - Invalid currency! No active currency found  
ERR01.03 ERR01.03. - Invalid beneficiaryCategory! This error appears when the beneficiary category is not found in the FTOS_CMB_AccountType entity or the account type selected is "Self employed indi­vidual".  
ERR01.04 ERR01.04 - First name and last name mandatory for individual person beneficiary category! When the "Individual person" beneficiary category is selected, the first name and last name are mandatory.  
ERR01.05 ERR01.05 - Name is mandatory for legal person beneficiary category! When the "Legal person" beneficiary category is selected, the name is mandatory.  
ERR01.06 ERR01.06 - Name should be empty for individual person beneficiary category! The attribute name should be empty when the "Individual person" beneficiary category is selected.  
ERR01.07 ERR01.07 - First name should be empty for legal person beneficiary category! The attribute first name should be empty when the "Legal person" beneficiary category is selected.  
ERR01.08 ERR01.08 - Last name should be empty for legal person beneficiary category! The attribute last name should be empty when the "Legal person" beneficiary category is selected.  
ERR01.09 ERR01.09 - Payment number is mandatory! The payment number should be completed.  
ERR01.10 ERR01.10 - Payment amount is mandatory and must be a number! The payment amount should be filled in with a number.  
ERR01.11 ERR01.11 - Payment due date is mandatory and must be a date! The payment due date should be filled in with a date.  
ERR01.12 ERR01.12 - Payment creation date is mandatory and must be a date! The payment creation date should be filled in with a date.  
ERR01.13 ERR01.13 - Payment scheduled date is mandatory and must be a date! The payment scheduled date should be filled in with a date.  
ERR01.13.1 ERR01.13.1 - Payment scheduled date has to be equal or bigger than the current date! The payment scheduled date has a validation to be equal or greater than today.  
ERR01.13.2 ERR01.13.2 - Payment scheduled date must be a date! The payment scheduled date should be filled in with a date. Only appears when defaultBusinessStatus is not completed.

 
ERR01.14 ERR01.14 - Invalid beneficiary Type! This beneficiary type is not defined in the FTOS_PYMT_OutgoingPaymentBeneficiary option set.  
ERR01.15 ERR01.15 - Payment beneficiary iban is mandatory! The IBAN should be completed.  
ERR01.15.1 ERR01.15.1 - Payment beneficiary iban is not valid! Invalid payment beneficiary IBAN.  
ERR01.15.3 ERR01.15.3 - No matching Bank for payment beneficiary iban! This bank couldn't be identified based on the payment beneficiary IBAN filled in.  
ERR01.16 ERR01.16 - Payer name is mandatory! The payer name should be completed.  
ERR01.17 ERR01.17 - Payer iban is mandatory! The payer IBAN should be completed.  
ERR01.17.1 ERR01.17.1 - Payer iban is not valid! Invalid payer beneficiary IBAN.  
ERR01.17.3 ERR01.17.3 - No matching Bank for payer iban! This bank couldn't be identified based on the payer IBAN filled in.  
ERR01.18 ERR01.18 - Payment number must be unique! There is another payment registered with this number.  
ERR01.19 ERR01.19 - Invalid user for ProposedBy. Invalid user.

ERR01.20

ERR01.20 - Invalid business status!

Invalid business status!

FTOS_PYMT_AddOutgoingPaymentRequest

Endpoint used to run the FTOS_PYMT_AddOutgoingPaymentRequest server automation script. See below.

FTOS_PYMT_AddOutgoingPaymentRequest - Script called with a data object.
This script first calls the validateRequest function from the BillingCollectionAPIs server automation script library. If the function returns the isSucces answer, then the script uses the same object to call the addOutgoingPaymentRequest function, from the BillingCollectionAPIs server automation script library.

The BillingCollectionAPIs library validates a request for an outgoing payment and creates a new request record based on the object received from the FTOS_PYMT_AddOutgoingPaymentRequest script.

The library contains the following functions:

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 function validates the date.

Input parameters: dateString - The date string formatted like yyyy-MM-dd.

Output parameters: true/ false.

This function returns the Id of the bank from FTOS_PYMT_Bank entity.

Input parameters: bankCode - string - The code of the bank.

Output parameters: bankId - The Id of the bank, from FTOS_PYMT_Bank entity.

This function returns the Id of the outgoing payment from the FTOS_PYMT_OutgoingPayment entity

Input parameters: paymentNo - string - The number of the payment.

Output parameters: outgoingPaymentId - The Id of the outgoing payment, from FTOS_PYMT_OutgoingPayment entity.

This function returns the userId from the System User entity.

Input parameters: userName - string - The name of the user.

Output parameters: userId - The Id of the user, from the System User entity.

This function returns the reference number from FTOS_PYMT_OutgoingPayment entity.

Input parameters: outgoingPaymentId - string - The Id of the outgoing payment request.

Output parameters: referenceNo - The reference number from FTOS_PYMT_OutgoingPayment entity.

This function returns the default payer details (name and IBAN), set in the processor FTOS_PYMT_OutgoingPayments_PayerDetails. This allows the user, or a third-party app, to call the API for generating an outgoing payment request without sending the payer details.

Input parameters: N/A.

Output parameters: payer details - A JSON structure containing the values from the processor.

This function inserts a new outgoing payment request, based on the given object from the FTOS_PYMT_AddOutgoingPaymentRequest server automation script.

Input parameters: input – object – The object received from the FTOS_PYMT_AddOutgoingPaymentRequest server automation script. The object contains the details about:

  • the payment request: paymentNo, paymentType, paymentAmount, paymentDueDate, creationDate, proposedBy, currency, scheduledDate, comments;

  • the payment beneficiary: firstName, lastName - for individual persons, name - for legal persons and other category, uniqueID, beneficiaryType, beneficiaryCategory, iban;

  • the payer: payerName, iban.

Output parameters:

  • id - The Id of the newly inserted outgoing payment request.

  • referenceNo - The reference number of the newly inserted outgoing payment request.

The addOutgoingPaymentRequest function also uses some of the functions presented above and the getIdByAttrib function, presented below.

This is a function from the FTOS_INS_Utils library. This function returns the Id of the given attribute.

Input parameters:

  • entityName – string – The entity name.

  • searchAttribute – string – The name of the attribute.

  • searchValue – string – The value of the attribute .

Output parameters: The Id of the searched attribute. If there are no entries with the searched value, the output is null.

This function validates an option set value from an option set.

Input parameters:

  • optionsetName - string - The name of the option set.

  • optionsetItemValue - string - The value of the option set item.

Output parameters: true/ false.

This function returns an object result with one of the following responses: isSuccess, errorMessage, errorCode.

Input parameters:

  • isSuccess - The success message.

  • errorMessage - The error message.

  • errorCode - The error code.

Output parameters: rez - An object containing the result.

This function validates the input object from the FTOS_PYMT_AddOutgoingPaymentRequest server automation script and uses some of the functions presented above.

Input parameters: input – object – The object received from the FTOS_PYMT_AddOutgoingPaymentRequest server automation script.

Output parameters: rez - An object containing the following details: {isSucces:true/false, errorMessage: “message error“, errorCode: “error code”}.

The function validates if the scheduled date has the correct date and format, and if it was submitted (for the case when it was marked as mandatory).

Input parameters:

  • rez - The result object.

  • scheduledDate - The scheduled date.

  • mandatory - boolean - The variable to determine if a scheduled date is mandatory.

Output parameters: returns an object - rez, with the followings {isSucces: true/false, errorMessage: “message error“, errorCode: “error code”}