Change log:

Terms and definitions:

Purpose of Document

This document provides an overview of the technical design and implementation of the Nordea Payout project, as well as providing details of any required configuration.

Introduction to Functionality

The purpose of the Nordea Payout project is to create Nordea payment message files in XML format (pain.001.001.03), that will be sent to and processed by Nordea, and received and process Nordea response message files (pain.002.001.03).

The response from Nordea comes in two tiers: The acknowledgement response is a validation of the payment message file format itself. If the acknowledgement response is positive, the payment message will be sent to Nordea’s backend for processing. Once this process is complete, we will receive a status report with an overview of the status of each requested payment. Additionally, if an accepted payment fails when attempted by Nordea, we may receive a third report containing rejections for previously accepted transactions.

The project consists of three engines:

See implementation details below, for a more detailed description of each engine.

Implementation

Below can be found technical details regarding the implementation of Nordea Payout. The project is split into four modules:

State Diagrams

NordeaPayoutSource - Response Status

NordeaPayoutItem - Response Status

Nordea Core

This module includes two new tables and required entity classes, as well as utility classes for cross-engine functionality. It also includes a custom implementation of AccountPaymentDateForBillingGroupRefundRequestProvider that is used to set the Payment Date on the Account Payment created when a Payout Request is approved.

NORDEA_PAYOUT_SOURCE

Table containing information about a batch of account payments. Primarily used to track the header information for the Nordea payment file.

NORDEA_PAYOUT_ITEM

Table containing information about each individual payment, used to track PaymentInformation for the nordea payment file.

NextBankingDayAsPaymentDateForNordeaPayoutRequestProvider

The Nordea Core module contains a new custom implementation of interface AccountPaymentDateForBillingGroupRefundRequestProvider named NextBankingDayAsPaymentDateForNordeaPayoutRequestProvider. This implementation is listed in the module’s resources, and will be automatically found and invoked when Billing Group Refund Requests are approved (so long as this module is included in the dependencies for Customer Care or Main Menu).

This provider will start with the refund date from the refund request (or now if later). If the refund date is before the cut-off time specified by parameter NORDEA.PAYOUT.PAYMENT_DATE.CUTOFF_TIME, and the refund date is a valid banking day, then the payout should be created with a payment date of the same day. Otherwise, the payment should be created with a payment date of the next valid banking day.

A date is considered a valid banking day if:

• It is not weekend (i.e. day of week is not SATURDAY or SUNDAY); and

• The day is not configured as a holiday in the Calendar specified by parameter NORDEA.PAYOUT.PAYMENT_DATE.CALENDAR_KEY

Misc

Implementation includes entity objects to represent above tables, NordeaPayoutSource and NordeaPayoutItem, builders (NordeaPayoutSourceBuilder, NordeaPayoutItemBuilder) and retrievers (NordeaPayoutSourceRetriever, NordeaPayoutItemRetriever). Added StatusNordeaPayoutSource to handle the status values of the NordeaPayoutSource.

• NordeaPayoutSourceBuilder does not take any input. NordeaPayoutSourceBuilder.build() will:

  • generate a message id

  • set status ID = 0 (NEW)

  • Set create date to DateUtils.now()

• NordeaPayoutItemBuilder takes two input. An AccountPayment, and a NordeaPayoutSource. Both are mandatory. NordeaPayoutItemBuilder.build() will:

  • set the source id of the provided NordeaPayoutSource object

  • set account payment id from the provided AccountPayment

  • set amount from the provided AccountPayment and negate the value

  • generate a instruction id (TODO: determine exactly how to format an instruction id)

Nordea Payment Handler

New PaymentHandlerEngine that processes account payments ready for payout. The engine will retrieve a batch of account payments, and generate NordeaPayoutSource and NordeaPayoutItems.

EngineParameters

EngineStartupCheck

Startup check implementation. No startup checks are required, so this just returns true. Exists to enable the implementation of startup checks if required.

EngineQueueLoader

Uses the broker to retrieve account payments where:

• capture status = AccountPaymentCaptureStatus.DO_PAYOUT

• payment_date is before sysdate

• payment_type is one of the payment types provided as engine parameter

EngineHandler

The EngineHandler will:

• Receive a list of account payments

• Create and save a new NordeaPayoutSource object

• For each account payment in the list:

  • Validate the account payment (chekcing the payment option and trying to match the personalID (cpr-nr) to a PersonalID object)

  • Create and save a new NordeaPayoutItem object, with an account payment and source object

  • Update the capture status of the account payment to AccountPaymentCaptureStatus.PAYOUT_SENT

  • Add the account payment amount to the batch sum

  • If account payment validation fails, no NordeaPayoutItem is created, and the account payment capture status is set to AccountPaymentCaptureStatus.PAYOUT_REJECTED

• When all account payments have been processed:

  • Set the final batch size on the source object

  • Set the batch sum on the source object

  • Set the status id of the source object to 1 (READY)

  • Save the source object

Nordea Message Handler

New MessageHandlerEngine that processes Nordea payout source objects. The engine will retrieve source objects in status 1 (READY) and generate a payment xml file and update the source with send date, set source status to 2 (SENT) and set the newly generated file name.

EngineParameters

EngineStartupCheck

Startup check implementation. The MessageHandlerEngineStartupCheck will validate if the following mandatory parameter values have been configured:

• NORDEA.PAYOUT.DEBTOR.ID

• NORDEA.PAYOUT.DEBTOR.NAME

• NORDEA.PAYOUT.DEBTOR.ADDRESS_LINE

• NORDEA.PAYOUT.DEBTOR.ACCOUNT_ID

• NORDEA.PAYOUT.INITIATOR.ID

• NORDEA.PAYOUT.FILE_HANDLER.PAYOUT_REQUEST.OUTGOING_FOLDER

Without these values configured, the engine will not start.

EngineItemErrorHandler

Updates the source to status 4 (ERROR) if an exception is caught during the engine processing.

EngineQueueLoader

Uses NordeaPayoutSourceRetriever. If engine is running in normal mode, will retrieve all sources in status 1 (READY). If engine is running in resend mode, will retrieve all sources in status 3 (RESEND).

EngineHandler

The EngineHandler will:

• Create the XML document based on the nordea payout source object.

• Create the outgoing xml file in a configurable outgoing file folder.

• Update the source after successful file generation:

  • Set file name on source object

  • set send date (DateUtils.now()) on source object

  • set status=2 (SENT) on source object

  • save the source object

Please note that this engine does not handle the generated file further. Once the file has been created, it is up to the customer project to handle and/or send the xml file as per business requirements.

Nordea Response Handler

New ResponseHandlerEngine that processes response (acknowledgement and status report) files from Nordea. The engine will use the response to update corresponding NordeaPayoutSources, NordeaPayoutItems and account payments based on the status of the response. If a payment is successful, that AccountPayment capture status is changed to PAYED_OUT. If a payment is rejected, the capture status is changed to PAYOUT_REJECTED.

It is assumed that the response files can be found at the expected location as configured in the parameter tree (see parameter configuration below).

EngineParameters

The ResponseHandlerEngine does not take any parameters.

EngineStartupCheck

Startup check implementation. The ResponseHandlerEngineStartupCheck will validate if the following mandatory parameter values have been configured:

• NORDEA.PAYOUT.FILE_HANDLER.PAYOUT_RESPONSE.INCOMING_FOLDER

• NORDEA.PAYOUT.FILE_HANDLER.PAYOUT_RESPONSE.PROCESSED_FOLDER

• NORDEA.PAYOUT.FILE_HANDLER.PAYOUT_RESPONSE.ERROR_FOLDER

Without these values configured, the engine will not start.

EngineItemErrorHandler

Moves the response file to the incoming error folder if an exception happens during the reading of the file.

EngineQueueLoader

Retrieves a list of all files in the configured incoming file location.

EngineHandler

The EngineHandler will:

• Convert the incoming file to an XML document

• Retrieve three main elements of the pain.002.001.03 file: GroupHeader, OriginalGroupInformationAndStatus and OriginalPaymentInformationAndStatus. Each of these elements will be read in turn:

  • GroupHeader: Contains information about the pain.002.001.03 file, such as message id, creation time and sender information. These fields are not used.

  • OriginalGroupInformationAndStatus: Contains group information sent in the original request.

    • OriginalMessageIdentification: the messageId of the original request. Used to identify the source in NORDEA_PAYOUT_SOURCE

    • GroupStatus: The status of the original request. This can either be ACTC or RJC. If status is RJC, we update the source object with status 4 (ERROR). Note that this field is only present for the acknowledgement response. In the full status report, this field is not present.

    • Reason / AdditionalInformation: If the GroupStatus is RJC, this field will contain a description. If found, this value is set on the source as RESPONSE_MESSAGE

  • OriginalPaymentInformationAndStatus: Details about the status of each individual payment. If this field is not found, we can assume the file is an acknowledgement file. This element contains the following relevant fields:

    • OriginalPaymentInformationIdentification: The payment id provided in the original request. Not currently used on Rator side.

    • PaymentInformationStatus: The overall status of the payout request. Can have the following values: ACCP, ACWC, PART, PDNG and RJCT. Only ACCP, PART and RJCT are valid for payouts.

    • Reason / AdditionalInformation: If the PaymentInformationStatus is RJC, this field will contain a description. If found, this value is set on the source as RESPONSE_MESSAGE (Note: according to the documentation, the AdditionalInformation element will always be provided unless the status is ACCP. However, in the provided example the status is PART, and no AdditionalInformation is included.)

    • TransactionInformationAndStatus: This is the list of payments from the original payout request. It includes OriginalInstructionIdentification, OriginalEndToEndIdentification and TransactionStatus. OriginalEndToEndIdentification is used to identify the NORDEA_PAYOUT_ITEM for this payment. TransactionStatus can have values of ACCP, ACWC, PDNG and RJCT. Only ACCP and RJCT are relevant for payouts.

    • The EngineHandler will iterate through each payment and retrieve the linked NORDEA_PAYOUT_ITEM.

      • If the status is ACCP or ACWC, it will update the capture status of the account payment to PAID_OUT

      • If the status is PDNG, the capture status of the account payment will not be changed (I don't think this status is used for our purpose though)

      • If the status is RJCT, the capture status is set to PAYOUT_REJECTED

  • Once all payments have been processed, the status on the NORDEA_PAYOUT_SOURCE is updated to status 5 (COMPLETED) and the file is moved to a configurable 'processed' directory.

  • If an exception happens during this process, the file is moved to a configurable 'error' directory, and the source is updated to status 4 (ERROR) if possible.

Configuration

Below is an overview of required and optional parameter values.

Mandatory parameter values

These parameters are validated by the StartupCheck. None of the engines will start if any of these values are missing

Optional parameter values

These parameter values may or may not be required by business rules, but the engines will be able to run without them.