Page Comparison

Document Logs
Change log:

Date:

Author:

Version:

Changes:

Completed

Ext.

Int.

Is in Core

11 September 2013

Lars Trzepacz

1.0

Doc. created

Yes

X

Lars Trzepacz

Doc updated: EkspresBank Ekspres Bank integration upgraded to use new API

In-progress

...

2 - Introduction to Functionality

Ekspres bank Bank is a company that can help finance a purchase by supplying a 'loan' during the purchase phase.

This means that the customer buys a phone during sign upsignup. The customer chooses to buy through Ekspres bank Bank who then pays for the phone.

The customer now has a 'loan' at Ekspres bank Bank that the customer will pay back outside our the Rator system.

The process is done through three steps.

The customer chooses to use Ekspres bankBank, and a container for the purchase is created at Ekspres bank Bank to Initiate the Application through a SOAP call to PrefillingService.
Note: CDRator Rator integration to Ekspres Bank API does not support this part, since it has been agreed that an external web service hosted by customer will take care of handle this.
The customer application is the then approved or rejected by Ekspres Bank. To get the application status information, Ekspres Bank is polled for a status of the purchase through a call to SOAP service: FeedbackService. The method called is getApplicationStatus.
If the customer is approved, Rator acknowledges the purchase and sends a capture message to Ekspres bank Bank through SOAP service FeedbackService. To achieve this, putEventRecord method from FeedbackService is called with parameter EventType="282"
It is also possible to cancel the purchase through SOAP service FeedbackService. To cancel the application, the method putEventRecord should be invoked with parameter EventType="401".
Note: It is possible to cancel the application via FeedbackService only if the Application application is not yet marked as 'Shipped' (capture signal not yet sent). Once the application has been marked as shipped'Shipped', the FeedbackService can no longer be used to cancel the application. In that case, the cancellation can be requested manually via Ekspres Bank Sales support and should be initiated by the partner. CDRator is not involved in/responsible for such manual cancellations.

...

Code Block
<groupId>com.cdrator.integration.financial</groupId> <artifactId>rator-financial-dk-ekspresbank</artifactId>

3 - API

The Ekspres bank Bank API can be accessed through the workflow actions developed in CDRator integration project.

...

FQCN of the action class: com.CDRator.billing.financial.ekspresbank.action.GetApplicationStatusAction

This action will poll for the status of an application referenced by the supplied ApplicationGUID.

Input Arguments

The action takes three arguments:

...

brandId: Used to read the Branded parameters. The URL of the webservice at Ekspres bank Bank and some additional required arguments are specified in the parameter tree. So brand Id is used on a branded environment.

...

This action returns an object of type ApplicationStatusResult. Helper methods exposed by this object can be used to map the result to relevant outcomes based on business requirements. The table below describes all helper methods that can be invoked on this result object with a description of the return value for each of these methods.

Helper method

return type

Description

getApplicationStatusOutputExceptionIfNull()

GetApplicationStatusOutput

(package path:

dk.ekspresbank.feedbackservice._2014._01)

Returns a reference to the actual result object returned by the FeedbackService.getApplicationStatus call. This object can be used in case the helper methods available in ApplicationStatusResult object are not enough to meet the requirements.

This method throws a RuntimeException if the GetApplicationStatusOutput object returned by FeedbackService.getApplicationStatus call is null.

All the helper methods described in the next rows of this table are actually calling the corresponding getter methods on this GetApplicationStatusOutput object. Some times the helper methods perform some internal conversions/formatting for easy use.

For ex:

Boolean type result values are converted to boolean type (with false being the default when Boolean object is null)
XMLGregorianCalendar type result values are converted to java.util.Date type

isStatusResultOk()

boolean

true: The currentStatus and latestEvent value in the response can be trusted

false: Something went wrong, so the response values cannot be trusted

isHasGoAhead()

boolean

true/false

Returns the value of hasGoAhead property

isHasShipped()

boolean

true/false

Returns the value of hasShipped property

isIsOk()

boolean

true/false

Returns the value of outputexception property

getRequestId()

String

Returns the requestId returned by Ekspres Bank in getApplicationStatus response

getApplicationGuid()

String

Returns the applicationGUID returned by Ekspres Bank in getApplicationStatus response. This will be same as the applicationGUID supplied in the input

getApplicationId()

Integer

Returns the applicationId returned by Ekspre sbank in getApplicationStatus response.

getCurrentStatus()

Integer

Gets the Current status of the application. Below is a list of all possible values for CurrentStatus:

CurrentStatus value	Description
0	Unknown: The application is not currently known by the system
1	Pending: The application is known, but has not yet reached its final status
2	Accepted: The application is approved, and is waiting for the customer to sign the agreement
3	Declined: The customer cannot get a loan at this time
4	Canceled: The application has been annulled and cannot be used for financing a purchase

getCurrentStatusDate()

Date

Date on which the application reached current status

getLatestEvent()

Integer

Gets the value of the latestEvent. Below is a list of all possible values for latestEvent property:

latestEvent value	Description
0	Unknown: The application is not currently known by the system.
1	Pending: The application is known, but has not yet reached its final status.
2	Accepted: The application is approved, and is waiting for the customer to sign the agreement.
3	Declined: The customer cannot get a loan at this time.
4	Cancelled: The application has been annulled and cannot be used for financing a purchase.
101	Initiation
102	Submit
103	Working
281	GoAhead: The agreement is signed, and the order is ready to be sent to the customer.
282	Shipped
291	Board
299	Disburse
401	CancelSale
402	CancelApplication

getLatestEventDate()

Date

Returns the date of latestEvent

getContractUrl()

JAXBElement<String>

Gets the value of the contractUrl

If anything unexpected happens, an exception is thrown. It is possible to map an Exception to an outcome on the Action GUI on the workflow builder.

...

FQCN of the action class: com.CDRator.billing.financial.ekspresbank.action.CancelAction

This action is used to send a Cancel signal to Ekspres Bank to cancel the sale. Cancel can be initiated via this action only if the Ship Signal for this application is not yet sent to Ekspres Bank.

Input Arguments

This action takes in three arguments:

...

eventDate: Time of cancellation of the Application. Ekspres Bank expects a non-null value for eventDate. Hence, the action will use current date if eventDate supplied in the input is null.

brandId: Used to read the Branded parameters. The URL of the webservice at Ekspres bank Bank and some additional required arguments are specified in the parameter tree. So brand Id brandId is used on in a branded environment.

Return value

This action returns an object of type CancelResult. Helper methods exposed by this object can be used to map the result to relevant outcomes based on business requirements. The table below describes all helper methods that can be invoked on this result object with a description of the return value for each of these methods.

Helper method

Return type

Description

getPutEventRecordOutputExceptionIfNull()

PutEventRecordOutput

(package path:

dk.ekspresbank.feedbackservice._2014._01)

Returns a reference to the actual result object returned by the FeedbackService.putEventRecord call. This object can be used in case the helper methods available in CancelResult object are not enough to meet the requirements.

This method throws a RuntimeException if the PutEventRecordOutput object returned by FeedbackService.putEventRecord call is null.

All the helper methods described in the next rows of this table are actually calling the corresponding getter methods on this PutEventRecordOutput object. Some times the helper methods perform some internal conversions/formatting for easy use.

For ex:

Boolean type result values are converted to boolean type (with false being the default when Boolean object is null)
XMLGregorianCalendar type result values are converted to java.util.Date type

isCancelResultOk()

boolean

true: The response values can be trusted

false: Something went wrong, so the response values cannot be trusted

getRequestId()

String

Returns the requestId returned in FeedbackService.putEventRecord call for cancel action

If anything unexpected happens, an exception is thrown. It is possible to map an Exception to an outcome on the Action GUI on the workflow builder.

...

FQCN of the action class: com.CDRator.billing.financial.ekspresbank.action.CaptureAction

This action is used to send a Ship signal to Ekspres Bank, and the payout process is initiated.

Input Arguments

This action takes in three arguments:

...

eventDate: Time of physical shipment of the goods. Ekspres Bank expects a non-null value for eventDate. Hence, the action will use current date if eventDate supplied in the input is null.

brandId: Used to read the Branded parameters. The URL of the webservice at Ekspres bank Bank and some additional required arguments are specified in the parameter tree. So brand Id is used on a branded environment.

...

This action returns an object of type CaptureResult. Helper methods exposed by this object can be used to map the result to relevant outcomes based on business requirements. The table below describes all helper methods that can be invoked on this result object with a description of the return value for each of these methods.

Helper method

Return Type

Description

getPutEventRecordOutputExceptionIfNull()

PutEventRecordOutput

(package path:

dk.ekspresbank.feedbackservice._2014._01)

Returns a reference to the actual result object returned by the FeedbackService.putEventRecord call. This object can be used in case the helper methods available in CancelResult object are not enough to meet the requirements.

This method throws a RuntimeException if the PutEventRecordOutput object returned by FeedbackService.putEventRecord call is null.

All the helper methods described in the next rows of this table are actually calling the corresponding getter methods on this PutEventRecordOutput object. Some times the helper methods perform some internal conversions/formatting for easy use.

For ex:

Boolean type result values are converted to boolean type (with false being the default when Boolean object is null)
XMLGregorianCalendar type result values are converted to java.util.Date type

isCaptureResultOk()

boolean

true: The response values can be trusted

false: Something went wrong, so the response values cannot be trusted

getRequestId()

String

Returns the requestId returned in FeedbackService.putEventRecord call for capture action

If anything unexpected happens, an exception is thrown. It is possible to map an Exception to an outcome on the Action GUI on the workflow builder.

4 - Return Codes

ReturnCode	Description
OK	Everything is ok, no errors.
ERROR_LOGIN_ERROR	Something is wrong with the RetailerId/Password combination.
ERROR_APPLICATION_NOTFOUND	Application identified by RetailerId/OrderNr not found.
ERROR_UNKNOWN_ERROR	Unexpected error occurred.
ERROR_APPLICATION_ALREADY_SUBMITTED	There is already a submitted application with the given OrderNr.
ERROR_MANDATORY_FIELDS_MISSING	Not all mandatory fields were provided for the requested operation.
ERROR_SITE_DISABLED	The site is disabled.
ERROR_INVALID_PREFILLABLE_FIELDS	There are either non-prefillable fields available, or the value of some prefillable fields are invalid.
ERROR_INVALID_HASH	The hash of the fields is invalid.

...

3.2 - Exceptions thrown by Workflow Actions

Following exceptions can be thrown by Ekspres Bank workflow actions:

com.CDRator.billing.financial.ekspresbank.action.result.exception.ResultNullException: Extends from java.lang.Exception. This exception is thrown when null response is received from Ekspres Bank.
com.CDRator.billing.financial.ekspresbank.action.result.exception.InvalidApplicationGUIDException: Extends from java.lang.Exception. If the ApplicationGUID supplied in the input parameters is null/empty, then the action throws this exception. ApplicationGUID is mandatory to invoke Status poll/cancel/capture functions of Ekspres Bank API.
java.lang.Exception: Sysexceptions due to missing parameter tree entries or other checked exceptions are grouped here
java.lang.RuntimeException: Any runtime exception

4 - Logging

The project uses the rator-soap-monitoring to log request and response to the SOAP_CLIENT_LOG table. In order for this logging to work, two parameters must be added to the parameter tree. See section Configuration.

...

5 - Configuration

The table below describes all parameter tree entries that are used for Ekspres Bank API integration. All parameters except the logging related parameters are brand-enabled.

Some of the Parameters are mandatory and some are optional. The mandatory parameters must always be created and should contain proper values. The Optional parameters can be omitted. If an optional parameter is not present, a default value (if available) is used instead. Default values (if any) for optional parameters are mentioned in the table. If the default value does not meet the requirements, then the corresponding optional parameter can be created and set to desired value as per business requirements.

Parameters Used for communicating with Ekspres Bank :

Used for communicating with Ekspres bankWSDLRequired

Parameter Path/Type	Mandatory?	Value	Description
FINANCIAL.EKSPRESBANK.PARTNER_ID
Number	YES	To be provided by Ekspres Bank	A unique Id supplied by Ekspresbank Ekspres Bank to identify the Partner.
FINANCIAL.EKSPRESBANK.EVENT_RECORD_PASS_KEY
String	YES	To be provided by Ekspres Bank	Value of eventRecordPassKey input parameter used in FeedbackService.putEventRecord method calls. This is supplied by Ekspres Bank
FINANCIAL.EKSPRESBANK.CANCEL_SIGNAL_EVENT_TYPE
Number	NO	Default value: 401	Value of eventType input parameter passed to the FeedbackService.putEventRecord method for canceling an Application. This parameter is created for flexibility that if this value changes in future, then it can be configured via the parameter. Value of eventType input parameter passed to the FeedbackService.putEventRecord method for canceling an Application. Note: Cancel can be initiated via the FeedbackService.putEventRecord call, ONLY if the order has NOT yet been shipped i.e. ship signal is not yet sent.
FINANCIAL.EKSPRESBANK.SHIP_SIGNAL_EVENT_TYPE
Number	NO	Default value: 282 This parameter is created for flexibility that if this value changes in future, then it can be configured via the parameter.	Value of eventType input parameter passed to the FeedbackService.putEventRecord method for sending 'Order Shipped' (i.e. Capture) signal to Ekspres Bank This parameter is created for flexibility that if this value changes in future, then it can be configured via the parameter.
FINANCIAL.EKSPRESBANK.FEEDBACK_SERVICE_				ENDPOINT
String	YES	URL to access the Ekspres Bank webservice FeedbackService The URL to access test FeedbackService Test service(Note: This is the value to be the configured in this parameter entry on TEST environment): https://preprodservices.ekspresbanktest.com/feedback/FeedbackService.svc The URL to access FeedbackService Production service(Note: This is the value to be the configured in this parameter entry on PRODUCTION environment): https://services.ekspresbank.com/feedback/FeedbackService.wsdlsvc	Endpoint URL to connect to the Ekspres Bank FeedbackService. In case the WSDLs need to be accessed, here are the links (do not use these URLs in this parameter tree entry value) For Test FeedbackService WSDL: https://preprodservices.ekspresbanktest.com/feedback/FeedbackService	.wsdl For Production FeedbackService WSDL: https://services.ekspresbank.com/feedback/FeedbackService.wsdl

Parameters Required for Logging SOAP request, response XMLs to the SOAP_CLIENT_LOG

Parameter Path/Type	Mandatory?	Value	Description
SOAP.MONITORING.ENABLE_RATOR_MONITORING_HANDLER
String	YES	T	Enables the logging to SOAP_CLIENT_LOG table
SOAP.MONITORING.ENABLE_XML_PERSISTENCY
String	YES	T	Enables logging of request and response XMLs along with other basic logging info. If this is set to false, the SOAP XMLs will not be logged.

...

6 - Version

Version	Released	Changes
2.0	xx-10-2016	The Ekspres Bank Integration project is updated to integrate to New API of Ekspres Bank. The Ekspres Bank has moved to a new API, and this is different from old API that there are changes in input parameters and output parameters and request response types. So we have developed new Workflow Actions. The old Actions/Components are no longer available.
1.1	12-09-2013 15:51:13	Fixed an issue where request response was stored in soap_monitoring. It will now store it in soap_client_log
1.0	11-09-2013 14:40:03	First stable release

Versions Compared

Old Version 30

New Version Current

Key

2 - Introduction to Functionality

3 - API

4 - Return Codes

3.2 - Exceptions thrown by Workflow Actions

4 - Logging

5 - Configuration

6 - Version