Credit Card Payments through Radial Secure iframe

Secure iframes are valuable tools that online merchants can use to protect credit card data, and provide a safe and convenient payment experience for customers. Radial JS offers a method to create and implement a secure iframe to collect payment data on behalf of the webstore. The iframe secure fields are hosted by Radial.When a customer submits payment information through the secure iframes, Radial sends the encrypted Payment information to the webstore to continue the order process. This provides a safe and isolated environment for sensitive data, protecting it from potential vulnerabilities and attacks.

How Secure iframes Work

Radial Secure iframes use two techniques:

• Isolation: When using the Radial JS Secure iframe feature to collect payment information from checkout pages, Radial creates a separate iframe for each secure field needed for the webstore. These iframes are a separate browsing context within the webstore checkout pages. This context avoids directly accessing the iframe's content or data from the main page via Java Script and other scripts running on main page.

• Data Encryption: Once webstore customers enter credit card information into the secure iframe, Radial JS validates the content and provides the encrypted payment data using secure encryption algorithms. This ensures data is transmitted securely between the webstore and the Radial Payment APIs.

Secure iframe Integration

Prepare the Webstore Payment Page

Based on your checkout flow, you can use Radial Secure iframes to collect both credit card and CVV info or just the needed field. Radial JS also supports saved wallet functionality. In this case Radial only adds the CVV field to capture input from the webstore user and communicate the user-entered value in an encrypted format with the parent webstore .

Ensure that the required DIV tags are present in the checkout pages to accommodate the iframe secure fields. The webstore can use provided customizations for all the secure fields to have the same look and feel as the existing checkout/payment form fields. Radial JS emits success and failure events based on customer inputs in these fields. The webstore listens to those events to handle error scenarios (for example, invalid card or cvv). If successful (valid card and cvv), Radial JS provides the webstore with encrypted payment details that the webstore can use to make further order flow scenarios like the submit payment authorization call for Radial Payment APIs.

Implement iframe Code

Once you invoke the initial Radial JS with a valid access token, you can use the Radial JS provided createSecureForm() method to create a secure iframe(s) for collecting payment data from the end user. The createSecureForm() method requires the Radial Options parameter, which is defined for the secure elements iframe options and styles.

Method

radial.createSecureForm(customConfig); 

Radial Secure iframe Options High-Level Structure

{ 
    "card" : { SecureFieldOptions}, 
    "code" : { SecureFieldOptions }, 
    "savedWallet": {boolean} //default false 
} 

The Radial Option Object consists of two properties: “card” and “code”. These properties describe the secure credit card and secure code fields configurations. The Radial object also contains The optional property “savedWallet”. This property takes a Boolean argument to determine the saved wallet payment scenarios. If savedWallet is true, the end user wants to use existing saved payment information without re-entering the card number but reconfirming the card secure code. In this scenario, the card property is optional.

{
  "code": { SecureFieldOptions },
  "savedWallet": true,
  "tenderType": "VC" //Just two alphabate,
} 

The "SecureFieldOptions" object consists of “iframeConfig”, “style”, ”attributes”, and ”config” properties. The following table describes each property.

The "IframeConfig" object consists of containerId and style. The following table describes each property.

Customize iframe and Secure Element inside iframe:

To customize the secure field iframe, use the "style" element to match the existing checkout page designs. The "style" object allows SSStyleDeclations interface elements, but Radial recommends using a minimum number of styles properties to match the existing page.

The "style" object consists of all CSS styles to match existing layout. The following table describes a few of the basic properties.

Note: All styles passed inside the ":: placeholder" must be in CSS style format.

The "attributes" object consists of value that is displayed on iframe. The following table describes each property.

The "config" object consists of value that is displayed on iframe. The following table describes each property.

Sample Style Options for Card Element and Card iframe

{
  "card": {
    "iframeConfig": {
      "containerId": "ccNumber",
      "style": {
        "width": "100%",
        "height": "100%"
      }
    },
    "style": {
      "color": "#581845",
      "padding": "12px",
      "border": "1px solid #ccc",
      "borderRadius": "4px",
      "::placeholder": {
        "color": "#D2D8D0",
        "font-family": "sans-serif",
        "font-size": "13px",
        "font-weight": "unset",
        "letter-spacing": "0px",
        "line-height": "22px"
      },
      "invalid": {
        "color": "red"
      }
    },
    "attributes": {
      "placeholder": "Card Number",
      "id": "ccCard"
    },
    "config": {
      "displayCardLogo": true
    }
  },
  "code": {
    "iframeConfig": {
      "containerId": "cvv",
      "style": {
        "width": "100%",
        "height": "100%"
      }
    },
    "style": {
      "color": "#581845",
      "padding": "12px",
      "border": "1px solid #ccc",
      "borderRadius": "3px",
      "::placeholder": {
        "color": "#D2D8D0",
        "font-family": "sans-serif",
        "font-size": "13px",
        "font-weight": "unset",
        "letter-spacing": "0px",
        "line-height": "22px"
      },
      "invalid": {
        "color": "red"
      }
    },
    "attributes": {
      "placeholder": "cvv"
    }
  }
}

Sample Style Options for saved Wallet

{
  "code": {
    "iframeConfig": {
      "containerId": "cvv",
      "style": {
        "width": "100%",
        "height": "100%"
      }
    },
    "style": {
      "color": "grey",
      "padding": "12px",
      "border": "1px solid #ccc",
      "borderRadius": "3px",
      "::placeholder": {
        "color": "green",
        "font-family": "sans-serif",
        "font-size": "13px",
        "font-weight": "unset",
        "letter-spacing": "0px",
        "line-height": "22px"
      },
      "invalid": {
        "color": "blue"
      }
    },
    "attributes": {
      "placeholder": "111"
    }
  },
  "savedWallet": true,
  "tenderType": "VC"
}

Sample UI for the Secure Radial iframe Fields

Handle Scenarios (success/failure):

Once createSecureiframe() has successfully added iframes for the secure fields in the webstore, the customer can use them as regular payment form fields. Radial JS performs real-time validations on these secure fields; for example, when a customer enters a credit card number, Radial JS validates and detects card type. (The ‘onblur’ and ‘input’ event listeners fire to validate data.) If the customer enters an invalid card number or code/CVV, Radial JS triggers the Invalid validation event. (Note: The CVV length is validated based on tender type). For all validation events, Radial emits a ‘RadialSecureFormEvent’. The webstore should listen for those events and style the parent fields of the iframe for error messages/styles.

Once the customer enters valid credit card numbers and valid CVV and clicks the webstore Submit button, call the getEncryptedPaymentData() method. This method gets the encrypted payment data entered by the customer.

Radial Custom Window Event Message for secureForm

Use the Radial Custom Window Event ‘RadialSecureFormEvent‘ on credit card number and code (CVV) input text fields to handle styling error and success messages or user input. The following table lists the event types emitted under ‘RadialSecureFormEvent’ message.

Sample code to listen events for ‘RadialSecureFormEvent’:

window.addEventListener('RadialSecureFormEvent', function (e) { console.log(e.detail); }, false);

The event sub type determines how to show error messages on the webstore payment page.

Sample ‘RadialSecureFormEvent’ type cardValidationSucces Event

{ 
    "type": "cardValidationSuccess", 
    "message": { 
        "tenderType": "VC", 
        "cvvLength": 3, 
        "issuingNetwork": "visa", 
        "success": true 
    } 
} 

Sample cardValidationFailed Event

{ 
    "type": "cardValidationFailed", 
    "message": { 
        "success": false, 
        "errorMessage": "Invalid Card: Card Luhn Check Failed", 
        "errorCode": "40004" 
    } 
} 

{ 
    "type": "secureCodeValidationFailed", 
    "message": { 
        "errorMessage": "Invalid Secure Code", 
        "errorCode": "40004", 
        "success": false 
    } 
} 

{ 
    "type": "cardValidationFailed", 
    "message": { 
        "success": false, 
        "errorMessage": "Invalid Card: Empty Card Number", 
        "errorCode": "40003"
    } 
} 

{ 
    "type": "cardValidationFailed", 
    "message": { 
        "success": false, 
        "errorMessage": "Invalid Card: Card Type Not Supported", 
        "errorCode": "40000"
    } 
} 

SecureForm Creation Errors

If errors occur during the secure form creation, Radial JS returns the following errors.

{ 
  errorCode: "40006", 
  errorMessage: "Radial Secure Form Error", 
  errorDescription: "No Options provided for secure card or code fields" 

} 

Test the Integration

After you configure iframe with the required options and styles, create a ‘Submit’ button to simulate the payment submit form. During this submit button call, use the getEncryptedPaymentData method to fetch encrypted payment that the customer entered in the Radial-provided secure iframe fields.

The getEncryptedPaymentData method returns the PaymentMethod object which consist of the following properties.

Sample Response from the getEncryptedPaymentData Method

{ 
    "success": true, 
    "cardDetails": { 
        "encryptedCardNumber": "aigAafIZgL+...Fjxb/z8qtZ+I2P7YNdmzs2evnWufiG1Ug=", 
        "encryptedSecurityCode": "ZVfjO5AX....KX1h07CAKICafPrGMPD7KytRPwS1pkj3bGU=" 
    }, 
    "tenderType": "VC" 
}