iFrame HTML Guide
- HostedPCI Express Solution is designed to integrate with any ecommerce site that requires credit card and CVV information captured.
- iFrame module is installed on the eCommerce sites payment pages. iFrame only displays the credit card fields which are in scope for PCI compliance, that is Credit Card# and CVV. Rest of the page is presented by the eCommerce site as usual.
- iFrame module will use the eCommerce sites payment form to submit credit card information to HostedPCI and returns the token back to the eCommerce site.
- Creating a Token is the First step in maintaining PCI compliant environment using HostedPCI toolset.
Prerequisites
| Parameters | Value |
| hpciSiteId | The site id (a number) configured and provided by HPCI after the activation of the HPCI account. There will be a different Site Id for staging and live sites. |
| location | The location reference within the HPCI application. Locations are configured through the HPCI customer portal. |
| fullParentHost | Is the full hostname where the parent ecommerce site resides (not the iframe). |
| fullParentQStr | Is the query string currently used by the payment page where the iframe resides. This parameter is required for backward compatibility with browsers that do not support “post” frame messages. This string has to match the current url that appears on the browser address bar. |
Parameters for iFrame URL
| Variables | Description |
|---|---|
| jqVersion | This setting is optional, allows control on the JQuery version of the iFrame that is being used. Available versions are 1.11.2 or 2.1.3 or 1.4.1. Values can be [jq1 | jq2 | jqdef] respectively. This parameter need the V2 iFrame to be enabled in order for it to work. |
| browserType | This setting is optional, sets the iFrame for mobile or desktop use. Values can be [mobile | def] |
| cvvValidate | Set the value of the parameter to Y if basic CVV form validation is required. Basic validation will report an error if the entered value is not numbers only and is not between 3 and 4 characters regardless of credit card type. |
| reportCCType | Set the value of the parameter to Y if preliminary credit card and CVV data needs to be reported once the user has entered the details and moves the focus from the respective fields. Credit card type, credit card and CVV length and credit card validity using Mod 10 check is reported. |
| reportCCDigits | This function is optional and requires iFrame V2 to be enabled on the account. This function enables key press feedback from the ccNum field within the iFrame. Set to Y if CC data needs to be reported back during key press. |
| formatCCDigits | Credit card formatting feature, automatically add delimiter while customer types the card in, for example “4444333322221111” will be turned to “4444-3333-2222-1111”. Turn on or off [Y/N]. |
| formatCCDigitsDelimiter | Credit card formatting feature, set the delimiter value which can be space, dash or tab, just need to remember that the value has to be URL encoded [%20/-/%09]. |
| reportCVVDigits | This function is optional and requires iFrame V2 to be enabled on the account. This function enables key press feedback from the ccCVV field within the iFrame. Set to Y if CVV data needs to be reported back during key press. |
| enableTokenDisplay | Set to “Y” if you want the iFrame to show pre-populated masked value that is stored inside. It applies to both credit card and CVV fields. If it’s not empty, it means there is already a value stored inside. |
| ccNumTokenIdx | This parameter is used to define which iFrame index is going to be used. Used mainly for instances where you would need to load multiple iFrames on the same page. Set to “1” unless there is a need for multiple iFrames on the same page. Required for CVV only iFrame. |
| ccNumToken | Is the credit card token that is associated with the CVV iFrame. To re-tokenize CVV for token 4111-1111-1111-1111 set this parameter to “4111111111111111”. |
| enable3DSec | This parameter is required to enable 3DS V2 iFrame. The possible value depends on the 3DS provider. Possible value [cruise1 / wpflex1]. |
| selected3DSecPayName | Name of the 3DSecure payment profile Name. |
| selected3DSecPayCCType | Parameter required to specify CCType. Can be set to ‘any’. |
| selected3DSecPayCurISO | Parameter required to specify Ccurrency Type. Can be set to ‘any’. |
| enableEarlyToken | Set to ‘Y’ to enable early Tokenization. Allows token to be generated beore submitting form. |
| reportFormFields | Set value to the nameOfField. It Returns value of field inside the iFrame. For Example: if id=nameonCard. In order to return value of the field you would need to place this inside a callback . “var frameFullName = hpciReportedFormFieldsObj.nameoncard;” User Semi colon (;) between different field ids. |
| formatCCMaskMode | Value [S6X6]. Required to mask the credit card number in the iFrame. |
| formatCCMaskChar | Value [*] or [X]. Will replace some of the card numbers with the selected values. |
| dataType | enables ach tokenization. The iFrame mist be in V6 (V6Dev) |
iFrame Callback Methods / SuccessHandlers
| Callback Method | Description |
|---|---|
| hpciSiteSuccessHandler | The reference to the function that handles successful credit card mapping. This function will typically copy the mappedCCValue, mappedCVVValue parameter values to form hidden fields that need to contain the credit card and CVV values respectively. Finally this function should submit the order processing form that encloses the credit card entry fields. |
| hpciSiteSuccessHandlerV2 | V2 of site successhandler. It returns ccBINvalue along with mappedCCvalue and mappedCVVvalue. |
| hpciSiteSuccessHandlerV3 | Includes everything in hpciSiteSuccessHandlerV2 but also returns hpciGtyTokenValue. |
| hpciSiteSuccessHandlerV4 | Includes everything in hpciSiteSuccessHandlerV3 but also returns hpciCCLast4Value, hpciGtyTokenAuthRespValue, hpciTokenRespEncrypt. |
| hpciSiteSuccessHandlerV5 | Requires V4 iframe. Includes everything in hpciSiteSuccessHandlerV4 plus it also returns hpciReportedFormFieldsObj, which contains value of extra iFrame form obkects. |
| hpciSiteErrorHandler | The reference to the function that displays the credit card mapping errors. Typically the following function uses DHTML/DOM to display the error. |
| hpciSetup3DSSuccessHandler | Invokes when 3DS iFrame is successfully populated. |
| hpci3DSitePINSuccessHandler | This function is optional and needs to be implemented only for sites that use 3D Secure functionality. The reference to the function that handles successful PIN validation. This function will typically submit the order processing form that encloses the credit card entry fields and the PIN validation iFrame. |
| hpci3DSitePINErrorHandler | This function is optional and needs to be implemented only for sites that use 3D Secure functionality. The reference to the function that displays the PIN validation errors. Typically the following function uses DHTML/DOM to display the error. |
| hpciCCPreliminarySuccessHandler | This function is optional and needs to be implemented only for sites that use reportCCType functionality. The function signature should accept credit card type, BIN, validity flag and length in that order. |
| hpciCCPreliminarySuccessHandlerV2 | Includes hpciCCPreliminarySuccessHandler plus it returns hpciCCEnteredLengthValue. |
| hpciCCPreliminarySuccessHandlerV3 | Requires iframe to enable early Tokenization. Includes hpciCCPreliminarySuccessHandlerV2 plus it returns hpciMappedCCValue, hpciMappedCVVValue and more. |
| HpciCCPreliminarySuccessHandlerV4 | Requires V4 iFrame. Includes up to hpciCCPreliminarySuccessHandlerV3 plus it returns hpciReportedFormFieldsObj which returns value of the new iFrame form object. |
| hpciCVVPreliminarySuccessHandler | This function is optional and needs to be implemented only for sites that use reportCCType functionality. The function signature should accept CVV length. |
| hpciCVVPreliminarySuccessHandlerV2 | Includes hpciCVVPreliminarySuccessHandlerV2 plus it returns hpciCVVValidValue. |
| hpciCVVPreliminarySuccessHandlerV3 | Requires early Tokenization funcationality enabled. Includes hpciCVVPreliminarySuccessHandlerV2 plus it returns hpciMappedCCValue, hpciMappedCVVValue, hpciCCBINValue, hpciGtyTokenValue, hpciCCLast4Value, hpciGtyTokenAuthRespValue and hpciTokenRespEncrypt. |
| hpciCVVPreliminarySuccessHandlerV4 | Requires V4 iFrame. Includes upto hpciCVVPreliminarySuccessHandlerV3 plus it returns hpciReportedFormFieldsObj which returns value of the new iFrame form object. |
| hpciCCDigitsSuccessHandler | This function is optional and requires iFrame V2 to be enabled on the account and needs to be implemented for sites that use key press functionality. The function signature should accept credit card type, BIN, validity flag and length in that order. |
| hpciCCDigitsSuccessHandlerV2 | Includes hpciCCDigitsSuccessHandler plus it returns hpciCCEnteredLengthValue. |
| hpciCVVDigitsSuccessHandler | This function is optional and requires iFrame V2 to be enabled on the account and needs to be implemented for sites that use key press functionality. The function signature should accept CVV length. |
| hpciInitCompleteSuccessHandler | Requires reportInit to be set to ‘Y’. Invokes the method once iFrame has been initiated into the checkout page. |
Other Key Terms
| Variables / Function | Description |
|---|---|
| hpciCCFrameName | The name of the iframe used for displaying the credit card entry fields. |
| sendHPCIChangeClassMsg | This function is optional and requires iFrame V2 to be enabled on the account and needs to be implemented for sites that require changes to the class of the fields inside the iFrame based on interactive feedback during customer keypress of CC/CVV data. The function signature expects elementId of ccNum/ccCVV from within the iFrame and replaces the class with the new classValue that can correspond to the classes from the style header of the iFrame. |
| sendHPCIChangeStyleMsg | This function is optional. It is required to change the style of the iFrame elements. In order to change the message it requires 3 parameters (elementId, propName, propValue); |
| sendHPCIChangeTextMsg | This function is optional. It is required to change the message of the iFrame elements such as labels. In order to change the message it requires 2 parameters (elementId, textValue); |