OnTokenStatusChangeNotification4.0,
OnCustomerChangeNotification2.4,
OnPaymentProfileStatusChangeNotification,
OnPaymentStatusChangeNotification4.0,
OnNewPaymentNotification4.0,
OnOrganizationsChangeNotification4.0,
OnPaymentRequestChangeNotification2.4,
OnNewPaymentRequestNotification4.0

Request Version:

AddPaymentRequest4.1,
ChangePaymentRequestRequest4.0,
ChangePaymentStatusRequest4.0,
DeletePaymentProfileRequest,
GetCustomerEventDetailsRequest4.0,
GetOrganizationsRequest4.0,
GetPaymentRequest4.0,
GetPaymentRequestDetailsRequest4.0,
GetPendingActivityForTokenRequest3.2,
GetTokenHistoryRequest4.1,
GetTokenStatusRequest4.2,
MatchRecipientRequest4.1,
RegisterTokenRequest4.0,
RemoveTokenRestrictionRequest3.10,
RequestPaymentsRequest4.0,
RestrictTokenRequest3.10,
UnregisterTokenRequest3.10,
UpdateBusinessPaymentProfileRequest4.0,
UpdatePersonalPaymentProfileRequest4.0 

Installing and configuring IBM WebSphere Liberty server

Locate the Liberty Application Server compressed file that is stored in the following path:

 <installation directory>/ftm/vxxx/run/liberty
 xxx = represent current FTM version that is running (Example v327)

Decompress the file in your preferred path: <liberty-install-directory>  (for example /opt/wlp/).

Follow the steps below to create and configure the server:

1. Create you server with <liberty-install-directory>/bin/server create PFSServer.
2. Modify the server.xml.template file located in FTM installation path <installation directory>/shared/vxxx/pfs/WebServices/Liberty/PFS with config values for your install (see below).
3. Rename that file server.xml
4. Copy server.xml and jvm.options into <liberty-install-directory>/usr/servers/PFSServer.
5. Start you server with <liberty-install-directory>/bin/server start PFSServer --clean  (--clean is optional).

Things that need modifying in the server.xml.template depending on environment details:

Db2 install location, database name and port;
IBM MQ install location, queue manager name, user, password and port;
db2admin user and password.
currentPackagePath, currentFunctionPath, and currentSchema set to your schema name.
FTM's administrator password needs to be set (usually fxhadmin).
WAR File Deployment location: the path to the WebServices war file <installation directory>/shared/vxxx/pfs/WebServices/Liberty/PFS/WebServices_PFS.war.

Additional parameters might need to be adjusted depending on usage.
 

        

---

         
 

         
 

         
 

---

Held files may be incorrectly flagged as duplicate.

Transmissions that are held/pending (based on error code/rule set configuration) may be incorrectly flagged as duplicates.  The held/pending transmission “duplicate” will be resolved if/when the transmission is accepted (from held/pending).
 

WebSphere Application Server Liberty Update


FTM Base installation includes an updated WebSphere Application Server Liberty v20.0.0.12.  You are recommended to upgrade to this version or a later version if one is available.

---

26624

FTM’s Risk application can invoke a prefunding user exit on a transmission, batch, and transaction level.  The prefunding user exit returns pass/fail code based on internal financial institution requirements.  If the prefunding user exit returns a failure, then based on the configuration of the error code assigned, the unit of work (UOW) is either outright rejected or it is held in a suspended state.  A permissioned FTM user would normally need to manually depose the UOW.

An automated retry of Risk prefunded errors for transmissions, batches, and transactions has been added to FTM.  There are several components and configuration details that are involved with the retry process.  This includes business rules configuration, a business rules web service, a services framework task, ITS scheduler XML, and the Risk application.

Business Rules Configuration

The specific reason/error codes that can be retried as well as the number and duration of the retries are controlled via Business Rules configuration.  This configuration is maintained in the RETRY_CONFIG Business Rules table.  This table contains configuration columns for:

• Payment scheme – The associated payment scheme (Ex. NACHA, TCH RTP, ZELLE, and so on.)
• Category – A constant category reference that is determined by the participating application. In this case, Risk is the participating application, and “RISK_PREFUND” is the constant category value that is used.
• Reason code – This is the assigned reason/error code that should be retried.
• Interval – The amount of time (in seconds) to wait before retrying.
• Retry start/Retry end – These 2 columns define the retry attempt range and the associated retry time (interval).  These columns allow for flexible retry configuration of the retry interval.  EX.  Reason code AAA_XXX could be configured for a retry interval of 5 minutes (300 seconds) for retry attempts 1-3 and configured for a retry interval of 30 minutes (1800 seconds) for retry attempts 4-6.

The shipped digital payments sample for Risk prefunded retry contains configuration for the 3 prefunded credit error codes for transactions/accounts (RSK0008), batches (RSK0016), and transmissions (RSK0020) for the NACHA payment scheme. 

The sample configuration looks like this:

Sample Retry Configuration

Business Rules Web Service

To determine the configured, retry configuration when a prefunded error code is assigned, the Risk application calls the Business Rule retry configuration web service.  To do that, the Business Rules web service client needs to be configured with information about the locally hosted Business Rules web service to allow for proper connectivity

There are 2 new WebSphere environment configurations that have been created for the Business Rules web service.

First, a new “BR Web Services Endpoint URL” URL WebSphere resource has been created for JNDI “brules/webserviceURL”.  The specification of this URL resource should point to the location of the locally hosted Business Rules web service.  The default URL configuration looks like this:

Business Rules Web Service JNDI

Second, a new JAAS Alias will be created for the Basic Authentication that is configured for the Business Rules web service.  The default JAAS Alias looks like this:

Business Rules JAAS Alias

Services Framework Retry Task

A new Services Framework task has been created to support the digital payments retry functionality.  The class name for the new task is “com.ibm.paydir.izg.tasks.retry.RetryTask”.

The task accepts 2 configuration parameters.

• Category – The category reference that is determined by the participating application. In this case, Risk is the participating application, and “RISK_PREFUND” is the constant category value that is used.
• Payment Scheme – The desired payment scheme (Ex. NACHA, TCH RTP, ZELLE, and so on.).  This field is optional.  The task looks for all payment schemes if not configured.

Below is a sample Retry Task configuration for a NACHA Risk Prefunded retry:

Retry Task Configuration

When executed, the Retry Task scans the RETRY and RETRY_ATTEMPT tables for retries that are past due that match the configured criteria (NACHA/RISK_PREFUND in this case). 

The Retry Task can be scheduled to run on a timed schedule. The Risk retries will be executed when the Retry Task determines that a retry attempt has expired and an event is sent to Risk (see ITS Scheduler update below).  So, any retry that is configured for 30 minutes will have a bit of a time lag between the time that the 30 minutes has expired and when the Retry Task executes.  So, some thought should be given to how often the Retry Task should be scheduled to execute.  If it is scheduled to execute every 5 minutes, then a maximum of a 5-minute lag between expiration and actual execution must be acceptable.

ITS Scheduler

A new stanza has been added to the ITS Scheduler to allow for correct event publishing to the Risk application.  This new stanza has to be in the Scheduler.xml for correct Risk retry processing.

The new stanza looks like this:

<EVENT>

   <NAME>Risk - Retry Initiation</NAME>

   <TYPE>RetryExecAdded</TYPE>

   <EXEC>com.ibm.paydir.ima.txsvr.event.appbridge.RetryExecAddedEventHandler</EXEC>

   <PARAMETER name="msgType">retryPrefund</PARAMETER>

   <PARAMETER name="category">RISK_PREFUND</PARAMETER>

   <PARAMETER name="paymentScheme">NACHA</PARAMETER>

   <PARAMETERREF>schedulerReferenceProperties</PARAMETERREF>

   <PARAMETERREF>sendToRiskManagement</PARAMETERREF>

</EVENT>

Risk application

FTM’s Risk application can invoke a prefunding user exit on a transmission, batch, and transaction level.  When this prefunding user exit check fails, risk application queries Business rules web service using the error/reason code returned by user exit among other parameters like scheme, retry category and retry number.  If matching configuration is found in business rules webservice, UOW is added for retry.  This will add entries in RETRY and RETRY_ATTEMPT tables.  While UOW is under retry protocol, new flag ‘Retrying’ is set to ‘Yes’.  New flag ‘Retrying’ is available for transmission, batch and transaction.

History tab on UOW displays appropriate message indicating that UOW is under retry protocol.

 

Subsequent retry attempts are driven by events that are initiated by Retry Task.  When retry message comes in FTM Risk application, risk will invoke prefunding user exit for the UOW.  If prefunding user exit passes, UOW is removed from retry protocol and risk application proceeds with further checks. 

If prefunding user exit fails, risk application will query business rules webservice.  Depending on the response from business rules webservice, UOW either waits for another retry or exits retry protocol if number of configured retry attempts are exhausted.

---

73985

The CreateCXCToken web service has been enhanced to support the ability transfer a token that is already registered at EWS.  It is assumed that all verification and authorization of this action will be done by the mobile application before allowing the token to be transferred.

The CreateCXCToken web service previously required the passed in paymentProfileId value to be “generated” for the token to be created.

A new “transferring” paymentProfileId value will be supported on the CreateCXCToken web service.  When attempting to register a token with EWS, FTM will determine the token status with FTM.  If the token is registered with EWS and the paymentProfileId is set to “transferring” then FTM attempts to unregister that token with EWS.  If the unregister call is successful, FTM then registers that same token with EWS for the owning FI (as a normal CreateCXCToken web service call).

The alternate CreateCXCToken flow can be seen here:

---

---

FTM’s read Zelle payment and payment request web services should provide all the required transaction information to the web service client/caller so that all Early Warning user experience guidelines can be met. 

There are some additional “historical” data fields that have been added to the EWS user experience guidelines that are not currently reflected in the date returned in those web services.

Zelle Payments

There are multiple scenarios covered in the EWS UX experience for viewing Zelle payment details.  The scenarios depend on whether the recipient is known or unknown as well as the status of the payment. 

For payments sent to unknown recipients, the payment will be in a “Payment pending” status for some period while the unknown recipient is notified (email or mobile text) that a Zelle payment is available to them.  Once the recipient signs up for Zelle, and the payment is successfully delivered, then the payment is marked “Delivered”.  When sending to a known recipient, the payment will go directly to “Delivered” (assuming success). 

For unknown recipients, other possible end status for the payments is “Canceled” or “Expired”.

The EWS user experience guidelines dictate that payments to the unknown recipients should have a timeline look and feel that displays the date that the payment was initially sent as well as the end date of the payment (Delivered, Canceled, Expired).

The user experience would look something like this:

Payment read web service

The various read webservices provided by FTM that include Payment information will be updated with new fields to allow the client to meet the user experience guidelines. 

Two new read only fields are being added to the payment information in the FTM read web services.

• Deactivation Date/Time – This timestamp field will reflect the time that the payment was “deactivated”.  This value will reflect whenever the payment was Delivered, Canceled or Expired.
• To Known Recipient – This boolean field will reflect whether the recipient of the payment was known to EWS/Zelle when the payment was originated. The field will be true if the recipient was known at the time the payment was originated and false if the recipient was not known.  The field will remain constant throughout the life of the payment.  So, an initial payment to the unregistered “test@email.net” token would reflect a value of false.  A subsequent payment (after the token is registered) would reflect a value of true.

The calling client can use these new fields in coordination with the existing data in the web service response (initiation time, payment status, and so on.) to meet the user experience guidelines for payments.

Zelle Payment Requests

There are multiple scenarios covered in the EWS UX experience for viewing Zelle payment request details.  The scenarios for both known and unknown respondents are similar since both cases require the responder to actively send a response to the payment request.

For payment requests sent to unknown/known respondents, the request will be in a “Request sent” status.  If the respondent chooses to sign up for Zelle (unknown respondent) and then chooses to respond to the payment request (both known and unknown respondents), then the payment request will be marked as “Complete”.  If they do not respond, then the payment request will eventually be marked as “Expired”.  The requestor can also cancel the payment request which would result in a status of “Canceled”.

The EWS user experience guidelines dictate that payment requests have a timeline look and feel that displays the date that the payment request was initially sent as well as the end date of the payment request (Completed, Canceled, Expired).  If the payment request is completed/paid, then the user experience dictates that the amount paid should also be included.

The user experience would look something like this:

Payment Request read web service

The various read webservices provided by FTM that include payment request information will be updated with new fields to allow the client to meet the user experience guidelines. 

Four new read only fields are being added to the payment request information in the FTM read web services.

• Deactivation Date/Time – This timestamp field will reflect the time that the payment request was “deactivated”.  This value will reflect whenever the payment request was Completed, Canceled or Expired.
• To Known Recipient – This boolean field will reflect whether the responder of the payment request was known to EWS/Zelle when the payment request was originated. The field will be true if the responder was known at the time the payment request was originated and false if the responder was not known.  The field will remain constant throughout the life of the payment request.  So, an initial payment request to the unregistered “test@email.net” token would reflect a value of false.  A subsequent payment request (after the token is registered) would reflect a value of true.
• Responder payment id – This string field will contain the payment id of the EWS payment that deactivated/paid the payment request.
• Responder payment amount – This numeric field will contain the actual payment amount received from the EWS payment that deactivated/paid the payment request.

The calling client can use these new fields in coordination with the existing data in the web service response (initiation time, payment request status, and so on.) to meet the user experience guidelines for payment requests.

---

Early Warning has created a new RESTful web service (Zelle Profile Search Service – ZPSS) that will allow FTM to provide a list of recipient tokens, and the web service will respond with a list of those tokens (if any) that are registered with EWS/Zelle.  The tokens that are registered will return whether the token is a personal or small business token along with an optional photo url.  These two pieces of information can be used by the calling client to provide a better user experience to the end user by denoting which of the user’s recipients are registered Zelle users.

There is no known guidance from EWS on how often the recipient lists should be refreshed, so it will be up to the financial institution how often this web service is used.

CXCRecipient

Two new fields have been added to the recipient data object. 

• Recipient Type – This string field will reflect the type of token as known to EWS. The values for this field can be: UNKNOWN, PERSON, BUSINESS.
• Photo URL – This string field will reflect the photo URL returned from the ZPSS webservice.

A new optional “refreshEWSActiveProfiles” parameter (valid values: null, “Y”, “N”) has been added to the CXCRecipient read (GET) web service.  If the refreshEWSActiveProfiles parameter is set to Y, then a partner ID parameter must also be included in the web service request.  This is to ensure that the ZPSS web service will be called for a single participant at a time.  When refreshEWSActiveProfiles is requested, FTM will call the EWS ZPSS web service for all the participant’s defined recipients and will update the recipient type and photo url for each.  This also means that any recipient that is not currently active at EWS will have its recipient type set to UNKNOWN and its photo URL cleared which will provide clarity on which recipients are registered Zelle users.

Both the recipient type and photo URL recipient fields will be available on the Zelle Recipients preference in FTM’s Participant Directory.

CXCParticipant

One new field has been added to the participant data object.

• Active Recipients Checked – This timestamp field will reflect the last time that the ZPSS web service was called for this participant.

Since there is no known guidance from EWS on how often the recipient lists should be refreshed, the client could use this timestamp field to determine if/when the participant’s active recipient list needs to be refreshed with EWS.

The timestamp field will be viewable as “Recipient profiles refreshed” on the Zelle Participant preference in FTM’s Participant Directory.

Read CXCRecipient web service workflow

With the addition of the refreshEWSActiveProfiles request parameter on the read CXCRecipient web service, the behavior of the web service will include the step of handling the EWS ZPSS web service call when requested.

When the refreshEWSActiveProfiles parameter is not set or is set to “N”, then the read CXCRecipient webservice will process as before the changes.

Read CXCRecipient without refreshing ZPSS

Read CXCRecipient with ZPSS refresh

WebSphere configuration

The EWS ZPSS RESTful endpoint url will need to be configured correctly for FTM to successfully call the web service.  To allow for this configuration, a new JNDI URL resource will be added to FTM’s WebSphere Application Server configuration:

EWS ZPSS JNDI configuration

The correct EWS ZPSS web service URL must be correctly defined in this variable for FTM to call the EWS web service.

It is assumed that the Financial Institution’s internal IT infrastructure (API Gateway, other) will inject any web service authentication (Basic, OAuth, JWT, and so on.) required by EWS to allow for successful web service connectivity between FTM and Early Warning.

NOTE:

The guidance from EWS is that the EWS MatchRecipient web service API should only be called during the workflow of a transaction.  Any other workflow (including recipients) should use the lighter weight GetTokenStatus call.  With this conversion, the recipient’s EWS participant id will not be returned for participant recipients/recipient lists.

So, going forward, the recipientID field on the CXCRecipient object will no longer be set.  If this field was being used to denote that a recipient is registered with EWS, then that logic should shift to using the newly added recipientType field along with the enhanced Read CXCRecipient web service that refreshes the recipient list with EWS.  If the recipientType field is UNKNOWN, then that recipient is not registered with EWS.  If the recipientType field is PERSON or BUSINESS, then that recipient is registered with EWS.

---

The Global Limit Monitor Detail Screen has a Maturity Date field added to it.   This is an optional field and if not filled is set to null.   If the maturity date is set, then this limit monitor will become inactive after the date specified.   A Services Framework Task has also been updated that will allow the creation of system alerts as Global Monitor Limits approach their maturity date. 

Global Limit Monitor UI

The Maturity Date Field is optional.  If it is left blank, then the Limit Monitor will never mature/expire.   If a date is provided the it will be tested to make sure that it is not a date in the past.   The following screen shows update Global Monitor Screen.

Maturing Risk Monitor Definition Services Framework Task

Services framework task (com.ibm.fxh.risk.tasks.MaturingRiskMonitorReportingTask) already exists that iterates through participant limit monitors that have maturity dates defined.  This task has been updated to include global monitors. 

This task now iterates through all risk monitor definitions where maturity dates have been specified.  The task will test these maturity dates against the configuration parameters which define when the alerts should be generated for monitor definitions approaching their maturity dates.

Alert message with unique message identifier is generated for each warning message:

• First Warning: RSKLM102W: The Limit Monitor monitorID (monitorDescription) for Participant Id partnerId will mature in firstWarningDays days
• Second Warning: RSKLM103W: The Limit Monitor monitorID (monitorDescription) for Participant Id partnerId will mature in secondWarningDays days
• Third to Zero Warning: RSKLM104W: The Limit Monitor monitorID (monitorDescription) for Participant Id partnerId will mature in thirdToZeroWarningDays days
• At Maturity Date: RSKLM101W: The Limit Monitor monitorID (monitorDescription) for Participant Id partnerId matures today.  This Limit Monitor will no longer be used after today

In case of Global Limit Monitor, partnerId in above alert messages will be replaced by keywork Global.

---

FTM supports multiple scheduling options for scheduled/recurring payments.  A payment can be scheduled as a single/one-time payment, a weekly recurring payment, or a recurring monthly payment.  Depending on the configuration, the recurring payment can be scheduled in a variety of ways:

• Every Wednesday
• Every other Friday
• Monthly on 15^th
• Monthly on the last day of the month
• Every other month on the 5^th

In the scheduled/recurring data, there are 4 configuration values that control this behavior.  Those 4 values are: Frequency, Interval, Day, and Start Date.

The following table identifies the values held by the scheduling configuration fields for the current scheduling options. 

• If the Frequency is Weekly, then the Day value will reflect the textual day of the week (Monday - Sunday).
• If the Frequency is Monthly, then the Day value will reflect the numeric day of the month (1 – 31). The Day value could contain a comma separated list of numeric days to reflect multiple days per month.
• The start date for single payments will dictate when the payment will be initiated. 
• The start date for weekly/monthly recurring payments will control when the recurring payment starts. If not set, the recurring payment will start from the current date.

Schedule Description	Frequency	Interval	Day	Start Date
1-time future payment	Single	Null	Null	2021/12/17
Weekly payment on Wednesday	Weekly	1	Wednesday
Every other Friday	Weekly	2	Friday
Twice monthly 15th and 31st	Monthly	1	15, 31
Monthly on 20th	Monthly	1	20
Every other month on 17th	Monthly	2	17
Every 3 months on 5th (quarterly)	Monthly	3	5
Every 6 months on 11th	Monthly	6	11
Every 12 months on 22nd (annually)	Monthly	12	22
Last day of the month	Monthly	1	31

The current scheduling options offer various configurations and supplies quite a bit of scheduling flexibility.  However, the ability to schedule a payment for the “Nth day of the month” (3^rd Friday of the month) cannot be done using the current configuration options.  All the current monthly configurations assume that the payment is being sent on a specific numeric day of the month.

FTM has been updated to support a configuration that will allow for “Nth day of the month” recurring payment initiation.

Scheduled/recurring model web service update

A new ordinal numerical field has been added to the scheduled model data object.  This new field will dictate whether the model is configured for the new Nth day processing.

The create/update/read scheduled/recurring model webservices will be updated to handle the new ordinal configuration. 

The create/update webservices will provide the following validations:

• The ordinal value can only be set (to a value greater than 0) when the Frequency value is Monthly.
• When set, the ordinal value can only be updated to values 0 – 5. 0 – Not using Nth day interval. 1- 5 is equivalent to First - Fifth.
• When the ordinal value is greater than 0 (using Nth day interval for a Monthly frequency), then the DAY value of the recurring model configuration must be the textual value of the day (“Monday”-“Sunday”).

When the ordinal value is greater than 0 (using Nth day interval for a Monthly frequency), then the interval value must be 1 (every month) when using this new configuration. Allowing only 1 as the interval will reduce the complexity so that FTM will process the scheduled payment EVERY 3^rd Friday, 5^th Monday, 1^st Thursday, and so on.

UI updates

The scheduled payment UI screens have been updated to read/save the ordinal configuration as well as display the ordinal option.

The scheduled payments grid in FTM’s Participant Directory has been updated to allow for the displaying of the new ordinal field.  The displaying of the Day field will also be updated for Monthly schedules that are using the ordinal field.  The day value will be displayed as a day of the week (previously displayed only as numeric day of the month).

A new “Nth day interval” checkbox has been added to the scheduled payment details screen.  When this checkbox is unchecked, the screen displays as previous versions. 

• The interval field is displayed.
• The Day(s) field is listed as a numeric selection.

Once the “Nth day interval” checkbox is selected, the fields (and behavior) on the screen are updated. 

• The Interval field (always 1 for Nth day intervals) is replaced with the new Ordinal field selection.
• The Ordinal field will contain selections for First – Fifth. 
• The Day(s) field will have available selections of Monday-Sunday.

---