SaFi Bank Space : Paynamics response code mapping

Requirements

There are hundreds of different response codes, and the response codes may be modified or expanded.
Will convert response codes to user friendly message when reverting back to the receivers/users.
We only need to support ONE locale.
Different integration services (i.e., payment aggregator/partner/merchants) will have different response codes and messages.
As a message mapping/processing service, we will include information on whether a response code/message is successful or not.
If some external services does not have any response code, we will use the response message instead. It will be generic if the service only provides the HTTP code without any response message.
We will use the most specific code available. For example, BN Instapay have HTTP response code and ISO20022 formatted response code. In this case we will use the ISO20022 formatted response code.

Technical analysis

To support changeability, we plan to store these mappings in a relational DB.
To support i18n, store different mappings in a single table (may be normalized) for the different integration services.
How to wrap raw response code to mapped messages?
1. Single service, this can be called by different services, if different services have their own messages;
2. As a component, just called by PaynamicWorkflowRestClient, if different services using the same message.
3. By AOP, no need to modify PaynamicWorkflowRestClient business code, and will available depending on the configuration.
For performance optimization, we can use cache to store mappings.
1. depends in the sense that it’s more read than modify;
2. will load the mappings from normal database when startup;
3. cached keys and values should be updated when there is a change in the database
4. will allow reload consider expiration time - need to keep data fresh since expiration does not completely solve this issue

Sequence for mapping service

Functional design

Data structure

field	specification
id
integration_gateway	paynamics-bills
response_code	If this is null, the response_message should be available.
tone
response_message	If this is null, the response_code should be available.
response_description	meaning in paynamics May not be available in other merchants
status	Success, Failed, Pending (see TransactionStatus enum)
user_message
version	small int - no frequent internal tracking only (not app version) - automated/increment no need for tracking old values - traceable through logging
created_at
updated_at
deleted_at

ERD

index

unique index for integration_gateway, response_code, response_message (and tone?)

cache

key: response_message_mapping

type: hashmap

values:

{
"<integration_gateway_response_code_response_message_tone>":"<user message>",
...
}

Mapping Service/Component

Input: raw_response (with response_code/response_message & tone), integration_gateway

Sample WorkflowResponseDto (Raw Response)

{
  "status" : "FAILED",
  "paymentActionInfo" : "/url", // link to redirect url
  "response_message" : "Transaction Declined Dispute Date Error",
  "response_id" : "response123",
  "request_id" : "request123"
}

Output: mapped_response (i.e., raw_response + user_message + status)

{
  "status" : "FAILED",
  "paymentActionInfo" : "/url",
  "response_message" : "Transaction Declined Dispute Date Error",
  "response_id" : "response123",
  "request_id" : "request123",
  "user_messsage": "Your transaction has been declined because there was an error in the dispute date."
}

Rest API Endpoints

GET /response-messages/system

Sample response body:

[
  {
    "integration_gateway" : "paynamics",
    "response_code" : "GR0078",
    "response_message" : "Transaction Declined Dispute Date Error",
    "response_description" : "This means that the dispute start date or dispute end date that was sent to the request was not valid entry.",
    "status" : "FAILED",
    "userMessages": [{
      "userMessage" : "The dispute start/end date is invalid.",
      "tone" : "informal",
    },{
      "userMessage" : "Invalid dispute start/end date.",
      "tone" : "formal",
    }]
    "version" : 1
  },
  ...
]

Get by composite key: POST /response-messages/system/{integrationGateway}

Body:

{

responseCode : <optionalResponseCode>,

responseCode : <optionalResponseCode>

}

Save/Update: POST /response-messages/system

Sample request body:

{
  "integration_gateway" : "paynamics-workflow",
  "response_code" : "GR001",
  "response_message" : "Transaction Successful",
  "response_description" : "Transaction is approved",
  "userMessages" : {
    "tone" : "formal",
    "userMessage" : "Transaction successful",
  }
  "status" : "SUCCESS"
}

DELETE /response-messages/system/{integration-gateway}/{tone}/{response-code}

The way to realization

Option 1: Create a Mapper<Raw, Mapped> interface, which includes:

Fields - raw, mapped
Method - Mapped convert(Raw)

This will be implemented for each integration. For example, PaynamicsMapper<WorkflowResponseDto, MappedWorkflowResponseDto> implements Mapper.

The convert method uses varying filters depending on which integration is used.

Option 2: Create a RawResponse interface that includes a convert method, which returns the MappedResponse object

For example, WorkflowResponseDto should implement the RawResponse interface providing its implementation of the convert method

In Options 1 and 2, the interfaces can be defined in a common “service”.

[IMPLEMENTED] Option 3: AOP approach

Create an Aspect class for the Mapper and configure it so that it is executed after the integration endpoint is invoked. Can we return the output of the Aspect class? Will this work across different services?

Architecture of mapping service

More suggestions

As we expected before, this service not only serve Paynamics but also for other outside services. It’s more reasonable to create a single microservice module than combined in paynamic-gateway module.
The basic task of this module is to maintain response code mappings, support for update/retrieve/query by condition and so on.
To make this mapping service simpler to use and transparent to service customer, we can create a message convert util based on AOP, basic rule as following.
1. Create a Base mapping class, including response code, integration gateway, tone, friendly message, status.
2. All those gateway services response class should extend this Base mapping class.
3. Gateway method which needs to be converted to mapping messages, should return the subclass of Base mapping class and must use annotation, e.g., @MessageMapping.
4. Message convert util will set a cut point on those method which are annotated by @MessageMapping. Before those method return, convert util will try to inject the friend message to return object.
5. Message convert util will request friendly message by using httpclient. And all this jobs is transparent to gateway methods.
After all of those implementions, if we need to add one more gateway service to support message mapping, all the jobs to do is make return type extends base mapping class, and annotate method with @MessageMapping.

Others

Do these 2 tickets cover the same set of tasks? Confirming that the expected output is the code for Mapper setup. Does this include modifying existing sendRequests so that responses have already been converted?

https://safibank.atlassian.net/browse/SM-2269

https://safibank.atlassian.net/browse/SM-2270

In the transactions processor manager, there is already a package called mapper. A sample interface under this package is EWalletTopUpMapper. There is some similarity to the goal of these tickets.

From "BN Instapay Message Implementation Guideline ISO 20022 v1.4.9.1 CLEAN.pdf", check codes from pages 178 or 181 onwards. Here are some sample codes from the file:

Code

Message/Meaning

Field Type

camt.026.001.07

Unable to Apply (Request for Information) - V07

pacs.002

Original Message Name Identification

AB01

AbortedClearingTimeout