NuDetect Risk Provider
NuDetect is a risk service provider that supports an array of risk assessments. The Mastercard Gateway supports the following risk assessments via NuDetect:
- Card Testing, also known as "card cycling screening" or "BIN attack screening" uses transactions details including card details, billing address, shipping address etc., to risk assess the transaction.
- Trusted Checkout, also known as "behavioral data screening" or "fingerprint screening" or "device screening" uses payer interaction details (e.g., key strokes, mouse clicks), device details (e.g., device ID, IP address), or location information (e.g. geographical location of a payer) to risk assess the transaction.
Based on the risk assessment, NuDetect provides a recommendation to either accept or reject the transaction. Where the recommendation is reject, the gateway blocks the transaction. The details of the risk assessment, including risk score, applied risk rules and their result is returned in the transaction response.
NuDetect is supported from API v56 onwards.
Adding NuDetect to your integration
The integration steps to add NuDetect depend on your gateway integration model.
Prerequisites
To use NuDetect via the gateway:
- Your payment service provider must have NuDetect risk service provider enabled on your merchant profile, and the NuDetect risk profile must be set to "Card Testing", "Trusted Checkout" or "Card Testing + Trusted Checkout".
- If you want to perform "Card Testing" assessment, your NuDetect risk profile on the gateway must be set to "Card Testing" or "Card Testing + Trusted Checkout".
- If you want to perform "Trusted Checkout" assessment, your NuDetect risk profile on the gateway must be set to "Trusted Checkout" or "Card Testing + Trusted Checkout".
If you are using your own payment page to collect payer details and want to perform "Trusted Checkout" assessment, you must integrate to the Risk JS API to allow your payment page to collect fingerprint data.
NuDetect through Hosted Checkout
If you have a Hosted Checkout version 56+ integration then transactions initiated via Hosted Checkout will be automatically sent to NuDetect for risk scoring. The type of assessment will depend on your NuDetect risk profile configuration, either "Card Testing" or "Trusted Checkout" or both.
With "Trusted Checkout", if Hosted Checkout fails to collect fingerprint data then the transaction will not be sent to NuDetect for risk scoring.
NuDetect through Direct Payment
When you collect payment details on your own payment page and submit them to the gateway using a Verify, Authorize, Pay, or Standalone Capture transaction, the implementation differs for "Card Testing" and "Trusted Checkout" risk assessments.
Card Testing
If you want to perform "Card Testing" and are configured for the "Card Testing" or "Card Testing + Trusted Checkout" NuDetect profile, the gateway handles the risk assessment via NuDetect for you.
- Verify, Authorize, Pay, and Standalone Capture transactions submitted to the gateway will be sent to NuDetect for the "Card Testing" risk assessment.
- Transactions will be pre-screened using transaction filtering if you have transaction filtering rules configured.
Trusted Checkout
If you want to perform "Trusted Checkout" and are configured for the "Trusted Checkout" or "Card Testing + Trusted Checkout" NuDetect profile, then you must integrate to Risk JS API to allow your payment page to collect fingerprint data. If the payment page fails to collect fingerprint data, then the transaction will not be sent to NuDetect for risk scoring.
To check if "Trusted Checkout" is enabled, submit a
Payment Options Inquiry request to the gateway. If "Trusted Checkout" with or without "Card Testing" is enabled, the
Payment Options Inquiry response returns
risk.fingerprintprovider=
NUDETECT
Risk JS Integration
This section describes how to use Risk JS API in your NuDetect integration.
Step 1: Create a Session
Perform a Create Session operation to obtain a session ID. Once you create a session, you can update the session with the request fields and values you wish to store in the session.
Create Session API Reference[REST][NVP]
Step 2: Initialize the API
On your payment page, reference the Risk JS API (risk.js) from the gateway servers. This will place a risk object into the window/global namespace.
https://rakbankpay.gateway.mastercard.com/static/risk-core/1.0.0/risk.min.js
risk.js Reference[JavaScript]
Inserting the Form Hidden Input Element
Note that upon completing the configuration using Risk.configure( ) method, the Risk JS SDK creates the following hidden input element inside the <form> element on the payment page, which is usually a wrapper for card details. The Risk JS SDK generates fingerprint data inside the hidden input element when the payer starts interacting with the payment page, for example, key strokes, moving or clicking mouse, etc.
<input name="nds-pmd" type="hidden">
If your payment page does not have a <form> element, you must manually insert the hidden input element, for example, <input name="nds-pmd" type="hidden"> before executing Risk.configure( ) method.
Risk JS Initialization Request
Once you have created a session, initialize the API using the Risk.configure( ) method. This method should be called during the page load or when the DOM is in ready state. It should be called only once for the page load. After calling this method, Risk JS will provide configuration values as member variables.
Provide the following mandatory fields as arguments to the riskConfig object:
merchantId: Your merchant identifier on the gateway.sessionId: The session Id that you created using the Create Session call.apiVersion: (Optional) The API version of the request. If you do not provide a value, the apiVersion defaults to 56.riskProvider: (Optional) The identifier of the risk service provider on the gateway. Currently, only NUDETECT risk service provider is supported via Risk JS API. If you do not provide a risk service provider, the Risk JS API will make a Payment Options Inquiry request to determine the supported risk provider.
Callback Function
You can provide an optional callback function in the Risk.configure() method, which will be invoked with the response object as an argument upon completion of the method. The response object will contain message and status properties to indicate whether the configuration was successful or failed due to an error.
If the configuration was successful:
{ status: "SUCCESS", message: "Risk SDK is configured successfully."}
If the configuration failed:
{ status: "ERROR", message: "Error message"}
Example Initialize API Configuration
Risk.configure({
merchantId: "TESTMERCHANT",
sessionId: "SESSION0002899787259G30902270H6",
apiVersion: 56,
riskProvider: "NUDETECT"
},
function(response) {
// Handle Risk.configure() response */
console.log(response.message)
// Configuration message: 'Risk SDK is configured successfully.'
console.log(response.status)
// Configuration status: 'SUCCESS' or 'ERROR'
}
);
Step 3: Collect Fingerprint Data into a Session
You can add or update fields in the session you created in Step 1 using the Update Session call. It allows you to add payment and payer data into a session that can subsequently become the input to a Verify, Authorize or Pay operation to determine the risk associated with a payer. Perform Update Session when the payer clicks the "Pay Now" button.
Mandatory Fields
- device.fingerprint: Provide the value of the hidden input element as described in step 2. The hidden input element contains the payer fingerprint data as captured by the Risk JS SDK.
- sourceOfFunds.provided.card.*: Details of the card being used for the payment.
order.amount- order.currency: The currency of the order.
- transaction.id: A unique identifier for this payment authentication.
- order.id: A unique identifier for this order.
Please note that you cannot remove fields from a session but can only overwrite values for existing fields.
Update Session API Reference[REST][NVP]
Step 4: Submit the Payment Transaction
If Update Session was successful, the returned session will contain the payer's payment details from the interaction. Use the returned session to present an order confirmation page or to submit a payment to the gateway. See Perform an Operation Using the Session..