Fix Readme
Abstract
This document contains version 3.2.8 release information for Financial Transaction Manager for Digital Payments for Multiplatforms.
Content
Financial Transaction Manager for Digital Payments 3.2.8 Release Information
Contents
Common Across Releases
3.2.8.0 Release
3.2.8.1 Release
... 3.2.8.1 interim fix 1
... 3.2.8.1 interim fix 2
... 3.2.8.1 interim fix 3
... 3.2.8.1 interim fix 4
When you upgrade a fix pack or interim fix, in addition to the changes in the level that is being upgraded to, be sure to review the changes in the intermediate fix packs or interim fixes.
Examples:
- Currently, at level fix pack 1 and upgrading to level fix pack 3, review the changes in fix pack 2 and fix pack 3.
- Currently, at fix pack 1 / interim fix 1 and upgrading to fix pack 1 / interim fix 3, review the changes in fix pack 1 / interim fix 2 and fix pack 1 / interim fix 3.
| Back to top |
Common Across Releases
|
Known Issues
Internet Explorer (IE) Issue
FTM does not set the "Cache-Control" and "Pragma" headers on certain responses even if they are defined in the "HTTP Response Headers" section in System Properties screen.
The issue happens only on Internet Explorer browser because of a known Internet Explorer defect, which has no immediate fix date available from Microsoft.
Work around:
Use Firefox or Chrome supported versions to have all headers properly set on all responses
WebSphere Application Server 9.0.x update issue
Automated Deployment Utility workaround:
The interim fix components to update need to be first uninstalled. The tokens file, for example pfs_deploy.xml, contains those interim fix components to update. These components appear in the <install> </install> section. You also need to add these same components in the <uninstall> </uninstall> section.
Before the Console WAR modules are updated, stop the FrameworkUI_EAR application and then proceed as normal. The Engine modules can be updated as normal.
The minimum EWS version required for FTM 3.2.8 is EWS 4.2.
The following is a list of supported EWS notifications and supported EWS SOAP requests.
Supported EWS notifications: OnTokenStatusChangeNotification4.0, OnCustomerChangeNotification4.2, OnPaymentProfileStatusChangeNotification, OnPaymentStatusChangeNotification4.0, OnNewPaymentNotification4.0, OnOrganizationsChangeNotification4.0, OnPaymentRequestChangeNotification2.4, OnNewPaymentRequestNotification4.0 Supported EWS requests: AddPaymentRequest4.1, ChangePaymentRequestRequest4.0, ChangePaymentStatusRequest4.0, DeletePaymentProfileRequest, GetCustomerEventDetailsRequest4.0, GetOrganizationsRequest4.0, GetPaymentRequest4.0, GetPaymentRequestDetailsRequest4.0, GetPendingActivityForTokenRequest3.2, GetTokenHistoryRequest4.1, GetTokenStatusRequest4.2, RegisterTokenRequest4.0, RemoveTokenRestrictionRequest3.10, RequestPaymentsRequest4.0, RestrictTokenRequest3.10, UnregisterTokenRequest3.10, UpdateBusinessPaymentProfileRequest4.0, UpdatePersonalPaymentProfileRequest4.0, ValidateRecipientRequest4.2 Supported EWS RESTful requests: zpss/v1/active-profiles
Feature changes
Fix list and new feature summary
For a list of fixes, see Version 3.2.8 Fix List for Financial Transaction Manager for Digital Payments.
Data Setup Utility
The following documentation describes the changes for the data setup utility (DSU) and the import and export workbooks:
- DSUmigration_v3.2.8.pdf
- DSUMigrationBR_v3.2.8.pdf
These documents are provided in the entitled documentation fix pack. For more information about getting this fix pack, refer to the Entitled Documentation section.
Database migration
For database migration instructions, refer to the migration instructions in {Install location}\shared\vnnn\pfs\Database\db2\{os}\doc
Transaction Server Scheduler XML
The following documentation describes the changes to the scheduler XML for the Transaction Server component:
- TransactionServerSchedulerChanges_v3.2.8.pdf
These documents are provided in the entitled documentation fix pack. For more information about getting this fix pack, refer to the Entitled Documentation section.
Web Services
The following documentation describes the new web services, which are implemented by using IBM WebSphere Application Server Liberty:
- IBM_FTM_Web_Services_v3.2.8.0.pdf
These documents are provided in the entitled documentation fix pack. For more information about getting this fix pack, refer to the Entitled Documentation section.
Entitled Documentation
The entitled documentation fix pack for Digital Payments can be downloaded from Fix Central by using the following link:
3.2.8-FTM-DP-MP-Documents.
General Instructions
Installation
- Start IBM Installation Manager.
- Add the location of the repository that contains the installation package:
- Select File > Preferences.
- Click Add Repository.
- Browse to the directory that contains the repository .zip file and select the file. Click Open and then OK.
- Click Test Connections and then OK.
- Click OK.
- Install the FTM product installation files to your installation directory:
- On the main pane, click Update.
- Select IBM Financial Transaction Manager for Digital Payments, IBM Financial Transaction Manager for Check Services, or IBM Financial Transaction Manager for Corporate Payment Services and then click Next.
- Select the fix pack or interim fix and then click Next.
- Follow the rest of the prompts.
- Confirm that the "Update packages" page shows success.
Deployment
- Do the database migration. Refer to the Database migration section in this document.
- Note: The runtime components can’t be running during the database migration.
- Note: Files can continue to be delivered to the Gateway inbound source folder.
- J2SE components: The installation overlays the J2SE applications, so no special migration instructions are needed. Restarting those applications updates them with the fixes.
- WebSphere Application Server components: You can use the Automated Deployment Utility (ADU), manually upgrade (refer to the update instructions in each WebSphere Application Server component doc folder), or, in a WebSphere Application Server Network Deployment configuration, use the Deployment Manager.
Note: Refer to "WebSphere Application Server 9.0.x update issue" in "Common Across Releases" > "Known Issues".- All WebSphere servers must be restarted after all the components were updated.
- For an interim fix, refer to the fix list for the modules to deploy. Note: Interim fixes are meant to be deployed on an existing WebSphere Application Server profile deployment. If you are using a new WebSphere Application Server profile and already installed the interim fix onto the prior installation, you must do two deployment passes. The first pass is to do the initial, full product deployment. The second pass is to do those components that are affected by the interim fix.
- Update your Transaction Server Scheduler.xml file. Refer to the Transaction Server Scheduler XML section in this document. Note: Updating the scheduler file might not be required for your installation.
- Refer to the release-specific section for any changes that might affect your installation.
- Start your runtime components.
- If you are using the Data Setup Utility (DSU) worksheets capability for managing your data, update your worksheets. For more information, see the Data Setup Utility section in this document.
Locate the WebSphere Application Server Liberty compressed file that is stored in the following path:
<installation directory>/ftm/vxxx/run/liberty
Where xxx = represents current FTM version that is running. For example, 328.
Decompress the file in your preferred path: <liberty-install-directory>. For example, /opt/wlp/.
Follow the following steps to create and configure the server:
1. Create your 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 (refer to the following list of things that need to be modified).
3. Rename that file server.xml
4. Copy server.xml and jvm.options into <liberty-install-directory>/usr/servers/PFSServer.
5. Start your server with <liberty-install-directory>/bin/server start PFSServer --clean (--clean is optional).
Things that need to be modified in the server.xml.template depending on environment details:
- Db2 installation location, database name, and port.
- IBM MQ installation location, queue manager name, user, password, and port.
- The db2admin user and password.
- Set currentPackagePath, currentFunctionPath, and currentSchema to your schema name.
- Set the password for the FTM administrator ID, which is usually fxhadmin.
- WAR file deployment location: the path to the Web Services WAR file <installation directory>/shared/vxxx/pfs/WebServices/Liberty/PFS/WebServices_PFS.war.
Extra parameters might need to be adjusted depending on your usage.
| Back to top |
3.2.8.1 interim fix 4
|
None.
None
None.
| Back to top |
3.2.8.1 interim fix 3
|
None.
None
None.
| Back to top |
3.2.8.1 Release
|
Because the development of releases and interim fixes for maintenance are done in parallel, a later release might not contain every interim fix that was created for an earlier release. The following table shows which releases and interim fix levels can be successfully upgraded to V3.2.8, Fix Pack 1.
In the following table, the "If you're on version" column shows you the releases that can be upgraded successfully. The latest release or interim fix level that can be upgraded for each release is shown in the "To successfully upgrade to V3.2.8.1, your version must be no higher than version" column. If the release that you are upgrading from is at an interim fix level higher than the release or fix level shown in the right column, you can't upgrade the release without losing some changes. The upgrade needs to occur at the next release.
For more information about the individual changes in a release or interim fix, see the fix list for this version.
| If you’re on version | To successfully upgrade to V3.2.8.1, your version must be no higher than version |
| 3.2.5.0 |
3.2.5.0 interim fix 4
|
| 3.2.6.0 | 3.2.6.0 |
| 3.2.6.1 | 3.2.6.1 interim fix 3 |
| 3.2.7.0 | 3.2.7.0 interim fix 1 |
| 3.2.8.0 | 3.2.8.0 |
Known Issues
Held files might be incorrectly flagged as duplicate.
Outbound physical transmissions page might provide more restrictive results to users without entitled access
When a restrictive entitlement is configured, users must be configured to have that entitlement before they can view the entitled data. The outbound physical transmissions page incorrectly restricts the data based on the inbound data fields. So, non-entitled users have a more restrictive view of the outbound physical transmission page.
Feature changes
125847
Zelle Reminder notification for senders with unknown payments about to expire
The Zelle User Experience Guide was updated to change “Payment Sent to Unknown Recipient, Reminder(s) - Notify Sender” from an optional use case to a mandatory use case. The modification to this use case notification is intended to aid in reducing expired payments by notifying the sender to contact the unknown recipient to remind them to enroll in Zelle for the unknown recipient to receive the payment.
The following new Zelle notification API methods were added to the Zelle notification interface:
- public void sendExpirationReminder(CXCPayment cxcPayment)
- public void sendExpirationReminder(CXCPaymentRequest cxcPaymentRequest)
The financial institution (FI) can implement the details of these methods to send a proper upcoming expiration reminder to the originator of the transactions.
The CXCExpirePaymentsTask was updated to include an optional parameter for “Notification reminder days prior to expiration”:
When the “Notification reminder days prior to expiration” parameter is set, the expiration task determines which transactions (payment or payment request) are within the configured interval. For those transactions, the task calls the previous notification UX methods to allow the correct expiration reminder to be sent.
126114
Server-Side Cache for Zelle Ready Contacts
FTM supplies direct web service access to the EWS Zelle Profile Search Service (zpss) through the existing zpssrecipients web service to support Zelle Ready Contacts. This existing web service is a direct pass-through from the mobile application through FTM to EWS. Further guidance from EWS is that the Zelle Ready Contacts should be cached server-side to reduce the traffic to the EWS ZPSS web service and to allow better performance for the mobile application.
FTM added new Zelle Ready Contact web services, which are hosted on IBM WebSphere Application Server Liberty, that allow for the loading, refreshing, or reading of a new Zelle Ready Contact cache.
These new web services are shown in the following list:
- (POST) https://<servername:serverport>/{ftm_participant_id}/contactsload/
Loads the FTM cache with the contact list data from the mobile device.
- (POST) https://<servername:serverport>/{ftm_participant_id}/contactsrefresh/
Refreshes the existing cache with the list of contact data supplied.
- (POST) https://<servername:serverport>/{ftm_participant_id}/contactscheck/
Reads the details of the requested contacts from the existing cache.
The YAML API document for the new Zelle web services, along with other web service API documentation, can be found in the entitled documentation fix pack.
A few Zelle configuration updates in the Liberty server.xml are needed for the Zelle Ready Contacts caching:
- Rename the jmsConnectionFactory from jms/txs/TxsQCF to jms/Zelle/ZelleQCF.
- Add a jmsQueue configuration for jms/Zelle/ZelleQ
- Add a jmsQueue configuration for jms/txs/TxsuiQ
126626
Zelle notification when an originated payment to an unknown recipient was delivered
EWS previously mandated that the sender or originator of a payment to an unknown recipient needs to be notified when that payment was delivered. (EWS UX Guide: Notification for Payment Delivered to Unknown Recipient).
FTM was updated to allow for the financial institution (FI) to provide this information through their notification user exit.
A new UX API was added for:
public void sendUnknownPaymentDelivered(CXCPayment cxcPayment);
This method is called whenever an originated payment that was sent to an unknown recipient is delivered.
The FI can provide the necessary notification messaging to the user.
126825
Zelle: Alerting the client when a contact (recipient) is added or updated.
New methods were added to the Zelle notification user interface (com.ibm.fxh.zel.ui.ejb.sendnotification.service.UserSendNotificationInterface). One to support customer notifications for Zelle recipient addition, one to support Zelle recipient updates, and one to support Zelle recipient deletions.
The add recipient notification is sent when an individual creates a recipient.
The edit/update notification is sent when an individual changes an existing recipient.
The delete recipient notification is sent only when an individual deletes a recipient.
These new methods are shown here:
/**
* This operation is called when a Zelle recipient was added.
* The implementation is responsible for delivering the recipient information to the internal notification system.
* The internal notification system should use the provided details to notify the end bank customer of the
* recipient that is being added.
*
* @param cxcRecipient the recipient that was added.
*/
public void sendRecipientAdded(CXCRecipient cxcRecipient) throws ZelleServiceException;
/**
* This operation is called when a Zelle recipient was edited.
* The implementation is responsible for delivering the recipient information to the internal notification system.
* The internal notification system should use the provided details to notify the end bank customer of the
* recipient that was edited.
*
* @param cxcRecipient the recipient that was edited.
*/
public void sendRecipientEdited(CXCRecipient cxcRecipient) throws ZelleServiceException;
/**
* This operation is called when a Zelle recipient was deleted.
* The implementation is responsible for delivering the recipient information to the internal notification system.
* The internal notification system should use the provided details to notify the end bank customer of the
* recipient that was deleted.
*
* @param cxcRecipient the recipient that was deleted.
*/
public void sendRecipientDeleted(CXCRecipient cxcRecipient) throws ZelleServiceException;
Skeleton methods were added to com.ibm.fxh.zel.ui.ejb.sendnotification.service.UserSendNotification.
Sample methods were added to com.ibm.zel.samples.SampleUXSendNotification.
128514
OAuth support for EWS RESTful web services
EWS began introducing new RESTful API calls that require OAuth authentication tokens to be included in the web service request header. The first of these new RESTful APIs to be used by FTM is the Zelle Profile Search Service (ZPSS) for Zelle Ready Contacts. The API endpoint is defined as shown in the following list:
- (POST) https://<servername:serverport>/zpss/vi/active-profiles
FTM is providing user exit entry points that the Financial Institution can use to integrate into their own internal IT infrastructure to handle authentication (API Gateway, and others) and apply the correct OAuth token to the outgoing EWS web service request.
FTM supplies sample user exit Java classes that provide a standard processing template of how to manage the received OAuth access token along with the provided timeout value. The samples also include (in code comments) the information received from EWS on how the EWS OAuth request needs to be formatted, and other information. It is the responsibility of the FI to update these samples to accommodate their own authentication framework. If no user exit is configured, FTM sends a ZPSS web service API request without an OAuth token, and it is assumed that the internal IT infrastructure of the FI is intercepting the requests and adding the required OAuth token.
FTM has 3 RESTful APIs that make EWS ZPSS API calls. Two of those APIs generate the EWS API call from IBM WebSphere Application Server:
- (POST) https://<servername:serverport>/{ftm_participant_id}/contactsload/
Loads the FTM Zelle Ready Contacts cache with the contact list data from the mobile device.
- (POST) https://<servername:serverport>/{ftm_participant_id}/contactsrefresh/
Refreshes the existing Zelle Ready Contacts cache with the list of contact data supplied.
The third makes a direct call from IBM WebSphere Application Server Liberty:
- (POST) https://<servername:serverport>/{ftm_participant_id}/zpssrecipients/
This request is a pass-through API call that is forwarded to the ZPSS web service, which provides no caching of the results. The results are returned directly to the mobile caller.
With possible calls from WebSphere Application Server and from Liberty, two separate entry points can be configured. If you are using only the caching APIs, you are not required to configure the Liberty OAuth interceptor.
IBM WebSphere Application Server configuration
To configure the FTMh WebSphere Application Server user exit, a few steps are needed.
- Review the com.ibm.zel.samples.SampleUXEWSOAuthRequestFilter Java sample file that is included in the {installDir}/DigitalPayments/{version}/RTP/Samples/Zelle directory.
- Update the sample as needed for the environment of the financial institution (FI). The resulting class must implement the com.ibm.fxh.zel.userexit.ws.filter.UserClientRequestFilterInterface. The sample class extends the com.ibm.fxh.zel.userexit.ws.filter.UserClientRequestFilter concrete class that provides database connection handling and an empty “filter” method, so it is recommended that any changed (or new) user exit maintains that hierarchy.
- Review the readme.txt file that is included with the samples for how to correctly compile the sample into a JAR file.
- Compile the sample and place the resulting JAR file into the correct shared library path for the zelConsole.
- Update the “EWS Web Service Client Filter” core property with the resulting Java class name that was generated during implementation. The property is in the FTM user interface at Administration > Components > Zelle > General Properties.
- Start, or restart, the RTP UIEJB EAR.
After it is successfully configured, the sample user exit is called whenever the contactsrefresh or contactsload APIs make EWS ZPSS active-profiles API requests.
Liberty configuration
A new com.ibm.fxh.jaxrs.sdk.userexits.SampleEWSOAuthRestfulInterceptor sample is included in the {installDir}/shared/{version}/pfs/SDK/WebServices directory. For more information about how to compile install the supplied interceptor, refer to the “IBM Financial Transaction Manager {version} Web Services” document in the entitled documentation fix pack.
Migration
- DSUmigration_v3.2.8.pdf
- DSUMigrationBR_v3.2.8.pdf
These documents are provided in the entitled documentation fix pack. The entitled documentation fix pack for Digital Payments can be downloaded from Fix Central by using the following link:
3.2.8-FTM-DP-MP-Documents.
| Back to top |
3.2.8.0 Release
|
Because the development of releases and interim fixes for maintenance are done in parallel, a later release might not contain every interim fix that was created for an earlier release. The following table shows which releases and interim fix levels can be successfully upgraded to V3.2.8.0.
In the following table, the "If you're on version" column shows you the releases that can be upgraded successfully. The latest release or interim fix level that can be upgraded for each release is shown in the "To successfully upgrade to V3.2.8.0, your version must be no higher than version" column. If the release that you are upgrading from is at an interim fix level higher than the release or fix level shown in the right column, you can't upgrade the release without losing some changes. The upgrade needs to occur at the next release.
For more information about the individual changes in a release or interim fix, see the fix list for this version.
| If you’re on version | To successfully upgrade to V3.2.8.0, your version must be no higher than version |
| 3.0.2.0 | 3.0.2.0 interim fix 2 |
| 3.0.2.1 | 3.0.2.1 interim fix 23 |
| 3.0.4.0 | 3.0.4.0 interim fix 3 |
| 3.0.4.1 | 3.0.4.1 interim fix 1 |
| 3.2.0.0 | 3.2.0.0 interim fix 1 |
| 3.2.0.1 | 3.2.0.1 interim fix 2 |
| 3.2.1.0 | 3.2.1.0 interim fix 3 |
| 3.2.2.0 | 3.2.2.0 interim fix 5 |
| 3.2.2.1 | 3.2.2.1 interim fix 3 |
| 3.2.3.0 | 3.2.3.0 interim fix 5 |
| 3.2.4.0 | 3.2.4.0 interim fix 7 |
| 3.2.5.0 |
3.2.5.0 interim fix 2
|
| 3.2.6.0 | 3.2.6.0 |
| 3.2.6.1 | 3.2.6.1 interim fix 2 |
| 3.2.7.0 | 3.2.7.0 |
Known Issues
Held files might be incorrectly flagged as duplicate.
Outbound physical transmissions page might provide more restrictive results to users without entitled access
When a restrictive entitlement is configured, users must be configured to have that entitlement before they can view the entitled data. The outbound physical transmissions page incorrectly restricts the data based on the inbound data fields. So, non-entitled users have a more restrictive view of the outbound physical transmission page.
Feature changes
WebSphere Application Server Liberty Update
Gateway Server changes
Gateway Server now supports ingesting 'stacked' NACHA files. A 'stacked' NACHA file is multiple logical NACHA files concatenated to each other in one physical file. Gateway Server processes these files by breaking one apart into its logical files and processing them independently in file threads. Similar to Fragmentation, Gateway Server stops processing other physical files when it is dealing with a stacked NACHA file.
FTM user interface changes
The FTM user interface now supports concatenated NACHA files, also referred to as stacked NACHA files. The inbound physical transmissions page shows one record for each stacked file regardless of how many transmissions are contained within it. These records show blank values for the sender, sender ID, processor, processor ID, and control total values apart from the payment standard.
The inbound physical transmission page ‘View Transaction Server UI/Distribution UI Data’ link is modified. This link still goes to the transmission hierarchy page for non-concatenated physical transmissions. For concatenated or stacked physical transmissions, it loads the inbound transmissions page with a filter applied that shows only the transmissions in the selected concatenated file.
Previous release did not support SSL RMI communication.
Resolution:
Added SSL RMI communication for Distribution Manager, Gateway Server, Transaction Server RMI interfaces.
Setting up SSL connection for RMI between these applications and WebSphere Application Server:
The following new properties were added to Distribution Manager, Gateway Server, and Transaction Server.
remoteSSLEnabled - true/false, whether to enable SSL for RMI or not
remoteKeyStore - location of a keystore for the application
remoteKeyStorePassword - password for the keystore
remoteKeyStoreFormat - JKS, which is a keystore format
remoteTrustStore - location of a truststore for the application
remoteTrustStorePassword - password for the truststore
remoteTrustStoreFormat - JKS, which is a truststore format
Example:
remoteSSLEnabled = true
remoteKeyStore = c:/IBM/Key/server/keyStore.jks
remoteKeyStorePassword = server
remoteKeyStoreFormat = JKS
remoteTrustStore = c:/IBM/Key/server/trustStore.jks
remoteTrustStorePassword = server
remoteTrustStoreFormat = JKS
Note: If you prefer to use different keystore and truststore files for the individual applications, make sure to add all extracted certificates to the WebSphere truststore.
For more information, refer to the Financial Transaction Manager documentation.
With TCH Spec 2.9, it is now possible for TCH to send a acmt.022 Token Notification Message to the originator for pacs.008 and pain.013 messages if the recipient signs up for TCH's Secure Token Exchange. If FTM for Immediate Payments receives a acmt.022 message, it attempts to update the participant's (originator) recipient entry with the token account and token bank code provided in the acmt.022 message.
Early Warning Services (EWS) mandated that when a Zelle payment is initiated to a token provided through a QR code, the sending or originating organization includes that information to EWS through the ValidateRecipient API in the recipient information.
FTM provides a new “scannedQRCode” parameter in the create Zelle Payment and Payment Request web service APIs to denote those transactions where the recipient or responder token was provided by a QR code. The new parameter must be supplied on the create request and cannot be updated. The scannedQRCode value is returned on all read payment and payment request APIs. The value is also displayed in the Zelle tab of the transaction details user interface page.
FTM uses this new scannedQRCode field to set the “located by QR code” field in the EWS ValidateRecipient API call when it creates a payment or a payment request.
For more information about the new scannedQRCode field, refer to the Zelle RESTFul API Documentation PDF document that is available to entitled customers. This document is provided in the entitled documentation fix pack, which is described in the Entitled Documentation section of this release information.
Early Warning Services (EWS) mandated that its MatchRecipient APIs are deprecated and should no longer be used. It is replaced by two APIs to use instead. The GetTokenStatus API is described as a lighter weight API and should be called in non-payment workflows (participant token registration, recipient list management, and so on). The ValidateRecipient API is described as a deeper validation and should be used only within payment and payment request workflows.
FTM is updated so that the MatchRecipient API is no longer called, and the appropriate API (GetTokenStatus/ValidateRecipient) replacement is introduced. There are no API changes to existing FTM web services. The changes are limited to the communication between FTM and EWS.
However, these API changes cause a few changes in behavior.
The ValidateRecipient API requires a “directory reference number” field, which should be the network ID for the payment/payment request that matches the API request. This requirement caused an FTM process change. Previously, FTM created the network ID by concatenating the default organization ID with the FTM payment ID after the payment was created in the FTM database, which occurs AFTER the call to the MatchRecipient/ValidateRecipient. So, this process is changed so that the network ID is created before the payment/payment request being inserted into the FTM database. The format remains the same, but a different identifying sequence is used when it is concatenated with the default organization ID.
Since the GetTokenStatus is a lighter weight API than MatchRecipient, the GetTokenStatus response does not contain all the same information that was included on the MatchRecipient API response. This lack of information returned from EWS impacts the information stored for Zelle recipients because that information is no longer returned on the GetTokenStatus. The following Zelle recipient attributes are no longer stored or updated in the FTM database since they are no longer returned on the GetTokenStatus API response:
- acceptanceMode
- canReceiveExpeditedPayments
- enforceNameMatching
- ignoreNameMatch
- paymentProfileID
- recipientID
The affected workflows and deprecated fields are documented in the Zelle RESTFul API Documentation PDF document that is available to entitled customers. This document is provided in the entitled documentation fix pack, which is described in the Entitled Documentation section of this release information.
OnCustomerChangeNotification4.2
In addition to the MatchRecipient API removal, the FTM-supported version of the OnCustomerChangeNotification was upgraded to OnCustomerChangeNotification4.2. In addition to customer deactivations, EWS sends the OnCustomerChangeNotification4.2 notification when a customer is restricted or when a restriction is removed from a customer.
When EWS notifications are received, the message driven bean (MDB) was enhanced to log only the message text of the received JMS message when the "finer" level WebSphere Application Server trace is enabled. This new message does not include the JMS header information, allowing the full text body of the message to be logged to the WebSphere trace.log for debugging and monitoring purposes. If the "finest" or "all" trace levels are used, the existing log message, which includes JMS header information, and the new message are logged to the WebSphere trace.log.
It is recommended to use the following WebSphere trace string to target this message for production debugging and monitoring use:
com.ibm.fxh.zel.ui.mdb.ZelleNotificationMDB*=finer
APIs: Need pacs.002 content returned on web service API response (sync mode) and a way to obtain the pacs.002 content for async mode or APIs without sync/async
The readInboundTransactions web service was enhanced to provide more information back to the caller.
The optional input parameter "Extension" was extended to support two new values "ERROR_DATA", and "ALL", in addition to "RELATED_TRANSACTION" that it previously supported.
If "ERROR_DATA" is specified and the transaction specified on the call has errors that are associated with it, they are returned in response in an Error_data structure that contains the error_code, a brief description of the error, and a detail description of the error. If multiple errors are associated with the transactions, they all are returned.
If "RELATED_TRANSACTION" is specified and the transaction specified on the call has transactions that are related to it, they are returned in the response in a related_transactions structure. This structure was enhanced to include the raw_data associated with the related transactions.
If "ALL" is specified, then the response contains both the error_data and the related_transactions structures.
Overview
New web service APIs to allow optional and conditional fields were added. These changes are needed to enable the customer to fully leverage these messages for TCH RTP version 2.9 work and other payment schemes in the future.
The new web service APIs are:
- Initiate Request For Payment
- Request Return Of Funds
- Response To Request For Payment
- Response To Request For Return Of Funds
Web service integration
New web services
The following new web service APIs are available for transactions.
- POST (/transactions/initiaterequestforpayment_v2) Initiate a request for payment.
- POST (/transactions/reqretfunds_v2) Request for return of funds.
- POST (/transactions/responsetorfp_v2) Response to request for payment.
- POST (/transactions/responsetorrof_v2) Response to request for return of funds.
Read more about these web services in the open API web service documentation (http://localhost:57107/openapi/ui/).
Deprecated web services
The following web service APIs are deprecated.
- POST /ws/svc/initiaterequestforpayment/ (Use /transactions/initiaterequestforpayment_v2)
- POST /ws/svc/reqretfunds/ (Use /transactions/reqretfunds_v2)
- POST /ws/svc/responsetorfp/ (Use /transactions/responsetorfp_v2)
- POST /ws/svc/responsetorrof/ (Use /transactions/responsetorrof_v2)
Response To Request For Payment API
Overview
The Response to Request for Payment message is used to provide a business response to a Request for Payment (pain.013) message in two scenarios:
- The debtor schedules a payment for a future date and time
- The debtor FI renders the Request for Payment unpayable before the expiry date included in the original request
If the debtor scheduled the payment for a future date and time, the Response to Request for Payment message is sent with the status ACTC. It includes details regarding the conditions of the payment (that is, date and time and amount of the scheduled payment, guaranteed payment indicator).
The debtor FI might render the Request for Payment unpayable before the expiry date included in the original request for several reasons (for example, account is closed while the Request For payment is still unpaid, account holder indicates payment is not going to be made). In this case, the Response to Request for Payment message is sent with the status RJCT with a reason code indicating the reason for the rejection.
Response To Request For Payment needs to support the following changes that were made available in TCH version 2.9:
- Proprietary reason codes
- Payment amounts different from the requested amount
- Flag for guarantee payment
- Flag for early payment indicator
JSON parameters
The parameters must use the following naming convention. Multiple word parameters must be separated by an underscore.
{
“accepted_amount”:,
"audit_source":,
"asynchronous":,
"additional_info":,
"action":,
“currency”:,
“guaranteed_payment”:,
“early_payment:,
"ids": [
{"ftm_transaction_id": }
],
“proprietary_code”:,
"reason_code": ,
“requested_execution_date”:,
"comment_and_contact": {
"contact_name": ,
"comment":,
"contact_phone":
},
"timeout":,
"initiator_type":
}
Mandatory parameters
The following input parameters are mandatory: ids, initiator_type, and action.
New JSON parameters
|
Input |
Description |
Type |
Required |
|
accepted_amount |
Amount accepted to be paid. |
Decimal |
No |
|
currency |
The currency of the accepted_amount. |
String |
No |
|
guaranteed_payment |
Indicates whether a payment guarantee request is granted or not. Default is false. |
Boolean |
No |
|
early_payment |
Indicates whether the debtor pays before the requested execution date. Default is true. |
Boolean |
No |
|
proprietary_code |
Proprietary reason code for the reject of the original instruction |
String |
No |
|
requested_execution_date |
This field is used to provide the date on which the payment was scheduled. |
Date |
No |
Parameters validation
If the action value is “Reject”, the following validations are done:
- A value must be provided for either the reason_code or proprietary_code parameters, but not both
- If reason_code is provided, it must be AC06, AM09, CH11, MD07, DS04, NARR, CUST, BE04, BE07, AM14, AG01, or AG03
- If reason_code is NARR or proprietary_code is 1100, then the additional_info field must not be null
- The accepted_amount, currency, guaranteed_payment, early_payment, and requested_execution_date fields should be null or default values
If the action value is “Accepted”, the following validations need to be done:
- The reason_code, proprietary_code, and additional_info fields should be null
- All other fields are optional
Response To Request For Return Of Funds API
Overview
The Response To Request For Return Of Funds message indicates the outcome of the creditor FI’s investigation following a Request for Return of Funds message.
Possible outcomes include:
- Funds are returned in full by using RTP credit transfer
- Partial funds are returned by using RTP credit transfer
- Funds are returned in full by using another payment channel (can be used only by participants who receive only)
- Partial funds are returned by using another payment channel (can be used only by participants who receive only)
- Funds are not returned as a result of the investigation
JSON parameters
The parameters must use the following naming convention. Multiple word parameters must be separated by an underscore.
{
"action": ,
"additional_info":,
"amount":,
"asynchronous":,
"audit_source":,
"cancelation_status_id":,
"clearing_channel":,
"comment_and_contact": {
"contact_name": ,
"comment":,
"contact_phone":
},
"currency":,
"ids": [
{"ftm_transaction_id": }
],
"initiator_type": ,
"reason_code":,
"settlement_date":,
"timeout":
}
Mandatory parameters
The following input parameters are mandatory: ids, initiator_type, and action.
New JSON parameters
|
Input |
Description |
Type |
Required |
|
settlement_date |
Indication of the date on which the return is intended to be settled. |
Date |
No |
|
amount |
Amount to be returned |
Decimal |
No |
|
currency |
The currency of the amount |
String |
No |
|
clearing_channel |
Indicates the channel on which the return is processed:
RTNS - RealTimeNetSettlementSystem (CHIPS) |
String |
No |
|
cancelation_status_id |
When funds are returned outside of RTP, the unique identifier of the transaction used to return the funds must be included in this field |
String |
No |
Parameters validation
Validation of the request is done based on the value in the action field, which must be one of the specified values.
If the action field is “Accept”, the following validations need to be done:
- Amount, currency, reason_code and additional_information fields must be null
- If clearing_channel is not null, it must be MPNS, RTGS or RTNS, and the cancelation_status_id field cannot be null
If the action field is “Reject”, the following validations need to be done:
- Amount, currency, settlement_date, clearing_channel and cancelation_status_id fields must be null
- Reason_code cannot be null and must be ARDT, AC04, CUST, AM04, LEGL, NOAS, or NOOR
Before Db2 version 11.5, the Db2 installation installed the db2jcc.jar and db2jcc4.jar driver files. Starting with Db2 11.5, the Db2 installation no longer installs the db2jcc.jar.
However, a slight behavior change between these two drivers affects FTM. The columnName and columnLabel values retrieved from database queries are equivalent when the db2jcc driver is used. When the db2jcc4 driver is used, these two values might be different.
For example, consider this query: SELECT COLUMN1 AS MY_VALUE FROM XYZ
When the db2jcc.jar is used, the getColumnName and getColumnLabel APIs return the same value ("MY_VALUE").
When the db2jcc4.jar is used, the getColumnName API returns "COLUMN1" and the getColumnLabel API returns "MY_VALUE".
FTM was updated to ensure that existing queries are processed correctly, regardless of which database driver is used.
To use the db2jcc4 driver, the configuration and installation of the WebSphere FTM JDBC providers were updated to be "DB2 Using IBM JCC Driver" (uses "{DB2_JCC_DRIVER_PATH}" class path variable) instead of "DB2 Universal JDBC Driver Provider" (uses "{DB2UNIVERSAL_JDBC_DRIVER_PATH}" class path variable)
All of the J2SE applications class paths were updated to use db2jcc4.jar.
TCH RTP: Pain001 message type should be displayed in DP-UI
The PAIN001 message type was renamed to pain.001 to keep in line with the naming convention of other ISO20022 message types. Required migration instructions are included in the DSU Migration documents.
-'Business Date' equal to current business day
-'Transmission Received' in the 'past five minutes'
This filter returns transactions that were received within the past five minutes of loading the page. The following screen capture shows how the new default filter appears in the user interface.
Before this change, the Inbound Transactions default filter contained only business date and looked like the following screen capture.
CLIENT_CERT authentication in Liberty web services
In version 3.2.8 and later, FTM now supports CLIENT_CERT authentication for all web services components. General instructions on how to configure this authentication is available in the FTM documentation.
Supported components:
WebServices_BusinessRules
WebServices_Gateway
WebServices_PFS
WebServices_EAR (Engine)
Note: WebServices_EAR (Engine) no longer displays a login page by default. This authentication now defaults to a BASIC authentication, which opens a dialog for the user to enter credentials when the web services are accessed by using the FTM web services browser (ws/svc).
Starting with version 3.2.8.0, FTM supports entitlements. Entitlements are a way to enforce restrictions, or entitlements, on users and groups. Entitlements based on its type and configuration, can restrict or enable users from seeing certain sensitive data on user interface pages and the web services. Support for entitlements is going to be delivered in multiple releases. For 3.2.8.0, the following features are added:
- Entitlement configuration is available by using the DSU worksheets only. Instructions and sample scenarios are available in the entitled documentation fix pack. For more information about getting the fix pack, refer to the Entitled Documentation section of this release information.
- Entitlement configuration supports only "GLOBAL_UI_RUNTIME_GRID" for the Resource value, which applies the entitlements globally across the following payment data user interface pages.
- Inbound: Physical Transmissions, Transmissions, Batches, Processing Batches, and Transactions
- Outbound: Physical Transmissions, Transmissions, and Batches.
- Entitlement configuration supports only "GLOBAL_BANK_ID" for the Criteria value, which applies to the following columns on the user interface pages:
- Inbound: Sender ID, Processor ID, Sender Alias, and Processor Alias (where available).
- Outbound: Receiver
- Entitlement configuration supports only "EQUAL_TO" and "NOT_EQUAL_TO" for Operator values.
User interface page screen captures from the sample scenarios
Instructions for configuring entitlements and sample scenarios are available in the “Sample Entitlements DSU Instructions” document.
Note: Depending on the default initial configuration, settlement posting files and transmission acknowledgment files might not be visible or generated in customer’s environment. The Outbound Physical Transmissions page might show different records based on which Outbound Transmissions are built and transmitted.
Inbound Physical Transmissions
Without entitlements
With entitlements (fxhadmin)
With entitlements (izhadmin)
Inbound Transmissions
Without entitlements
With entitlements (fxhadmin)
With entitlements (izhadmin)
Inbound Batches
Without entitlements
With entitlements (fxhadmin)
With entitlements (izhadmin)
Inbound Transactions
Without entitlements
With entitlements (fxhadmin)
With entitlements (izhadmin)
Outbound Physical Transmissions
Note: The data on this page shows the transmissions that are built and transmitted from the Outbound Transmissions page.
Without entitlements
With entitlements (fxhadmin)
Note: No entries were restricted because none of the entries have ‘011000028’ in either the ‘Sender ID’ or ‘Processor ID’ columns.
With entitlements (izhadmin)
Note: No entries were visible because none of the entries have ‘011000028’ in either the ‘Sender ID’ or ‘Processor ID’ columns.
Outbound Transmissions
Without entitlements
With entitlements (fxhadmin)
Note: No entries were restricted because none of the entries have a ‘Receiver’ column RT number of ‘011000028’.
With entitlements (izhadmin)
Note: No entries were visible because none of the entries have a ‘Receiver’ column RT number of ‘011000028’.
Outbound Batches
Without entitlements
With entitlements (fxhadmin)
Note: No entries were restricted because none of the entries have a ‘Receiver’ column RT number of ‘011000028’.
With entitlements (izhadmin)
Zelle: Track number of payments sent to recipients
Starting with version 3.2.8, FTM for Digital Payments (Zelle) supports tracking the number of payments that were sent to recipients.
- The counter is updated on a successful CXCPayment POST (create) web service.
- The counter is now available for consumption on CXCRecipient READ web services.
- For more information about the changes and specifications, refer to the specific sections for these web services in the Zelle RESTFul API Documentation PDF document that is available to entitled customers. This document is provided in the entitled documentation fix pack, which is described in the Entitled Documentation section of this release information.
For example, both “Mom” and “Dad” are listed separately in the recipient list, but both entries use the same email token.
The EWS User Experience guide was since updated so that duplicate or shared tokens are not allowed within the recipient list of a Zelle user.
FTM was updated to restrict the Zelle recipient list to ensure that a recipient token is only allowed one time within the recipient list of a participant, regardless of the given name or surname.
Product configuration
The duplicate recipient check behavior is controlled by a Zelle system property (Administration->Components->Zelle->General) that can be turned on and off. The property is defined as:
Allow shared recipient tokens
If this property is set to no, FTM does not allow redundant tokens to be entered into the recipient list of a Zelle participant. If it is set to yes, FTM allows the same recipient token to be created within the recipient list of a Zelle participant with different given name or surname values.
The property has a default value of ‘No’. This new property is cached, so any change to the setting requires the Zelle application to be restarted to cache the new value.
Add recipient behavior
When a participant creates a recipient by using a web service, FTM detects whether an existing recipient exists. If so, FTM returns an error code of 160300 (“Failed to add recipient due to duplicate recipient detection”).
This duplicate logic is updated to make use of the new “Allow shared recipient tokens” property. If the core property is no, the duplicate query defines a duplicate recipient to be any existing recipient in the Zelle participant’s recipient list that matches the token that is being added (regardless of given name or surname). If the core property is yes, the duplicate recipient query logic is unchanged from the previous process.
For example, assume a token of “mom_dad@example.com”.
With the new property set to no, a new recipient of “First Name – Mom, Token – mom_dad@example.com” can be added to the recipient list of the participant. However, a subsequent recipient of: “First Name – Dad, Token – mom_dad@example.com” returns a 160300 error code (token matched).
With the new property set to yes, both recipient entries are allowed. Only another addition of “First Name – Mom, Token – mom_dad@example.com” causes the 160300 error code to be returned (given name and token matched).
FTM was updated to provide this expanded functionality. A new RESTful web service interface, which is hosted on an IBM WebSphere Application Server Liberty server, is supplied.
This new POST web service requires an FTM participant ID parameter as well as the list of tokens to be validated or verified through the EWS ZPSS web service. Any tokens registered at EWS return the recipient type (PERSON or BUSINESS) of the token as well as the photo URL that was defined for the token (if any).
It is assumed that the internal IT infrastructure (API Gateway, other) of the financial institution injects any web service authentication (Basic, OAuth, JWT, and so on) that is required by EWS to allow for successful web service connectivity between FTM and Early Warning Services.
The YAML API document for the new Zelle web service can be found in the entitled documentation fix pack. For more information about getting the entitled documentation fix pack, refer to the Entitled Documentation section of this release information.
Migration
- DSUmigration_v3.2.8.pdf
- DSUMigrationBR_v3.2.8.pdf
These documents are provided in the entitled documentation fix pack. The entitled documentation fix pack for Digital Payments can be downloaded from Fix Central by using the following link:
3.2.8-FTM-DP-MP-Documents.
Was this topic helpful?
Document Information
Modified date:
18 February 2022
UID
ibm16456977