Change log:
Date: | Author: | Version: | Changes: | Completed | Ext. | Int. | Is in Core |
---|---|---|---|---|---|---|---|
20 July 2023 | CMI | 1.0 | Doc. created | No | |||
21 July 2023 | CMI | 1.0.1 | Added nordea documentation | No | |||
11 August 2023 | CMI | 1.0.2 | Added EngineStartupCheck documentation | No | |||
31 August 2023 | CMI | 1.0.3 | Added documentation for EngineItemErrorHandler. Moved debtor name and address line from mandatory to optional parameter configuration. Added END_TO_END_ID to NORDEA_PAYOUT_ITEM table. | No |
Terms and definitions:
Terms/definitions: | Meaning: |
---|---|
TBD | To be determined |
N/A | Not applicable |
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.
The project consists of three engines:
Name | Description |
---|---|
PaymentHandlerEngine | The payment handler engine will pick up Account Payments in status (DO_CAPTURE) and prepare them for handling by the MessageHandlerEngine. |
MessageHandlerEngine | The message handler engine will pick up payments ready for processing, and create a pain.001.001.03 Nordea payout message. The resulting file will be saved to a configurable outgoing file path. |
ResponseHandlerEngine | The response handler engine will pick up Nordea response files (pain.002.001.03) from a configurable incoming file location, and process the file, If the response file contains payout results, the original account payments to either PAID_OUT or PAYOUT_REJECTED, depending on the result status. |
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:
Nordea Core
This module includes two new tables and required entity classes, as well as utility classes for cross-engine functionality.
NORDEA_PAYOUT_SOURCE
Table containing information about a batch of account payments. Primarily used to track the header information for the Nordea payment file.
Column | Notes |
---|---|
ID | Standard rator ID. |
MESSAGE_ID | Generated when a new source is created, used as messageId in the nordea payment file. |
FILE_NAME | The name of the file on the file system, created when the file is created, and updated on the source. |
STATUS_ID | The status of the batch. 0=new, 1=ready, 2=send, 3=resend, 4=error. Notes: 0=new is used when the batch is created. Once the source has been filled out with relevant information and is ready to be picked up by the MessageHandlerEngine, the status is updated to 1=ready. Status 3=resend is used if file validation fails and the file needs to be recreated. |
CREATE_DATE | The date the source was created. |
SEND_DATE | Will be updated with the date when the Nordea payment file is created. |
RESPONSE_STATUS | The result from nordea's validation, set when we receive a response. This can be either ACTC or RJCT for acknowledgement response, or one of ACCP, ACWC, PART PDNG, or RJCT for the status report. |
RESPONSE_MESSAGE | if the file is rejected, the StatusReasonInformation will be added here if provided in the response. |
BATCH_SIZE | The total number of account payments included in this batch. Calculated in PaymentHandlerEngine as each account payment is being processed. Used as NumberOfTransactions in the nordea payment file. |
BATCH_SUM | The sum of values of all items included in this batch. Calculated in PaymentHandlerEngine as each account payment is being processed. Used as ControlSum in the nordea payment file |
NORDEA_PAYOUT_ITEM
Table containing information about each individual payment, used to track PaymentInformation for the nordea payment file.
Column | Notes |
---|---|
ID | Standard rator ID. |
ACCOUNT_PAYMENT_ID | The ID of the account payment this item represents. |
INSTRUCTION_ID | Generated when the payout item is created. Maps to the InstrId in the nordea payment file. |
END_TO_END_ID | Generated when the payout item is created. Maps to the EndToEndId in the nordea payment file. |
AMOUNT | The amount on the account payment. Used in the payment information of the nordea payment file. Note that this value will be positive in the payout item. |
RESPONSE_STATUS | The response code from Nordea validation. Possible values: ACCP, ACWC, PDNG, RJCT |
RESPONSE_MESSAGE | If payment is rejected, the StatusReasonInformation will be inserted here if provided in the response |
SOURCE_ID | The ID of the source object this item belongs to |
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
ACCOUNT_PAYMENT_TYPE_IDS | A list of account payment type IDs that are valid for the Nordea payout process |
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
check_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
RESEND_MODE | optional engine parameter that indicates the engine should run in 'resend mode'. The possible values for this parameter are: "y", "true", "yes", "on", "checked", "1". If this parameter is not included, or RESEND_MODE is set to one of "n", "false", "no", "off", "0", the engine will run in normal mode. 'Resend mode' means that the engine will retrieve sources in status 3 (RESEND) instead. |
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. OriginalInstructionIdentification 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
Parameter | Parameter type | Description |
---|---|---|
NORDEA.PAYOUT.DEBTOR.ID | S | The Nordea ID of the debtor, must be provided in every request. |
NORDEA.PAYOUT.DEBTOR.ACCOUNT_ID | S | The IBAN account ID of the debtor |
NORDEA.PAYOUT.INITIATOR.ID | S | The nordea ID of the request initiator. Will be the same as the debtor ID if the debtor is also initiating the request |
NORDEA.PAYOUT.FILE_HANDLER.PAYOUT_REQUEST.OUTGOING_FOLDER | S | The folder where the payout request file is deposited. |
NORDEA.PAYOUT.FILE_HANDLER.PAYOUT_REQUEST.PROCESSED_FOLDER | S | The folder where the payout request file is moved to after it has been processed. |
NORDEA.PAYOUT.FILE_HANDLER.PAYOUT_RESPONSE.INCOMING_FOLDER | S | The folder where the ResponseHandlerEngine will look for response files from Nordea. |
NORDEA.PAYOUT.FILE_HANDLER.PAYOUT_RESPONSE.PROCESSED_FOLDER | S | The folder where the ResponseHandlerEngine moves the response file after it has been processed. |
NORDEA.PAYOUT.FILE_HANDLER.PAYOUT_RESPONSE.ERROR_FOLDER | S | The folder where the ResponseHandlerEngine moves the response file if any errors occur during processing |
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.
Parameter | Parameter type | Description |
---|---|---|
NORDEA.PAYOUT.DEBTOR.NAME | S | A string representation of the name of the debtor. |
NORDEA.PAYOUT.DEBTOR.ADDRESS_LINE | S | Single line address of the debtor. |
NORDEA.PAYOUT.INFO.REMITTANCE_TEXT | S | The text being displayed on the payout message. |
NORDEA.PAYOUT.MESSAGE.CONFIGURATION.FILE_NAME_PREFIX | S | The prefix of the file name for the payout file. The full name of the file will be prefix+messageId+”.xml” |
NORDEA.PAYOUT.MESSAGE.CONFIGURATION.MESSAGE_ID_PREFIX | S | The prefix of the message ID for the payout file. The message ID will be: prefix+source_Id |
NORDEA.PAYOUT.MESSAGE.CONFIGURATION.PAYMENT_INFORMATION_ID_PREFIX | S | The prefix of the payment information ID for the payout file. The payment information ID will be: prefix+source_id |
NORDEA.PAYOUT.MESSAGE.CONFIGURATION.END_TO_END_ID_PREFIX | S | The prefix of the end-to-end ID for the payout file. The end-to-end ID will be: prefix+item_id |