Change log:

Terms and definitions:

...

Terms/definitions:

...

Meaning:

...

TBD

...

To be determined

...

N/A

...

Not applicable

Purpose of Document

...

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.

...

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.

...

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.

State Diagram - NORDEA_PAYOUT_

...

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

...

SOURCE.RESPONSE_STATUS

NORDEA_PAYOUT_SOURCE.RESPONSE_STATUS is updated by NordeaResponseHandler based on Group Status or Payment Information Status received in PAIN.002 response files from Nordea:

NORDEA_PAYOUT_ITEM

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

State Diagram - NORDEA_PAYOUT_ITEM.RESPONSE_STATUS

NORDEA_PAYOUT_ITEM.RESPONSE_STATUS is updated by NordeaResponseHandler based on Transaction Status received for the individual payout transactions in the PAIN.002 response files. The corresponding AccountPayment is also captured, rejected, or withdrawn in conjunction with this change in state.

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.

...

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.

...

• capture status = AccountPaymentCaptureStatus.DO_PAYOUT

• checkpayment_date is before sysdate

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

...

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:

...

• 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 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.

...

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.