Event Handling and Data Processing

The embedded banking component uses events to send information during connection, authentication and disconnection. These three steps are necessary to safely connecting the user to the FI, and are fully explained in our Authentication article.

All events contain a payload of data that will need to be encrypted or decrypted on the server-side of the application. The non-bank partner is responsible for ensuring any payload from the client-side events are securely and correctly communicated to their server-side services.

Reminder: The user is using two accounts during this process. They are already authenticated into the non-bank partner’s credential system while using the Embedded Banking Component. They also must authenticate with the FI using the FI’s credential system. For a more in depth explanation, see this article on Authentication.

Connecting to Embedded Banking

When a user connects to an Embedded Banking Component, they both establish a connection to the FI and authenticate using the FI’s normal login system. This section explains the steps needed in detail.

Decrypting Received Data

The data received by the Partner is a HEX encoded string, similar to the one below:

86fe4520496b67dab8989c55e94ab6f6ebd8de4a62518f23cb2...eb520e39fd26d12a

The Partner must first decode this string into a stream or byte array to obtain the raw encrypted data:

const rawEncryptedData = Buffer.from(encodedUrlParameter, 'hex');

Once decoded, the data should be decrypted using the private RSA Key provided to the Partner within the Developer Portal. For more information on keys, see Getting Application Keys and IDs.

NOTE: OAEP padding scheme should be used.

const rawDecryptedData = crypto.privateDecrypt(privateKey, rawEncryptedData);

The decrypted data should be encoded as a UTF-8 string and then Deserialized as a JSON object.

const obj = JSON.parse(rawDecryptedData.toString('utf8'));

The resulting object’s structure is described in the workflows below.

Receive the Connect JSON Data Object

The following object structure is used when connecting:

{
"userCode" : "The User's Security Code", 
"retUrl" : "The Next URL in the workflow" 
}

The userCode is the link between both the FI’s user credentials and the non-bank partner’s user credentials. userCode is used later during silent authentication to prove the user is allowed to access their banking, and must be kept secret.

Safely Store the userCode

userCode must be stored securely in the non-bank partner’s application data store and must be associated with the non-bank partner’s authenticated user. The userCode must be returned by the application to prove that the same end user is logged in and is allowed to access their banking data.

If the server responds with the same userCode in a subsequent initializeAuthenticate event, the end user will be connected to the same banking login. The server also must ensure that the userCode is only returned to the same, currently authenticated application user.

The identifier must be treated as secret and stored server side only. It cannot be stored in

browser local storage
user-facing locations
publicly accessible location

POST to the retUrl in Response

Once the userCode has been processed, the non-bank partner application must POST to the retUrl to continue the flow.

The body of this POST request is a JSON object with a status property indicating whether or not the userCode was successfully captured by the non-bank partner:

{  status: OK }

Submitting Custom Status Values

If data from a response was obtained and stored correctly, the value of status should be OK . Any value other than OK in the status property is considered an error that fails the connection attempt and is recorded for future troubleshooting purposes.

Errors encountered should follow the general flow of the application, such as redirecting to the applications custom error page when appropriate. Errors to consider writing handling for include:

Failing to authenticate or authorize the current user
User session expiration
Unable to connect to the database to retrieve user information

retUrl Response

Upon posting to the retUrl, the Embedded Banking Component completes the authentication process and sends a 204 – No Content response if no errors have occurred.

Silent Authentication Workflow

The Embedded Banking Components can perform silent authentication on a previously Connected User. Silent authentication does not require direct user interaction; it allows the partner application to show banking information the next time the user logs back into the non-banking partner’s application.

This workflow depends on the Partner application having safely and securely stored the userCode reference provided during the initial connection, as documented earlier in this article.

Receive the Authentication JSON Data Object

The following object structure is used when silently authenticating:

				
					{
 "attemptId" : "Authentication attempt identifier",
 "retUrl" : "REST API Url Location for the next step"
}

Constructing a Response Object

A response object should be constructed containing the attemptId from the decrypted request, and the userCode obtained during the Connection for the current user.

				
					{
 "attemptId" : "Authentication attempt identifier",
 "userCode" : "Obtained when originally connecting"
}

The response object should be serialized as a UTF-8 JSON string and encrypted using the public key provided during onboarding.

Note: The below example uses the JavaScript Crypto library. The use of this library is not required.

				
					const rawResponseData = Buffer.from(JSON.stringify(responseObject));
const rawEncryptedResponseData =   crypto.publicEncrypt({
    key: publicKey, 
    padding: crypto.RSA_PKCS1_OAEP_PADDING
    encoding: 'utf8'
  }, responseData);

NOTE: RSA_PKCS1_OAEP_PADDING encryption method and padding scheme (or the corresponding equivalent on the platform you are using) must be used.

POST the Response Object to the retURL

The resulting data should then be encoded as a HEX string and set as the payload property of the JSON posted to the retUrl.

				
					const authResponse = {
  payload: rawEncryptedResponseData.toString('hex'),
  status: 'OK'
};

status should be OK unless an error was encountered while creating the payload. See the Submitting Custom Status Values section for directions on error handling and creating messages for the status field.

retUrl Response

Upon posting to the retUrl, the Embedded Banking Component completes silent authentication and sends a 204 – No Content response if no errors have occurred.

Logout Component

A separate Logout embedded banking component is included on the non-bank partner’s log out page. When the user clicks the button to log out or disconnect from Embedded banking, the logout component is used to remove the client and server artifacts related to the user’s embedded banking session. This is critical to the secure operation of embedded components. Failure to initiate this process may result in orphaned authentication in the user’s browser.

The logout component must be included in the FI’s logout page.

<web-component app-id="YourAppId" route="logout"></web-component>

Automatically Disconnecting

The user is automatically disconnected from the FI after a timeout that is pre-determined by the FI. Usually this period of time is set to a large number days. Automatic disconnection renders the userCode invalid and the user must re-authenticate when they attempt to use an embedded banking component again.

The userCode is not automatically removed from the non-bank partner’s data storage, but will fail when used for silent authentication. The userCode should be removed by the application when it is invalid.