DESIGN DOCUMENT
FOR
REGISTER INTENT
Table of Contents
1. Introduction.................................................................................................................................... 3
1.1 Purpose...................................................................................................................................3
1.2 Scope...................................................................................................................................... 3
1.3 Document Ownership.............................................................................................................3
2 API/Service Definition.....................................................................................................................4
3 API/Service Method Definition....................................................................................................... 5
3.1 POST/registerIntent................................................................................................................ 5
3.1.1 Implementation.............................................................................................................. 5
3.1.2 Method Design................................................................................................................5
3.1.3 Summary.........................................................................................................................6
3.1.4 Request Schema..............................................................................................................6
3.1.5 Response Schema........................................................................................................... 7
3.1.6 Response Mapping......................................................................................................... 9
3.1.7 Error Handling...............................................................................................................10
3.1.8 Logging..........................................................................................................................10
4 API/Service NFR............................................................................................................................ 10
4.1 Security................................................................................................................................. 11
4.2 Performance......................................................................................................................... 11
4.3 Exception and Error Handling............................................................................................... 11
4.4 Application Monitoring.........................................................................................................11
4.5 Build and Deployment Solution............................................................................................ 11
4.5.1 Code Versioning............................................................................................................ 11
4.6 Tools and Technologies......................................................................................................... 11
4.6.1 Development Tools....................................................................................................... 11
4.6.2 Technologies................................................................................................................. 11
5 Testing...........................................................................................................................................11
5.1 Testing Approach.................................................................................................................. 11
5.2 Functional Testing................................................................................................................. 12
5.3 Non-Functional testing......................................................................................................... 12
5.4 Testing Tools..........................................................................................................................12
5.5 Mocking frameworks............................................................................................................ 12
1. Introduction
1.1 Purpose
The purpose of this document is to provide the detailed design for the Register Intent endpoint along
with the interaction methods. It provides request and response structure and also the non-functional
requirements like debug logging, error/exception handling and Security.
This operation is managed in experience, process and system layer, with each API receiving the same
request payload. Therefore, this document serves as the combined design document for the three
API.
1.2 Scope
This document only covers details around x-portal-autopayyesbank-api,
p-portal-autopayyesbank-api and s-portal-autopayyesbank-api that will be used to perform the
following operations.
● POST Register Intent.
o Requesting to get payment link details from system API.
1.3 Document Ownership
Document Author PRANAV
Document Reviewer SUREKA SURESH
Document Approver
2 API/Service Definition
API/ Experience API to perform Process API to perform the System API to perform the
the Register Intent request. Register Intent Request Register Intent Request
Service
Title
API/ x-portal-autopayyesbank-a p-portal-autopayyesbank-api s-portal-autopayyesbank-api
pi.raml
Service
Name
API/ 1.0 1.0 1.0
Service
Version
Brief This API exposes Register This API exposes Register This API exposes Register
Intent Details – Intent Details – Intent Details –
Descrip - To GET Payment - To GET Payment Link - To GET Payment Link
tion Link details details details
Summ Following are the Following are the operations Following are the operations
operations exposed exposed through this API: exposed through this API:
ary of through this API: ● POST/registerIntent – ● POST/registerIntent –
Metho ● POST/registerInten Get thepayment link Get thepayment link
ds t – Get details from target details from target
thepayment link system via system system via system
details from target API. API.
system via system
API.
Criticali High High High
ty
Layer/ Experience Process System
Catego
ry
Usage Real Time Real Time Real Time
Domai YES (mule-app-domain) YES (mule-app-domain) YES (mule-app-domain)
n
Base Dev:http://Mulesoft-Dev-7
43329365.ap-south-1.elb.a
URI mazonaws.com/apy/ux/1.0
/registerIntent
UAT:
https://uat-api.fsbl.in/apy/
ux/1.0/registerIntent
PROD :
https://api.fivestar.in/apy/u
x/1.0/registerIntent
Transp HTTP HTTP HTTP
Port number: Port number: Port number:
ort Dev: 8440 Dev: 8440 Dev: 8440
Protoc UAT: 8440 UAT: 8440 UAT: 8440
ol(s) PROD: 8440 PROD: 8440 PROD: 8440
Service SLA is valid if there are no SLA is valid if there are no SLA is valid if there are no
Level re-connection attempts re-connection attempts re-connection attempts
required to connect to the required to connect to the required to connect to the
Access downstream system. If a downstream system. If a downstream system. If a
(SLA) re-connection is attempted, re-connection is attempted, re-connection is attempted,
the response time will the response time will include the response time will include
include the frequency and the frequency and retry delay. the frequency and retry delay.
retry delay.
3 API/Service Method Definition
3.1 POST /registerIntent
3.1.1 Implementation
● Common logger framework should be used for standard logging across all the entry, process and exit
point as per the best practices.
● All component naming should be done as per the best practices.
● This API method accepts encrypted request over HTTP endpoint.
● The request is validated against the mapping sheet and an error response is returned if validation fails.
● The timeout properties on experience API should be configurable. Actual value will be configured for
production based on performance testing.
● All sensitive properties should be secured using AES encryption and CBC mode.
3.1.2 Method Design
Following is the list of recommended Mule ESB components to be used for this method.
● HTTP Listener – to configure HTTP inbound endpoint for this API operation.
● Reference Exception Strategy – to invoke a global shared exception strategy defined in the application.
● Secure Property Placeholder – to encrypt the sensitive properties.
● HTTP Requester – to invoke the Process and System API.
● Data Weave – to transform the response from S- API.
● Flow/Private-Flow/Sub-Flow – to implement the actual business logic.
● Set Payload – to set payload message when required.
● Logger Framework – to do standard logging
● Choice – to validate Client Credentials.
● RAML Library – to describe request and response structure for this API.
● RAML – to define API contracts. This will use the JSON schema internally.
● APIkit Console – to simulate and test the API contract
● APIkit Router – to route API call to the correct operations
3.1.3 Summary
This operation is responsible for getting payment link details through System API. The POST
operation covers the following use cases:
The following resource of Process API will be invoked ;
● POST/registerIntent : This endpoint in Experience API will be invoked by other api’s.
The below parameters will be picked from the secured properties
(<project-name>-{env}-secure-properties.yaml, (<project-name>-{env}-properties.yaml,
(<project-name>-common-properties.yaml) file before invoking the Data Vault System
● Process API configuration details from (<project-name>-{env}-properties.yaml)
● Process api basic authentication details, client id and client secret
(<project-name>-{env}-secure-properties.yaml)
● Process api call retry configuration (<project-name>common-properties.yaml)
The following response scenarios handled at the ESB:
a. SUCCESS scenario: Data Vault details successfully fetched from the process api, and the system api
response will be captured and transformed to return to the consumer API.
b. Data error scenario: Validation error at the system API, return the specific error response to the
consumer API.
c. End System Error Scenario: In case end system is down or unreachable, it will return back the error to
the consumer API, along with the error code.
3.1.4 Request Schema
Attribute Datatype Description
merchantRequestId String Unique identifier for the
merchant's request
amount String Monetary amount of the
transaction
intentRequestExpiryMinutes String Duration in minutes until the
payment intent expires
flow String Type of transaction flow
(e.g., TRANSACTION,
REFUND)
remarks String Description of the
transaction
refUrl String URL referencing the
transaction
refCategory String Category code for the
transaction
iat String Issuance time of the JSON
object (Unix timestamp)
udfParameters Object User-defined parameters in
JSON format
payerAccountHashes Array List of hash values
associated with payer
accounts
Refer the “x-portal-autopayyesbank-api” project in Anypoint Exchange for schema definition. A
quick link for the project is as follows.
x-portal-autopayyesbank-api
Note: you would require Fivestar Anypoint Platform account to be able to access the request schema.
Canonical Model for request schema is not applicable.
3.1.5 Response Schema
Attribute Data Types Description
String Indicates the status of the
status transaction (e.g., "SUCCESS",
"FAILURE")
String Provides a human-readable message
responseMessage
describing the transaction status
String A code representing the transaction
responseCode
status
Object Contains detailed information about
payload
the transaction
payload.merchantChannelId String Identifier for the merchant's channel
payload.payeeName String Name of the payee
payload.merchantId String Identifier for the merchant
String Unique identifier for the merchant's
payload.merchantRequestId
request
String Identifier for the transaction on the
payload.gatewayTransactionId
gateway
payload.orderId String Order identifier
Object Contains any user-defined
udfParameters parameters associated with the
transaction
3.1.6 Response Mapping
The response from the system API is sent to the caller.
3.1.7 Error Handling
● For any error, a standard HTTP error code should be return with corresponding message.
● For any system api connectivity issues, the particular error message with the respective error code is
sent as response. Below is the error response structure to be formed if any error occurs:
Target Source
error <root tag>
source Name of the source system
target Name of the target system
errorCode error code number
message error message
descriptio
n Detailed description of the error
timeStam
p Current datetime in yyyy-MM-dd HH:mm:ssZ format
3.1.8 Logging
Following information will be implemented and captured in Database in this API:
● Application Name
● Flow Name
● Request Id
● Message Id
● Log Message
Payload should never be logged. If business requires some key information to be logged such as
correlation Id, it should be logged using custom logger framework but ensure not to log any sensitive
data such as customer email, contact details or card details.
4 API/Service NFR
4.1 Security
Following security shall be implemented/configured in this API:
● The APIs shall be private and should use HTTP i.e., expose internally using 8202 for System API.
Any system API credentials must be encrypted and picked from the secure property files.
4.2 Performance
● Mule API makes multiple re-connection attempt due to target web service connection issues, the
overall time for API to return a response will be multiplied based on the configuration.
● The overall response time depends on how long downstream API takes to serve the request.
4.3 Exception and Error Handling
Global Reference Exception strategy is used for exception and error handling. A set of common
exceptions that need to be handled are declared in the global exception handling block and all
exceptions and error originated in the flow will be referenced or passed to this global exception
strategy block. Custom error formed in error xml will be sent back to the caller.
4.4 Application Monitoring
Additional API transactions details will be captured as part of logging will be used for future
reporting.
Manual monitoring and health check will be part of the support activity carried out by the support
team. Maven as a build tool will be used to standardise on build best practices, reduce
dependencies, simplify continuous integration and easily share projects between developers.
4.5 Build and Deployment Solution
4.5.1 Code Versioning
GitHub is used for software configuration management. Access to GitHub is provided by Fivestar.
4.6 Tools and Technologies
4.6.1 Development Tools
● Anypoint Studio 7.11 with Mule 4.4 runtime - used for all mule application development
● Anypoint Design Center - will be used to design API.
● Anypoint Runtime Manager – for application deployment
● Maven – for defining the application dependencies
● Anypoint Exchange – used to maintain all MuleSoft API assets.
4.6.2 Technologies
● Data Weave expression language
● JSON
5 Testing
5.1 Testing Approach
The testing for this API shall cover the following:
● The API shall be accessible only using HTTP port 8440.
● The request and response structure are aligned with the schema mentioned in this document.
● Logging should be as per the logging framework best practices.
● Postman to be used for functional testing.
● MUnits will be written for unit testing.
● System Integration Testing (SIT) will be performed by Whishworks testing team for the possible test
cases which can be executed
5.2 Functional Testing
● Testing and verification of all use cases mentioned in 1.2 section.
● All mapping rules should be executed as per the mapping sheet given in this document.
5.3 Non-Functional testing
NA
5.4 Testing Tools
● Postman
5.5 Mocking frameworks
● Munit
********End of Document********
