📘
Strong customer authentication
Strong Customer Authentication (SCA) is a critical security protocol designed to protect financial transactions from fraud and unauthorised access. In the context of NoFrixion's MoneyMoov API, SCA is implemented to ensure the highest level of security during the payout process. This section explains how SCA works in our system and the steps involved in the authentication process.
What is Strong Customer Authentication?
SCA is a requirement of the PSD2 regulation in the European Union. It mandates a two-factor authentication process for online payments and financial transactions. This means that to complete a transaction, a user must provide at least two of the following three forms of identification:
Knowledge: Something only the user knows (e.g., a password or PIN).
Possession: Something only the user possesses (e.g., a mobile phone or security token).
Inherence: Something inherent to the user (e.g., a fingerprint or facial recognition).

Pre-requisites

1. Set up MFA on NoFrixion Identity Server

Before an authoriser can authorise an entity in MoneyMoov, they must set up MFA on the NoFrixion Identity Server. Here's how this is done:

Navigate to NoFrixion Identity server's Manage your account page.
Setup a security key or one time password under Two-factor authentication section.

1. Generate authorisation link

In MoneyMoov, certain entities require authorisation through strong customer authentication. Following are the steps to generate an authorisation link, which authorisers use to review the entity and authorise requests. It ensures a streamlined and secure process for submitting the entity for processing.

i. Authorisation type

In MoneyMoov, entity types that necessitate this level of authorisation are:

Payout
BatchPayout
Beneficiary
Rule

To authorise these entities, a query parameter named ApproveType must be included in your request, set to one of these specific entity types.

ii. ID

This is the ID of the entity that you are trying the authorise. For example, this is the ID of the payout if you are trying to authorise a payout.

iii. Callback URL

This is the url on your server that NoFrixion Identity server will call with the OAuth authorisation code and state set. Example: https://yourserver.com/NoFrixion/Authorise/Callback. Query parameters to this url are as follows:

code: If successful this will contain the OAuth2 code that can be used to acquire an access token from the identity server.
state: If successful this will contain the OAuth2 state that can be used to verify the callback in response to a genuine authorisation generated from your application.
id: Only set if the callback is for a cancellation and contains the ID of the entity that was being authorised.
approveType: Only set if the callback is for a cancellation and contains the type of authorisation that was taking place. Refer (i) Authorisation type for the values this can contain.
cancelled: Set to true if the authorisation operation was cancelled.

iv. State

The state parameter is used in OAuth and OpenID Connect authentication flows. It helps in preventing CSRF attacks. By verifying that the state in the response matches the state sent in the request, the application ensures that the response is to the request it made and not a forged request. When the state is passed as a query parameter to the NoFrixion identity server, it is part of an authentication request. The identity server will send back this state value in its response. Your application will then validate this returned state against the one it sent to ensure the authenticity and integrity of the response.

v. Client ID

The Client ID is a unique identifier for your application on NoFrixion's identity server, essential for implementing the OAuth2 authentication flow. It ensures secure communication between your app and NoFrixion's server. If you don't have a Client ID, you can obtain one by contacting NoFrixion's support team at support@nofrixion.com, necessary for accessing their services securely.

vi. Generate authorisation link

Once you've gathered all the necessary parameters, you can generate the authorisation link using this format: https://identity-sandbox.nofrixion.com/approve?ApproveType=[AUTHORISING_ENTITY_TYPE]&ID=[ID_OF_THE_AUTHORISING_ENTITY]&ClientID=[CLIENT_ID]&State=[STATE]&ReturnUrl=[CALLBACK_URL]

public enum ApproveTypesEnum
{
    None,
    Payout,
    Rule,
    BatchPayout,
    Beneficiary,
    Payrun,
}

public string GenerateAuthorizationUrl(
    ApproveTypesEnum approveType, 
    Guid id, 
    string state, 
    string clientID, 
    string returnUrl)
{
    var urlBuilder = new StringBuilder();
  
    urlBuilder.Append("https://identity-sandbox.nofrixion.com/approve");
    
    // Append the required query parameters
    urlBuilder.Append($"?approveType={approveType}");
    urlBuilder.Append($"&id={id}");
    urlBuilder.Append($"&state={state}");
    urlBuilder.Append($"&clientID={clientID}");
    urlBuilder.Append($"&returnUrl={returnUrl}");
    
    return urlBuilder.ToString();
}

// Define an object to represent the ApproveTypesEnum
const ApproveTypesEnum = {
  None: 0,
  Payout: 1,
  Rule: 2,
  BatchPayout: 3,
  Beneficiary: 4,
  Payrun: 5
};

/**
 * Generates an authorization URL based on the provided parameters.
 *
 * @param {number|string} approveType - The approval type. Can be a value from ApproveTypesEnum.
 * @param {string} id - The GUID as a string.
 * @param {string} state - An arbitrary state string.
 * @param {string} clientID - The client ID.
 * @param {string} [returnUrl] - (Optional) The return URL.
 * @returns {string} The complete authorization URL.
 */
function generateAuthorizationUrl(approveType, id, state, clientID, returnUrl = null) {
  const baseUrl = "https://identity-sandbox.nofrixion.com/approve";

  // Create a URLSearchParams object to build the query string safely
  const params = new URLSearchParams();
  params.append("approveType", approveType);
  params.append("id", id);
  params.append("state", state);
  params.append("clientID", clientID);
  
  // Only add returnUrl if it's provided
  if (returnUrl) {
    params.append("returnUrl", returnUrl);
  }

  return `${baseUrl}?${params.toString()}`;
}

// Example usage:
const approvalUrl = generateAuthorizationUrl(
  ApproveTypesEnum.Payout,
  "123e4567-e89b-12d3-a456-426614174000",
  "someStateValue",
  "YourClientID",
  "https://yourapp.com/callback"
);

console.log(approvalUrl);

import uuid
import urllib.parse
from enum import Enum

# Define the ApproveTypesEnum equivalent in Python
class ApproveTypesEnum(Enum):
    None_ = 0
    Payout = 1
    Rule = 2
    BatchPayout = 3
    Beneficiary = 4
    Payrun = 5

def generate_authorization_url(approve_type: ApproveTypesEnum, id: uuid.UUID, state: str, clientID: str, returnUrl: str = None) -> str:
    base_url = "https://identity-sandbox.nofrixion.com/approve"
    
    # Build a dictionary of query parameters
    params = {
        "approveType": approve_type.value,  # or approve_type.name if you prefer the name
        "id": str(id),
        "state": state,
        "clientID": clientID,
    }
    
    # Only add returnUrl if provided
    if returnUrl:
        params["returnUrl"] = returnUrl
    
    # Encode the parameters to form the query string
    query_string = urllib.parse.urlencode(params)
    
    # Construct the final URL
    return f"{base_url}?{query_string}"

# Example usage:
if __name__ == "__main__":
    # Create a sample UUID for demonstration purposes.
    sample_id = uuid.uuid4()
    
    # Generate the URL
    url = generate_authorization_url(
        ApproveTypesEnum.Payout, 
        sample_id, 
        "exampleState", 
        "YourClientID", 
        "https://yourapp.com/callback"
    )
    
    print(url)

2. Authorise the entity to receive OAuth authentication code

In this step, an authoriser visits the link generated in step 1 to verify the information about the entity they're about to authorise. This process involves checking the specifics of the entity to ensure it's correct and safe. Once satisfied, they grant permission to the entity. Subsequently, this action triggers a response to the previously mentioned callback URL (from step 1), including specific query parameters as outlined. This step is crucial for completing the OAuth authentication process, where the entity is officially authorized to receive an authentication code.

3. Requesting strong access token

After receiving the OAuth authorisation code and state from NoFrixion's identity server, you can request an access token by providing your client ID, secret, and the received code. This access token is special and is necessary to securely submit a payout. With this token, you're enabled to make an API request to process the payout.

NoFrixion identity server token URL: https://identity-sandbox.nofrixion.com/connect/token