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.
Property | Description | Child properties |
---|---|---|
iframeConfig | Along with the style property, describes the about secure field iframe div container info. | containerId, style (see next row for style) |
style | Represents an object that used to define the style of the secure field element. Follow the “CSSStyleDeclaration” object specification. | Color, fontSize, fontFamily, padding, border, ::placeholder (pseudo-element), invalid (only web safe fonts are allowed) |
attributes | Secure field html element attributes | Any valid html element attributes; for example, placeholder |
config | Handles Radial custom functional config on secure field. | displayCardLogo (Available on card secure field only) |
The "IframeConfig" object consists of containerId and style. The following table describes each property.
iframeConfig Object properties | Description | Example | Required |
---|---|---|---|
containerId | Id of <div> tag where iframe needs to be added . | containerId: “cardContainer” | Yes |
style | Represents an object that defines height and width for iframe |
style: { "width": "100%", "height": "100%" } |
Optional |
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.
style Object properties | Description | Example | Required |
---|---|---|---|
color | Represent color of that font |
color: "grey" |
Optional |
fontSize | Represent size of that font |
fontSize": "16px" |
Optional |
fontFamily | Represent style of that font |
fontFamily: "Arial, sans-serif", |
Optional |
padding | Represent spacing |
padding: "12px", |
Optional |
border | Represent outline around iframe |
border: "1px solid #ccc", |
Optional |
borderRadius | Represent curve outline corner around iframe |
borderRadius: "4px", |
Optional |
letterSpacing | Represent spacing between each letters |
letterSpacing: "5", |
Optional |
":: placeholder": { “ color ” : “ font-family": "font-size": " font -weight": "letter-spacing": }, | Add styling to placeholder if any |
::placeholder: { "color": "green", "fontFamily": "sans-serif", "fontSize": "13px", "fontWeight": "unset", "letterSpacing": "0px" }, |
Optional |
invalid: { color: }, | It will that color passed when card number is invalid |
invalid: { "color": "blue" } |
Optional |
The "attributes" object consists of value that is displayed on iframe. The following table describes each property.
attributes Object properties | Description | Example | Required |
---|---|---|---|
placeholder | Represents value that needs to be displayed in iframe |
placeholder: "Card Number" |
Optional |
The "config" object consists of value that is displayed on iframe. The following table describes each property.
config Object properties | Description | Example | Required |
---|---|---|---|
displayCardLogo | Represents logo of the card typed, by default it is false | displayCardLogo: true | Optional |
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);
Event sub type | Validation /event type |
---|---|
cardEncrypted | success |
cardValidationSuccess | success |
cardValidationFailed | fail |
cardEncryptedFailed | fail |
secureCodeEncrypted | success |
secureCodeValidationSuccess | success |
secureCodeValidationFailed | fail |
secureCodeEncryptionFailed | fail |
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.
Scenario | errorCode | Message | Description |
---|---|---|---|
accessToken expired | 40001 | Invalid Authentication Error | provided JWT is either invalid or expired, please try with valid Access Token |
Insufficient Radial Options | 40006 | Radial Secure Form Error | No Options provided for secure card or code fields |
Client specific HPS JS load error | 40007 | Radial HPS Module Load Error | Error Loading Radial Hosted Payment JS Module. Reach Radial PTF Support team |
card/code options missing | 40006 | Radial Secure Form Error | No Options provided for secure card field |
{
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.
Property | description | |||
---|---|---|---|---|
Success | Boolean | Indicates getEncryptedPaymentData is success or failed to fetch payment info | ||
cardDetails | Object | Contains below properties encryptedCardNumber, encryptedSecurityCode | ||
tenderType | String | Determine which tenderType of card used | VC, DC, MC |
Sample Response from the getEncryptedPaymentData Method
{
"success": true,
"cardDetails": {
"encryptedCardNumber": "aigAafIZgL+...Fjxb/z8qtZ+I2P7YNdmzs2evnWufiG1Ug=",
"encryptedSecurityCode": "ZVfjO5AX....KX1h07CAKICafPrGMPD7KytRPwS1pkj3bGU="
},
"tenderType": "VC"
}