Radial JavaScript Integration

Radial's foundational JavaScript library can be used to quickly integrate with the Radial Payments Framework. When the Radial library, radial-hostedpayments-js-sdk.js, is included in your webstore page, you can call any of its JavaScript functions and take advantage of the following features:

• Secure Credit Card Payments via the Radial Secure iframe solution

• 3D Secure Support

• Klarna Integration

• Tokenization

• Helper Functions (Utilities)

  • Data Encryption

  • Luhn check

For details on including the library and implementing these features, see the following topics:

• Credit Card Payments through Radial Secure iframe

• 3D Secure Support (Version 2) (including iframe)

• Klarna JavaScript Integration

• Radial JavaScript 3D Secure Helper Utilities

Installation Process

Important: Before you start, request or confirm your testing setup and credentials.

To start using any of Radial JS offerings, you must first have an account set up with Radial Managed Payments. If you do not have an account, contact Radial Payments support.

If you do have an account, contact Radial Payments support to confirm that your setup is correct and your credentials are valid.

Overview

Adding the Radial JS involves integrating the correct Radial JavaScript file, passing required data elements to Radial's API, and creating a division (<div>) tag as needed on your webstore checkout page. The details of each of these steps are explained in the following sections .

Integrate the Radial Payments JavaScript File

To add Radial JS features to your checkout flow, you must integrate the Radial Payments JavaScript file. This process includes the following steps:

Step 1. Provide a list of domains to Radial Payments to add to our Allowed List

The JavaScript integration makes a cross-site call from the browser to Radial's server instead of the originating webstore server. This type of call is often called a Cross-Origin Resource Sharing (CORS) request. For more information, see Mozilla's documentation on Cross-Origin Resource Sharing.

You must provide Radial Payments the domain names of servers for JavaScript integration, so that Radial can put these domains on the Allowed List to enable a successful CORS request. Provide the names of the domains in this format: https://example.com. We will notify you when these domains have been added to your store's Allowed List of domains.

Contact Radial Payments Support to provide your domain names.

Step 2. Generate an Access Token (JWT) for Authentication

Access Token (JWT) generation is a server-to-server call. For security purposes, Radial must authenticate the webstore prior to exchanging any data. To facilitate authentication, Radial exposes a HTTPS REST endpoint where a webstore can submit the request with required params and headers.

Required Parameters

HTTP Headers in Request

Use the following environment-specific URLs to generate an Access Token (JWT):

• Test/UAT Environment URL
  

  https://hps-auth.uat.radial.com/oauth2/token 

• Production Environment URL
  

  https://hps-auth.radial.com/oauth2/token

The following is a curl example of an Access Token (JWT) generation request.

 curl --location --request POST 'https://hps-auth.uat.radial.com/oauth2/token?grant_type=client_credentials&client_id={client_id}&scope=hostedpayments-uat/web-ui-js' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Basic {Base64String}' \
--data ''

The Access Token (JWT) generation call provides a response similar to the following.

{
    "access_token": "eyJraWQiOiJCdE1nOWg...oXHgw37FYwDnl6BQK4Wrw",
    "expires_in": 3600,
    "token_type": "Bearer"
}

Note: Scope in the URL parameter should have a value appropriate for production.

Access Token (JWT) Expiration

The Access Token (JWT) obtained has an expiration period associated with it. Currently, the expiration duration is set as 3600 seconds/1hour, but it can vary from time to time based on security requirements.

If the Access Token (JWT) expires, or if your login credentials are invalid, you receive a 40001-error code.

Radial Payments advises you to configure your webstore so that it makes a new server-to-server authentication call to get a new Access Token (JWT) upon receipt of the error code. If the call is still failing, your login credentials may not be correct and you should contact support.

Capture the Access Token (JWT)

The webstore must capture the response and use the authentication token further requests to Radial.

The Access Token (JWT) received in the response is required to invoke and use the JavaScript library. The webstore must ensure the Access Token (JWT) value is available in the response.

As discussed earlier, in case of error, the following payload is returned:

{
  "errorCode": "40001",
  "errorMessage": "Invalid Authentication Error",
  "errorDescription": "Provided JWT is either invalid or expired"
}

The following sample code generates the Access Token (JWT).

const requestOptions = {
  method: "POST",
  headers: {
    "Content-Type": "application/x-www-form-urlencoded",
    Authorization: "Basic {Base64String}",
  },
};
const response = await fetch(
  "https://hps-auth.uat.radial.com/oauth2/token?grant_type=client_credentials&client_id=${clientId}&scope=hostedpayments-uat/web-ui-js",
  requestOptions
);
const { access_token } = await response.json();

Step 3. Add the new Radial Payments JavaScript File Script Tag

To use radial-hostedpayments-js-sdk.js, you begin by including the library. Add this script tag to your webstore checkout page:

• Test Environment script tag:

  <script src=https://hps-ui.uat.radial.com/sdk/radial-hostedpayments-js-sdk.js></script>

Remove the old file: If you have the old Radial Payments JavaScript library (radial_payments.js), remove it from your test environment.

• Production Environment script tag:
  

  <script src=https://hps-ui.radial.com/sdk/radial-hostedpayments-js-sdk.js></script>

Remove the old file: If you have the old Radial Payments JavaScript library (radial_payments.js), remove it from your production environment.

Step 4. Add Radial() function call

Radial Payments hosts a JavaScript file, radial-hostedpayments-js-sdk.js. This provides the Radial payment functionality. The Access Token (JWT) received from the generation of the Access Token (JWT) call is necessary for the subsequent Radial JavaScript calls from the webstore.

When the radial-hostedpayments-js-sdk.js script has been added to the checkout page in the webstore, the customer's browser downloads the file upon visiting the page.

After downloading the radial-hostedpayments-js-sdk.js file, the webstore should invoke the Radial() method by passing the Access Token (JWT) as illustrated in the following example. In other words, Radial() should be invoked in the checkout page onload event to initialize the Radial Payment JavaScript file.

<script src="https://hps-ui.uat.radial.com/sdk/radial-hostedpayments-js-sdk.js"></script>

<script language="JavaScript">
  Const jwt = <AccessToken received from Radial>
  function loadRadial() {
  const radial = await Radial(jwt);
  }
</script>

onload="loadRadial()"

Once the Radial JS is executed successfully, the Radial Object (typically defined as a const; for example, "radial" when calling Radial() and used to represent Radial Object) is available to window global scope to continue use with Radial JS functionalities. (If control is switched to new page at any point, the Radial JS should be reinitialized by following the preceding steps.)

Note: Not all features are available for all clients, contact PTF Support to enable the additional features mentioned in the documentation.

Error Handling

If the JWT token is invalid or expired, the SDK will throw an error during initialization. Make sure to handle any errors appropriately.

Error Response

If JWT is expired or invalid:

{ 
    "errorCode": "40001", 
    "errorMessage": "Invalid Authentication Error", 
    "errorDescription": "Provided JWT is either invalid or expired" 
} 

If any error loading Hosted Payment Module:

{ 
    "errorCode": "40007", 
    "errorMessage": "Radial HPS Module Load Error", 
    "errorDescription": "Hosted Payment Module Not loaded" 
}