Documentation
iFrame HTML Guide
- HostedPCI Express Solution is designed to integrate with any e-commerce site that requires a credit card and CVV information captured.
- iFrame module is installed on the e-commerce site payment pages. iFrame only displays the credit card fields which are in scope for PCI compliance, which is Credit Card# and CVV. The rest of the page is presented by the eCommerce site as usual.
- the 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.
- The HostedPCI token provided back by the iFrame can be stored within your system for future use. The token will remain active for 18 months from the last time it is used.
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 e-commerce 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 | Value |
---|---|
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 needs 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 the 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 the Mod 10 check is reported. |
reportCCDigits | This function is optional and requires iFrame V2 to be enabled on the account. This function enables keypress 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 keypress 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 the 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”. |
lang | Required to invoke the French version of the iFrame. The value needs to be [fr_CA].Not required for English iFrame. |
enable3DSec | This parameter is required to enable 3DS V2 iFrame. The possible value depends on the 3DS provider. Possible value cruise1/wpflex1. value .waitbin’ will delay the 3DS init process. |
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.If more than one field seperate by semi-colon (;).
i.e. reportFormFields=nameoncard;expiryMonth;expiryYear |
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 | value: achus1 (enables ACH tokenization. The iFrame must be in V6 (V6Dev)) |
iFrame Callback Method / SuccessHandler
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 objects. |
hpciSiteSuccessHandlerV6 | Requires V5 iframe. Includes everything in hpciSiteSuccessHandlerV5 plus it also returns hpciMsgSrcFrameName, which contains value of src Frame Name. |
hpciSiteSuccessHandlerV7 | Requires V5 iFrame. Includes everything in hpciSuccessHandlerV6 plus it returns threeDSValuesObj. which includes 3ds objects (threeDSOrderId, cruiseBinStatus, and cruiseSessionId)To return the value i.e.: threeDSValuesObj[“threeDSOrderId”]; OR threeDSValuesObj.threeDSOrderId; |
hpciSiteSuccessHandlerV8 | Requires V5 iFrame. Includes everything in hpciSuccessHandlerV7 plus it returns hpciCCTypeValue. |
hpciSiteSuccessHandlerV9 | Requires V6 iFrame. Includes everything in hpciSuccessHandlerV8 plus it returns ACH parameters: hpciMappedACHValue1, hpciMappedACHValue2, hpciMappedACHValue3, hpciMappedACHValue4full paremeters: hpciMsgSrcFrameName, hpciMappedCCValue, hpciMappedCVVValue, hpciCCBINValue, hpciGtyTokenValue, hpciCCLast4Value, hpciReportedFormFieldsObj, hpciGtyTokenAuthRespValue, hpciTokenRespEncrypt, threeDSValuesObj, hpciCCTypeValue, hpciMappedACHValue1, hpciMappedACHValue2, hpciMappedACHValue3, hpciMappedACHValue4 |
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 the value of the new iFrame form object. |
hpciCCPreliminarySuccessHandlerV5 | Requires V5 iFrame. Includes until hpciCCPreliminarySuccessHandlerV4 plus it returns hpciMsgSrcFrameName object which returns the Frame Name. |
hpciCCPreliminarySuccessHandlerV6 | Requires V5 iFrame. Includes until hpciCCPreliminarySuccessHandlerV5 plus it returns hpciCCTypeValue. |
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 up to hpciCVVPreliminarySuccessHandlerV3 plus it returns hpciReportedFormFieldsObj which returns the value of the new iFrame form object. |
hpciCVVPreliminarySuccessHandlerV5 | Requires V5 iFrame. Includes until hpciCVVPreliminarySuccessHandlerV4 plus it returns hpciMsgSrcFrameName object which returns the Frame Name. |
hpciCVVPreliminarySuccessHandlerV6 | Requires V5 iFrame. Includes until hpciCVVPreliminarySuccessHandlerV5 plus it returns hpciCCTypeValue. |
hpciCCDigitsSuccessHandler | This function is optional and requires iFrame V2 to be enabled on the account and needs to be implemented for sites that use keypress functionality. The function signature should accept credit card type, BIN, validity flag, and length in that order. |
hpciCCDigitsSuccessHandlerV2 | Includes hpciCCDigitsSuccessHandler plus it returns hpciCCEnteredLengthValue. |
hpciCCDigitsSuccessHandlerV3 | Includes hpciCCDigitsSuccessHandlerV2 plus it returns hpciMsgSrcFrameName. |
hpciCVVDigitsSuccessHandler | This function is optional and requires iFrame V2 to be enabled on the account and needs to be implemented for sites that use keypress functionality. The function signature should accept CVV length. |
hpciCVVDigitsSuccessHandlerV2 | Includes hpciCVVDigitsSuccessHandler plus it returns hpciMsgSrcFrameName. |
hpciInitCompleteSuccessHandler | Requires reportInit to be set to ‘Y’. Invokes the method once iFrame has been initiated into the checkout page. |
hpciInitCompleteSuccessHandlerV2 | Returns parameter hpciMsgSrcFrameName. |
hpciFormFieldPreliminarySuccessHandler | Required for iFrame with additional Form FIeld such as (name on card, expiry date)example: var hpciFormFieldPreliminarySuccessHandler = function (hpciFormFieldName, hpciFormFieldValue)
Requires additional iFrame src param: reportFormFields=nameoncard;expiryMonth;expiryYear (seperate each field by (;) semi-colon) |
hpciACHPreliminarySuccessHandlerV1 | ACH successhandler. Requires v6 iFrame. Full returned paraemeters:hpciMsgSrcFrameName, hpciMappedACHValue1, hpciMappedACHValue2, hpciMappedACHValue3, hpciMappedACHValue4, hpciTokenRespEncrypt, hpciReportedFormFieldsObj |
Optional Settings
Parameters | Value |
---|---|
hpciNoConflict = N | If TypeError: $ is not a function error occurs, then you can set hpciNoConflit =N.
This needs to be set during document.ready function.. Example with plain javascript: document.addEventListener(“DOMContentLoaded”, () => { hpciNoConflict = “N”; }); |
Other Key Terms
Variable / 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 class value 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); |
sendHPCISet3DSecParamMsg | This function is required during the 3DS 2.0 ‘waitbin’ process to initiate 3DS flow. The possible value of the function is (“cruise1”, “DEF_3DSEC”, “any”, “any”); |
HOSTEDPCI IFRAME
HostedPCI iFrame is available in multiple versions to fit your needs:
Installing iFrame:
In order to Install iFrame some JavaScript is required.
Required Javascript (in order):
JavaScript in HEAD section:
iFrame V6 – Latest Version
iFrame V6 is the latest version of the HPCI iFrame that is available.
The V6 iFrame supports all of the features until iFrame V5 plus additional features.
iFrame V6 includes ACH Tokenization. Iframe needs to be in mode V6 (V6Dev).
Also include this additional parameter in iFrame src: dataType=achus1
The ACH tokens are returned in the callback methods: hpciSiteSuccessHandlerV9 and hpciACHPreliminarySuccessHandlerV1
iFrame V6 Sample URL
iFrame V5
iFrame V5 is the latest version of the HPCI iFrame that is available.
The V5 iFrame supports all of the features until iFrame V4 plus additional features.
iFrame V5 includes a masking feature as well as 3DSec 2.0 waitbin implementation.
iFrame V5 Sample URL
The parameters ‘formatCCMaskMode=S6X6 ‘ and ‘formatCCMaskChar=*’ are required to enable the masking feature. The masking feature will mask the middle 6 digits of the credit card number and the CVV. The masking character can be either * or X which can be declared in the parameter ‘formatCCMaskChar=[* or X].
‘enable3DSec=waitbin‘ is used to delay the 3DS Implementation process to a later time during the transaction. This is used when additional steps are needed by merchants before invoking the 3DS 2.0 implementation. To invoke 3DS later the following method needs to be initiated inside the successhandler: sendHPCISet3DSecParamMsg(“cruise1”, “DEF_3DSEC”, “any”, “any”);. More information regarding ‘waitbin’ can be found here
iFrame V4
iFrame V4 is the latest version of the HPCI iFrame that is available.
The V4 iFrame supports features to:
- Returns hpciMappedCCValue and hpciMappedCVVValue.
- Return hpciCCBINValue
- Keypress feedback: returns hpciCCTypeValue, hpciCCBINValue, hpciCCValidValue, hpciCCLengthValue.
- Returns hpciCCLast4Value
- Format Credit Card Number in the iFrame (space, tabs or dashes)
- Mask the credit card number and the CVV in the iFrame.
- TLS 1.2 protocol.
- Early Tokenization
- Report Form Fields
enableEarlyToken=Y will enable early Tokenization feature on the iFrame. With Early Tokenization, once users enter a valid credit card number and leave the field the hpciCCCPreliminarySuccessHandlerV4 or hpciCVVPreliminarySuccessHandlerV4 will be invoked which will return the CCToken back to the checkoutPage from HPCI.
reportformfields is the name of the additional form field in the iFrame. In this example reportFormFields=nameoncard
If more than one fields: reportFormFields=nameoncard;expiryMonth;expiryYear (seperate each field by (;) semi-colon)
formatCCMaskMode and formatCCMaskChar will mask the ccnum and cccvv. Accepted value for formatCCMaskMode=S6X6. Accepted value for formatCCMaskChar=* or X.
Basic iFrame
To install the HostedPCI iFrame, you will need to place the code where the credit card field will be in your checkout process.
You can omit onload=”receiveHPCIMsg()” call if preliminary messages are not required.
If the primary eCommerce site has checkout page URL where HPCI iFrame is displayed as ( https://checkout.myecommercesite.com/MyApp/checkout.asp?param1=value1 ) and if the location name is checkout1 and HCPI site ID is 400001, then HPCI iFrame URL will be as follows:
*Other iframe parameters such as width, height, and borders are adjustable as required for the implementation.
https://ccframe.hostedpci.com/iSynSApp/showPxyPage!ccFrame.action?pgmode1=prod&locationName=checkout1&sid=400001&fullParentHost=https%3A%2F%2Fcheckout.myecommercesite.com&fullParentQStr=%2FMyApp%2Fcheckout.asp%3Fparam1%3Dvalue1
Interactive iFrame
- Interactive iFrame provides prompts and feedback during the keypress of credit card# and CVV.
- It also gives prompt informing of which card type is being used.
- To use the full functionality of the iFrame additional parameters needs to be added to iFrame URL, as well as making some small changes to the back -end.
- Format credit card number 3 different ways, dashes, spaces, or tabs.
Interactive iFrame SuceessHandlers example
3 Types of Interactive iFrames
Key Parameters and Values
reportCCType | Requires iFrame V2 to be enabled on the account. This function enables keypress feedback for the credit card type within the iFrame. Set to Y if CC data needs to be reported back during key press. |
reportCCDigits | 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. |
reportCVVDigits | 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. |
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]. |
enableEarlyToken=Y | This parameter needs to be set on the Host Page in order to utilize the keystroke feedback. |
Store Secure Data from iFrame
- Secure Data such as Client’s First Name, Last Name and Credit Card Expiry Date can be stored from the iFrame and they can be retrieved during the Payment API transaction securely.
- This feature requires at least iFrame V5.
- This will require making changes to the iFrame code, Iframe SRC URL and updating the API request.
- The iFrame must include fields for Name such as nameoncard / holdername/ firstname / lastname and Credit Card Expiry such as expiryMonth . expiryYear / expiryDate.
iFrame Body code:
<body> <div> <div class="booking-form__field"> <div class="input-text" id="ccNum-wrapper"> <input autocomplete="cc-name" id="holderName" name="ccname" type="text" value=""> <label for="ccname">Name on Card</label> <div class="message" id="holderNameErrorMessage"> <span class="error" id="holderNameErrorText">Please fill out this field.</span> </div> </div> </div> <div class="booking-form__field"> <div class="input-text" id="ccNum-wrapper"> <input id="ccNum" name="ccNum" type="text" value="" autocomplete="cc-number"> <label for="ccNum">Credit Card Number</label> <div class="message" id="ccErrorMessage"> <span class="error" id="ccErrorText">Please fill out this field.</span> </div> </div> </div> <div class="booking-form__field"> <label>Expiry date</label> </div> <div class="booking-form__field" > <div class="col-xs-4 col-sm-3 col-md-2"> <div class="input-text" id="ccNum-wrapper"> <input type="text" value="" id="expiryMonth" name="ccmonth"> <label for="expiryMonth">Month</label> <div class="message expiry-message" id="expiryMonthErrorMessage"> <span class="error" id="expiryMonthErrorText">Please fill out this field.</span> </div> </div> </div> <div class="col-xs-4 col-sm-3 col-md-2"> <div class="input-text" id="ccNum-wrapper"> <input type="text" value="" id="expiryYear" name="ccyear"> <label for="expiryYear">Year</label> <div class="message expiry-message" id="expiryYearErrorMessage"> <span class="error" id="expiryYearErrorText">Please fill out this field.</span> </div> </div> </div> </div> <div class="booking-form__field"> <div class="input-text" id="ccCVV-wrapper"> <input id="ccCVV" name="ccCVV" type="text" value=""> <label for="ccCVV">Security Code</label> <div class="message" id="cvvErrorMessage"> <span class="error" id="cvvErrorText">Please fill out this field.</span> </div> </div> </div> </div> </body>
iFrame URL details
- The id’s in the iframe and the iFrame URL(reportFormFields) should match.
- In the iFrame URL the order of the parameters inside reportFormFields and reportFormStoredNames must be the same.
- reportFormStoredNames can only have one of the following values expMonth/expYear/lastName/
firstName. They need to match the value API parameter pxySecureData.fields[X]. formName for that corresponding field.
The iFrame src URL for the iFrame above
https://ccframe.hostedpci.com/iSynSApp/showPxyPage!ccFrame.action?pgmode1=prod&locationName=[IFRMAE_NAME]&sid=[SITE_ID]&reportCCType=Y&reportCCDigits=Y&reportCVVDigits=Y&cvvValidate=Y&strictMsgFmt=Y&enableEarlyToken=Y&formatCCDigits=Y&formatCCDigitsDelimiter=%20/-/%09&reportFormFields=holderName;expiryMonth;expiryYear&reportFormFormats=alphanum;&reportFormModes=storereport;storereport;storereport&reportFormStoredNames=lastName;expMonth;expYear&reportFormMinLengths=3;2;2&fullParentHost=[FULLPARENT HOST]
API parameters details
- pxySecureData.fields[X].
action = storeforward / forward: The value “storeforward” should be sent for each field to be stored in HPCI system in the initial API call. The value “forward” should be sent in the subsequent API call, it will retrieve the stored fields only. - pxySecureData.fields[X].
destDefaultValue: OPTIONAL value in case a merchant wants to provide a default value if we have nothing to store. - pxySecureData.fields[X].
encryptKey: The value of the parameter is provided by the merchant. HPCI doesn’t store the key in any shape or form, hence can’t decrypt the data stored in the database without the key. It needs to be same for both storeforward and forward API calls. - pxySecureData.fields[X].
apiName: The value is name of the parameter is the HPCI request API we should map the stored value to. (example: pxyCreditCard.expirationMonth, pxyCreditCard. expirationYear, pxyCustomerInfo. billingLocation.lastName or pxyCustomerInfo. billingLocation.firstName) - pxySecureData.fields[X].
formName: can only have one of the following values expMonth/expYear/lastName/ firstName. It needs to match the value IFrame URL parameter reportFormStoredNames. - pxySecureData.fields[X].name: The value, of the name parameter is how HPCI will store it in the database and is provided by the merchant. Needs to be same in the subsequent transaction.
API Parameters for retrieve the secured data
pxySecureData.fields[0].action=[storeforward / forward] pxySecureData.fields[0].apiName=pxyCreditCard.expirationMonth pxySecureData.fields[0].destDefaultValue= pxySecureData.fields[0].encryptKey=CBF1832CBF18329ABEF12349ABEF1234 pxySecureData.fields[0].formDefaultValue= pxySecureData.fields[0].formName=expMonth pxySecureData.fields[0].name=expiryMM pxySecureData.fields[1].action=[storeforward / forward] pxySecureData.fields[1].apiName=pxyCreditCard.expirationYear pxySecureData.fields[1].destDefaultValue= pxySecureData.fields[1].encryptKey=CBF1832CBF18329ABEF12349ABEF1234 pxySecureData.fields[1].formDefaultValue= pxySecureData.fields[1].formName=expYear pxySecureData.fields[1].name=expiryYY pxySecureData.fields[2].action=[storeforward / forward] pxySecureData.fields[2].apiName=pxyCustomerInfo.billingLocation.lastName pxySecureData.fields[2].destDefaultValue= pxySecureData.fields[2].encryptKey=CBF1832CBF18329ABEF12349ABEF1234 pxySecureData.fields[2].formDefaultValue= pxySecureData.fields[2].formName=lastName pxySecureData.fields[2].name=fullName
Credit Card Field Only iFrame
- For companies that only require Credit Card Numbers, they can hide the CVV input field in their Basic and Interactive iFrame.
- Do not delete the CVV field but rather just hide it from being visible so it does not cause any functionality issues.
- Please insert the code within the iFrame body styling section.
|
|
CVV field Only iFrame
- Sometimes it’s useful to load an iFrame with only the CVV field. That iFrame will be associated with an existing token.
- Credit Card Token is valid for 18 months but CVV token is only valid for 20 min. If you would like to bill a token that is in the system, but we also want to pass the CVV along with it and it’s been more than 20 minutes, we would need to load a CVV only iFrame that will re-tokenize the CVV to an existing credit card token.
- When installing CVV only iFrame, please hide the Credit Card field instead of completely removing it
https://ccframe.hostedpci.com/iSynSApp/showPxyPage!ccFrame.action?pgmode1=prod&locationName=checkout1cvvonly&sid=400001&enableTokenDisplay=Y&ccNumTokenIdx=1&ccNumToken=4000000000000001&fullParentHost=[ecommerceSiteHostName]&fullParentQStr=[ecommerceURLQueryString]
Key Parameters and Values
enableTokenDisplay | Set to “Y” if you want the iFrame to show the 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”. |
Multiple iFrames
- Some instances require loading multiple iFrames on the same page.
- For example, if there is a requirement to split the payment into multiple credit cards. Another example would be for an agent to have multiple iFrames available to him on a single page load. This way there is no need to reload the page to select a different customer/credit card.
https://ccframe.hostedpci.com/iSynSApp/showPxyPage!ccFrame.action?pgmode1=prod&locationName=checkout1&sid=400001&ccNumTokenIdx=1
Key Parameter
ccNumTokenIdx | This parameter is used to define which iFrame index is going to be used. Set to “1” or increment by 1 for every additional iFrame that is required for the same page. |
Checkout Page
- Once information is submitted to iFrame, the credit card token will be returned from HPCI iframe to the main form hosted on the parent page.
- The following form elements are required.
Fields in the forms
Field | Description |
---|---|
ccNum | Credit Card Number field. |
ccCVV | CVV field. |
ccBIN | Field to display BIN (Bank Identification Number) of the card. |
action3DSec | Only required if the 3D Secure functionality is used. Pass the action value to HPCI API in field pxyThreeDSecAuth.actionName so that credit card enrolment in 3D Secure Service is verified. |
Submit | JavaScript embedded in the onClick() event will be used to send a message to the iFrame, to submit the credit card info and return token info back to the main form. Use the JavaScript function sendHPCIMsg() to initiate the mapping and submission process. |
* ccNum and ccCVV are minimum fields required for an iFrame. Other fields required to process a payment consist of the expiry date, billing info, and more.
Submitting information to your Ecommerce Application
- Once Credit card token information is returned to the main form the JavaScript provided will submit the main form to the eCommerce application. Token will be submitted along with the rest of the form information.
- Once the server-side application has the credit card token, all of the credit card operations such as SALE, AUTH, CAPTURE, VOID, and CREDIT will be available to the application through the HCPI server-side API
- please see Web Service API guide
How to Handle Tokens
- Tokens can be stored in the eCommerce application database without risk of compromising PCI compliance.
- Tokens are designed to look similar to credit card numbers in length and structure without actual valid credit card numbers.
- The first 3 – 4 digits and last 4 digits of token match the credit card number but the Tokens are guaranteed NOT to be MOD-10 compatible. (First 3 for 15 Digits and First 4 for 16 digits and longer)
Modifying iFrame CSS
Basic iFrame CSS
- It may be necessary to update CSS / Style within the iFrame to highlight the error field for example.
- The following method can be used to initiate style updates for an element within the iFrame. This method can be invoked multiple times to update the style parameters with the iFrame.
- Make sure ‘hpci-cciframe-1.0.js’ file is included from HPCI servers before making the call.
- Call signature as follows: sendHPCIChangeStyleMsg(htmlElementID, cssTagName, cssTagValue);
- Here’s an example of a call to update the credit card number field to red. sendHPCIChangeStyleMsg(“ccNum”, “color”, “red”);
Interactive iFrame(V2) CSS
- There is another function available to change CSS class at run time within the iFrame. It is specifically useful to create interactive iFrame experience using the keypress functions that were introduced for iFrame V2.
- The call signature is as follows: sendHPCIChangeClassMsg(elementId, classValue);
- For example, to change the class of credit card field inside the iFrame which has the id “ccNum” from the existing class into class “.input-text”, one has to use the following parameters: sendHPCIChangeClassMsg(“ccNum”, “input-text”);
Updating iFrame CSS using Query String Parameters
To use query string parameters to update CSS within the IFRAME, place any of the following place holders in the style tag within the iFrame code:
${pageParam1} / ${pageParam2} / ${pageParam3} / ${pageParam4} / ${pageParam5} / ${pageParam6} / ${pageParam7} / ${pageParam8} / ${pageParam9} e.g: style="margin: ${pageParam1} auto;background: ${pageParam2} repeat scroll 0 0 white;
To use query string parameters to update CSS within the iFrame, place any of the following place holders in the style tag within the iFrame code:
https://ccframe.hostedpci.com/iSynSApp/showPxyPage!ccFrame.action?pgmode1=prod&locationName=test1&…….&pageParam1=0&pageParam2=none
Installing the iFrame for 3D Secure PIN Validation (Optional)
Prerequisite
Parameters | Values |
---|---|
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. |
authTxnId | The unique reference provided by the 3D Secure enrolment verification call. |
fullParentHost | The full hostname where the parent e-commerce site resides (not the iframe). |
fullParentQStr | 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. |
- This is an optional iFrame implementation only for sites that use 3D Secure functionality.
- The HPCI PIN Validation iFrame can be installed into any form that is required to accept credit card information.
- This form should be displayed after receiving a response status of “3dsecure” from the HPCI PaymentAuth or PaymentSale call.
- The returned response should also contain authorization transaction ID (authTxnId)
Example of 3D Secure Pin Validation
- The following example from the “PCI Direct” website shows the credit card PIN validation from within the My Account section of the website.
- To install PIN validation iFrame, the following code Should be placed where the credit card field is required.
- The highlighted top portion of the screenshot shows the portion of the page that is delivered through the iframe. The remainder of the form is provided by the e-commerce site itself, all the user entered data along with tokenized credit card and CVV should be populated in the form for resubmission after the PIN validation completes.
3D Secure Hidden Field / Form Information
- Once the information is submitted to the iFrame and pin validation is complete, the form is resubmitted to perform the AUTH or SALE operation:
- The ccNum and ccCVV fields are populated by the eCommerce sites from the previous call when the credit card tokenization iFrame was displayed.
- The hpci3DSitePINSuccessHandler present in the header section is called once the PIN verification is complete. This handler should initiate the resubmission of the form, this handler can be customized to do any other validation prior to submission if required.
Required parameters to be sent back to HostedPCI (3D Secure only)
Once 3D Secure information has been validated inside the 3D Secure iFrame, the following parameters must be returned back to HPCI:
Parameter | Value |
---|---|
pxyThreeDSecAuth.actionName | must contain “verifyresp”. |
pxyThreeDSecAuth.authTxnId | contains authTxnId that was received from HPCI in the previous call. |
pxyThreeDSecAuth.authSignComboList[0] | optional, for example “YY”. |
pxyThreeDSecAuth.authSignComboList[1] | optional, for example “AY”. |
pxyThreeDSecAuth.authSignComboList[2] | optional, for example “UY”. |
API Tokenization
Introduction
This guide provides implementation details to tokenize a credit card using an API call. The returned credit card token can be used for any further calls for processing transactions.
Credit card tokenization calls
HostedPCI API provides a two-step(setup and mapping) or single-step (direct) process to convert the credit card to a form compatible token.
The two steps process requires a call to set up a conversion call and then a mapping call to covert the credit card number. The request ID and response from the setup call need to be returned for the tokenization call.
The one-step direct call does not require the setup call and is recommended for most operations.
One Step – Direct Credit Card Tokenization Process
The one-step direct process only requires a single API call to convert the Credit Card number and CVV to HPCI Token.
API Endpoint:
https://< site specific api URL>/iSynSApp/mapCCNumAPI.action?apiVersion=1.0.1&userName=&userPassKey=&apiType=pxyhpci&callMode=direct&ccNum=4111111111111111&ccCVV=123
Parameter List
Parameter Name | Parameter Value |
---|---|
userName | [API Username] |
userPassKey | [API Userpasskey] |
apiVersion | 1.0.1 |
apiType | pxyhpci |
callMode | direct |
ccNum | [Credit card number with any spaces and hyphens] |
ccCVV | Optional [Card verification code (CVV) for the credit card] |
If the call is successful the following return parameters will be provided in a URL encoded result set:
Direct Call Successful Response
status=success&callMode=direct&mappedCC=4111000018801111&mappedCVV=200&ccBIN=411111
Response Parameter list
Response Parameter Name | Response Parameter Values |
---|---|
status | Success | error |
callMode | map | direct |
mappedCC | Mapped Credit Card Token for the future use. |
mappedCVV | Mapped CVV valid for use until the first call with the credit card token or 20 minutes. This value is available only if a valid value for CVV is provided in the map call. |
ccBIN | First 6 digits of the credit card (BIN Number). |
Payment API Guide
- A HostedPCI checkout Web Services API can be accessed by any e-commerce system that needs to process credit card transactions with the use of the HPCI credit card token.
- HPCI Web Service API can be used in any programming language that supports HTTPS calls. Examples include Java, PHP, and C #.Net.
Two things to keep in mind when making requests with parameters:
- Parameter values should be UTF-8
- Requests to the endpoints can be sent as NVP (Name-Value Pair)
Prerequisite
API userName | Provided by HPCI after the activation of the HPCI account. |
API userPasskey | Provided by HPCI after the activation of the HPCI account. |
HPCI Tokens | Have been generated and ready to use (implementation of HPCI iFrame Checkout Web Service ) |
HPCI HOST NAME | Provided by HPCI after the activation of the HPCI account. |
Setting up API calls
- API calls to HPCI are made over HTTPS to the provided endpoint URL.
- Parameters are passed through the standard HTTP POST method.
- Name-Value pairs are separated by ‘&’ character and are URL Encoded.
- The java code will set up and call HPCI API URLs.
- PHP and C# .Net have similar methods for POSTing HTTP URLs.
- Full source code is available on file ‘ProxyHPCIProcessorApp.java’
public static String callUrl(String urlString, MapparamMap) { String urlReturnValue = ""; try { // Construct data StringBuffer dataBuf = new StringBuffer(); boolean firstParam = true; for (String paramKey : paramMap.keySet()) { if (!firstParam) dataBuf.append("&"); dataBuf.append(URLEncoder.encode(paramKey, "UTF-8")).append("=") .append(URLEncoder.encode(paramMap.get(paramKey), "UTF-8")); firstParam = false; } String data = dataBuf.toString(); // Send data URL url = new URL(urlString); URLConnection conn = url.openConnection(); conn.setDoOutput(true); OutputStreamWriter wr = new OutputStreamWriter(conn.getOutputStream()); wr.write(data); wr.flush(); // Get the response BufferedReader rd = new BufferedReader(new InputStreamReader(conn.getInputStream())); String line; while ((line = rd.readLine()) != null) { urlReturnValue = urlReturnValue + line; } wr.close(); rd.close(); } catch (Exception e) { e.printStackTrace(); urlReturnValue = ""; } return urlReturnValue; } //END: callUrl
Required Parameters for Setting up API Calls:
Parameter | Value |
---|---|
apiVersion | [ 1.0.1] |
apiType | [pxyhpci] |
userName | [API UserId] |
userPassKey | [API Passkey] |
pxyTransaction.txnPayName | [Name of the Payment profile in use] |
Some advanced configuration allows multiple payment gateways to be set up with HPCI and specified over API Calls. The above parameter can be used to specify the name. Default value is [DEF]. Profile names must be pre-arranged with the HPCI team.
Reading Results from API Calls
- The result is returned in Name-Value pair format with URL Encoded Values
- The java code on the side will read the result from HPCI API Calls and convert to String Map container object.
public static MapparseQueryString(String queryStr) { Map map = new HashMap (); if (queryStr == null) return map; String[] params = queryStr.split("&"); for (String param : params) { String name = ""; String value = ""; String[] paramPair = param.split("="); if (paramPair != null && paramPair.length > 0) { name = paramPair[0]; if (paramPair.length > 1 && paramPair[1] != null) { try { value = URLDecoder.decode(paramPair[1], "UTF-8"); } catch (UnsupportedEncodingException e) { logMessage("Could not decode:" + paramPair[1]); } } } map.put(name, value); } return map;
Credit Card Authorization Transaction (AUTH)
API Endpoint: http://HPCI_API_HOSTNAME/iSynSApp/paymentAuth.action
Additional Required Parameters:
Card Number Related Parameters:
Parameters | Values |
---|---|
pxyCreditCard.cardType | [Type of Credit Card Used] |
pxyCreditCard.creditCardNumber | [HPCI Token Representing Credit Card] |
pxyCreditCard.expirationMonth | [Credit Card Expiry Month] |
pxyCreditCard.expirationYear | [Credit Card Expiry Year] |
pxyCreditCard.cardCodeVerification | [HPCI Token Representing CVV Code] |
Transaction Amount Related Parameters:
Parameters | Values |
---|---|
pxyTransaction.txnAmount | [Amount to Authorize] |
pxyTransaction.txnCurISO | [ “USD” or “CAD” or other ISO Currency Code] |
pxyTransaction.merchantRefId | [Merchant Reference Number (order Id?)] |
pxyTransaction.txnPayName | [“DEF” or a payment profile name] |
pxyTransaction.txnComment | [Empty string or short comment not longer than 50 characters] |
pxyTransaction.txnExtraParam1 | [Not required for all gateways, please ask HPCI support for more details] |
pxyTransaction.txnExtraParam2 | [ Not required for all gateways, please ask HPCI support for more details] |
pxyTransaction.txnExtraParam3 | [Not required for all gateways, please ask HPCI support for more details] |
pxyTransaction.txnExtraParam4 | [Not required for all gateways, please ask HPCI support for more details] |
pxyTransaction.txnExtraParam5 | [Not required for all gateways, please ask HPCI support for more details] |
pxyTransaction.txnInstallmentCount | [For installment count for the transaction amount not required for all gateways, optional for Global Collect gateway] |
pxyTransaction.txnLangCode | [For language code for transaction, not required for all gateways, optional for Global Collect gateway] |
pxyTransaction.txnDuplicateWindowSeconds | [For defining duplicate transaction validation window in seconds, not required for all gateways, optional for Authorize.net] |
User Related Parameters:
Parameters | Values |
---|---|
pxyCustomerInfo.email | [Customer Email Address] |
pxyCustomerInfo.customerId | [Customer User ID] |
Billing Address Related Parameters:
Parameters | Values |
---|---|
pxyCustomerInfo.billingLocation.firstName | [Customer First Name] |
pxyCustomerInfo.billingLocation.lastName | [Customer Last Name] |
pxyCustomerInfo.billingLocation.address | [Customer Billing Street Address] |
pxyCustomerInfo.billingLocation.city | [Customer Billing City] |
pxyCustomerInfo.billingLocation.state | [Customer Billing State] |
pxyCustomerInfo.billingLocation.zipCode | [Customer Billing Zipcode] |
pxyCustomerInfo.billingLocation.country | [Customer Billing Country] |
pxyCustomerInfo.billingLocation.phoneNumber | [Customers Billing Phone Number] |
Shipping Address Related Parameters:
Parameters | Values |
---|---|
pxyCustomerInfo.shippingLocation.firstName | [Customer First Name for Shipping] |
pxyCustomerInfo.shippingLocation.lastName | [Customer Last Name for Shipping] |
pxyCustomerInfo.shippingLocation.address | [Customer Shipping Street Address] |
pxyCustomerInfo.shippingLocation.city | [Customer Shipping City] |
pxyCustomerInfo.shippingLocation.state | [Customer Shipping State] |
pxyCustomerInfo.shippingLocation.zipCode | [Customer Shipping Zipcode] |
pxyCustomerInfo.shippingLocation.country | [Customer Shipping Country] |
pxyCustomerInfo.shippingLocation.phoneNumber | [Customers Shipping Phone Number] |
Other Optional Parameters:
Parameters | Values |
---|---|
pxyCustomerInfo.customerIP | [Customer IP Address] |
pxyOrder.invoiceNumber | [Additional Merchant Identifier (order Id)] |
pxyOrder.description | [Order Description] |
pxyOrder.totalAmount | [Total Amount of Order] |
AUTH Request example:
pxyTransaction.txnPayName=DEF_WIRE&apiVersion=1.0.1&apiType=pxyhpci&userName=[API-USER]&userPassKey=[API_PASSKEY]&pxyCreditCard.creditCardNumber=[4200********1542].&pxyCreditCard.expirationMonth=10&pxyCreditCard.expirationYear=2024&pxyCreditCard.cardCodeVerification=200&pxyTransaction.txnAmount=0.95&pxyTransaction.txnCurISO=EUR&pxyTransaction.merchantRefId=[Merchant-ID]&pxyCustomerInfo.billingLocation.firstName= &pxyCustomerInfo.billingLocation.lastName=Livecareer&pxyCustomerInfo.customerId=2188000&pxyCustomerInfo.profileAction=add&pxyCustomerInfo.billingLocation.address=&pxyCustomerInfo.billingLocation.city=&pxyCustomerInfo.billingLocation.state=&pxyCustomerInfo.billingLocation.zipCode=&pxyCustomerInfo.billingLocation.country=&pxyTransaction.merchantPhoneNum=1800283878&pxyCustomerInfo.customerIP=52.242.23.44
AUTH Response example:
status=success&operId=&saleId=527389371&pxyResponse.threeDSEnrolled=&pxyResponse.threeDSAcsUrl=&pxyResponse.threeDSErrorDesc=&pxyResponse.processorRefId=5756ea78-19a8-41ba-8fad-27a1bc559da8&pxyResponse.processorType=wirecardResponse&pxyResponse.threeDSMessageId=&pxyResponse.threeDSSessionId=&pxyResponse.cardOnFileIssuerId=&pxyResponse.mappedParams=txnResponse.ccTypeEst=VISA&pxyResponse.threeDSARS=&pxyResponse.threeDSOrderId=&pxyResponse.gatewayToken.status=&pxyResponse.responseStatus.name=&pxyResponse.responseAVS2=&pxyResponse.responseStatus=approved&pxyResponse.gatewayToken=&pxyResponse.responseAVS1=&pxyResponse.responseAVS4=&pxyResponse.responseStatus.description=3d-acquirer:The resource was successfully created.&pxyResponse.threeDSCAVV=&pxyResponse.responseAVS3=&pxyResponse.gatewayToken.fullNativeResp=&pxyResponse.threeDSXid=&pxyResponse.threeDSProtoVersion=&pxyResponse.responseStatus.reasonCode=&pxyResponse.threeDSPARequest=&pxyResponse.responseCVV1=&pxyResponse.threeDSECI=&pxyResponse.responseCVV2=&pxyResponse.fullNativeResp=status-code=201.0000&status-description=3d-acquirer%3AThe+resource+was+successfully+created.&merchant-account-id=1b3be510-a992-48aa-8af9-6ba4c368a0ac&transaction-id=5756ea78-19a8-41ba-8fad-27a1bc559da8&request-id=2657335642007935744&transaction-type=purchase&transaction-state=success&completion-time-stamp=2020-05-05T15%3A32%3A16.000Z&requested-amount=0.95&account-holder=Livecareer&ip-address=52.242.23.44&descriptor=1800283878&payment-methods=&authorization-code=792301&api-id=elastic-api&provider-account-id=70010&pxyResponse.threeDSAcsPageData=&pxyResponse.gatewaySubToken2=&pxyResponse.threeDSTransactionId=&pxyResponse.gatewaySubToken1=&pxyResponse.gatewaySubToken3=&pxyResponse.merchantRefId=&pxyResponse.threeDSErrorId=&pxyResponse.txnPayName=DEF_WIRE&pxyResponse.responseStatus.code=201.0000&pxyResponse.threeDSSRS=
Credit Card Capture Transaction (CAPTURE)
API End point: HPCI_API_HOSTNAME/iSynSApp/paymentCapture.action
Additional Required Parameters:
Transaction Amount Related Parameters:
Parameters | Value |
---|---|
pxyTransaction.txnAmount | [Transaction Amount to Capture] |
pxyTransaction.txnCurISO | [ “USD” or other ISO Currency Code] |
pxyTransaction.merchantRefId | [Merchant Reference Number (order Id)] |
Processor ID Parameters:
Parameters | Value |
---|---|
pxyTransaction.processorRefId | [Processor ID provided from Authorization or Sale] |
The pxyTransaction.processorRefId is returned from AUTH (authorization) transaction and must be provided for funds to be captured.
CAPTURE Request example:
apiVersion=1.0.1&pxyTransaction.processorRefId=[AUTH_REF_ID]&userPassKey=[API-PASSKEY]&pxyTransaction.txnAmount=45.45&userName=[API-USERNAME]&pxyTransaction.txnCurISO=USD&apiType=pxyhpci&pxyTransaction.merchantRefId=[MerchantID]
CAPTURE Response example:
status=success&operId=&captureId=[CAPTURE_REF_ID]&pxyResponse.threeDSEnrolled=&pxyResponse.threeDSAcsUrl=&pxyResponse.threeDSErrorDesc=&pxyResponse.processorRefId=[AUTH_REF_ID]&pxyResponse.processorType=anetResponse&pxyResponse.threeDSMessageId=&pxyResponse.threeDSSessionId=&pxyResponse.cardOnFileIssuerId=&pxyResponse.mappedParams=txnResponse.ccTypeEst%3DMASTER_CARD&pxyResponse.threeDSARS=&pxyResponse.threeDSOrderId=&pxyResponse.gatewayToken.status=&pxyResponse.responseStatus.name=APPROVED&pxyResponse.responseAVS2=&pxyResponse.responseStatus=approved&pxyResponse.gatewayToken=&pxyResponse.responseAVS1=P&pxyResponse.responseAVS4=&pxyResponse.responseStatus.description=This+transaction+has+been+approved.&pxyResponse.threeDSCAVV=&pxyResponse.responseAVS3=&pxyResponse.gatewayToken.fullNativeResp=&pxyResponse.threeDSXid=&pxyResponse.threeDSProtoVersion=&pxyResponse.responseStatus.reasonCode=1&pxyResponse.threeDSPARequest=&pxyResponse.responseCVV1=&pxyResponse.threeDSECI=&pxyResponse.responseCVV2=&pxyResponse.fullNativeResp=txnResponse.target.transactionId%3D40048550306%26txnResponse.declined%3DN%26txnResponse.review%3DN%26txnResponse.responseReasonCode.notes%3D%26txnResponse.approved%3DY%26txnResponse.responseReasonCode.reasonText%3DThis%2Btransaction%2Bhas%2Bbeen%2Bapproved.%26txnResponse.responseText%3DThis%2Btransaction%2Bhas%2Bbeen%2Bapproved.%26txnResponse.responseCode.name%3DAPPROVED%26txnResponse.error%3DN%26txnResponse.responseCode.code%3D1%26txnResponse.responseCode.description%3DThis%2Btransaction%2Bhas%2Bbeen%2Bapproved.%26txnResponse.target.authorizationCode%3D3KG7PD%26txnResponse.responseReasonCode.responseReasonCode%3D1&pxyResponse.threeDSAcsPageData=&pxyResponse.gatewaySubToken2=&pxyResponse.threeDSTransactionId=&pxyResponse.gatewaySubToken1=&pxyResponse.gatewaySubToken3=&pxyResponse.merchantRefId=&pxyResponse.threeDSErrorId=&pxyResponse.txnPayName=DEF&pxyResponse.responseStatus.code=1&pxyResponse.threeDSSRS=
Credit Card Sale Transaction (SALE)
API End point: HPCI_API_HOSTNAME/iSynSApp/paymentSale.action
The SALE API call is performed exactly the same way as an AUTH, with a different API endpoint. The funds from a SALE operation will be immediately captured and a CAPTURE operation will not need to follow a SALE operation. However, CAPTURE operations should always follow AUTH operations in order to fully complete a credit card transaction when using AUTH
Credit Card Void Transaction (VOID)
API Endpoint: HPCI_API_HOSTNAME/iSynSApp/paymentVoid.action
Additional Required Parameters:
Transaction Amount Related Parameters
Parameters | Value |
---|---|
pxyTransaction.txnAmount | [Transaction Amount to VOID] |
pxyTransaction.txnCurISO | [“USD” or other ISO Currency Code] |
pxyTransaction.merchantRefId | [Merchant Reference Number (order Id)] |
Processor ID Parameters:
Parameters | Value |
---|---|
pxyTransaction.processorRefId | [Processor ID provided from Authorization or Sale] |
The pxyTransaction.processorRefId is returned from AUTH (authorization) transaction and must be provided for funds specified (partial or full) to be voided and funds relinquished back to the original credit card in question.
VOID Request example:
apiVersion=1.0.1&pxyTransaction.processorRefId=[AUTH_REF_ID]&userPassKey=[API-PASSKEY]&pxyTransaction.txnAmount=45&userName=[API-USER_NAME]&pxyTransaction.txnCurISO=USD&apiType=pxyhpci&pxyTransaction.merchantRefId=[MERCHANT-ID]
VOID Response example:
status=success&operId=&voidId=[VOID_REF_ID]&pxyResponse.threeDSEnrolled=&pxyResponse.threeDSAcsUrl=&pxyResponse.threeDSErrorDesc=&pxyResponse.processorRefId=[AUTH_REF-ID]&pxyResponse.processorType=anetResponse&pxyResponse.threeDSMessageId=&pxyResponse.threeDSSessionId=&pxyResponse.cardOnFileIssuerId=&pxyResponse.mappedParams=txnResponse.ccTypeEst%3D&pxyResponse.threeDSARS=&pxyResponse.threeDSOrderId=&pxyResponse.gatewayToken.status=&pxyResponse.responseStatus.name=APPROVED&pxyResponse.responseAVS2=&pxyResponse.responseStatus=approved&pxyResponse.gatewayToken=&pxyResponse.responseAVS1=P&pxyResponse.responseAVS4=&pxyResponse.responseStatus.description=This+transaction+has+been+approved.&pxyResponse.threeDSCAVV=&pxyResponse.responseAVS3=&pxyResponse.gatewayToken.fullNativeResp=&pxyResponse.threeDSXid=&pxyResponse.threeDSProtoVersion=&pxyResponse.responseStatus.reasonCode=1&pxyResponse.threeDSPARequest=&pxyResponse.responseCVV1=&pxyResponse.threeDSECI=&pxyResponse.responseCVV2=&pxyResponse.fullNativeResp=txnResponse.target.transactionId%3D40048550306%26txnResponse.declined%3DN%26txnResponse.review%3DN%26txnResponse.responseReasonCode.notes%3D%26txnResponse.approved%3DY%26txnResponse.responseReasonCode.reasonText%3DThis%2Btransaction%2Bhas%2Bbeen%2Bapproved.%26txnResponse.responseText%3DThis%2Btransaction%2Bhas%2Bbeen%2Bapproved.%26txnResponse.responseCode.name%3DAPPROVED%26txnResponse.error%3DN%26txnResponse.responseCode.code%3D1%26txnResponse.responseCode.description%3DThis%2Btransaction%2Bhas%2Bbeen%2Bapproved.%26txnResponse.target.authorizationCode%3D3KG7PD%26txnResponse.responseReasonCode.responseReasonCode%3D1&pxyResponse.threeDSAcsPageData=&pxyResponse.gatewaySubToken2=&pxyResponse.threeDSTransactionId=&pxyResponse.gatewaySubToken1=&pxyResponse.gatewaySubToken3=&pxyResponse.merchantRefId=&pxyResponse.threeDSErrorId=&pxyResponse.txnPayName=DEF&pxyResponse.responseStatus.code=1&pxyResponse.threeDSSRS=
Credit Card Credit Transaction (CREDIT)
API End point URL: HPCI_API_HOSTNAME/iSynSApp/paymentCredit.action
Additional Required Parameters:
Transaction Amount Related Parameters:
Parameters | Value |
---|---|
pxyTransaction.txnAmount | [Transaction Amount to Credit] |
pxyTransaction.txnCurISO | [ “USD” or other ISO Currency Code] |
pxyTransaction.merchantRefId | [Merchant Reference Number (order Id)] |
Processor ID Parameters:
Parameters | Value |
---|---|
pxyTransaction.processorRefId | [Processor ID provided from Authorization or Sale] |
The pxyTransaction.processorRefId is returned from AUTH (authorization) transaction and must be provided for funds specified (partial or full) to be credited back to the original credit card in question.
CREDIT Request example:
apiVersion=1.0.1&pxyTransaction.processorRefId=[AUTH_REF_ID]&userPassKey=[API_PASSKEY]&pxyTransaction.txnAmount=22&userName=[API_USERNAME]&pxyTransaction.txnCurISO=USD&apiType=pxyhpci&pxyTransaction.merchantRefId=[MERCHANT_ID]
CREDIT Response example:
status=success&operId=&creditId=529326875&pxyResponse.threeDSEnrolled=&pxyResponse.threeDSAcsUrl=&pxyResponse.threeDSErrorDesc=&pxyResponse.processorRefId=40048764072&pxyResponse.processorType=anetResponse&pxyResponse.threeDSMessageId=&pxyResponse.threeDSSessionId=&pxyResponse.cardOnFileIssuerId=&pxyResponse.mappedParams=txnResponse.ccTypeEst%3DMASTER_CARD&pxyResponse.threeDSARS=&pxyResponse.threeDSOrderId=&pxyResponse.gatewayToken.status=&pxyResponse.responseStatus.name=APPROVED&pxyResponse.responseAVS2=&pxyResponse.responseStatus=approved&pxyResponse.gatewayToken=&pxyResponse.responseAVS1=P&pxyResponse.responseAVS4=&pxyResponse.responseStatus.description=This+transaction+has+been+approved.&pxyResponse.threeDSCAVV=&pxyResponse.responseAVS3=&pxyResponse.gatewayToken.fullNativeResp=&pxyResponse.threeDSXid=&pxyResponse.threeDSProtoVersion=&pxyResponse.responseStatus.reasonCode=1&pxyResponse.threeDSPARequest=&pxyResponse.responseCVV1=&pxyResponse.threeDSECI=&pxyResponse.responseCVV2=&pxyResponse.fullNativeResp=txnResponse.target.transactionId%3D40048764072%26txnResponse.declined%3DN%26txnResponse.review%3DN%26txnResponse.responseReasonCode.notes%3D%26txnResponse.approved%3DY%26txnResponse.responseReasonCode.reasonText%3DThis%2Btransaction%2Bhas%2Bbeen%2Bapproved.%26txnResponse.responseText%3DThis%2Btransaction%2Bhas%2Bbeen%2Bapproved.%26txnResponse.responseCode.name%3DAPPROVED%26txnResponse.error%3DN%26txnResponse.responseCode.code%3D1%26txnResponse.responseCode.description%3DThis%2Btransaction%2Bhas%2Bbeen%2Bapproved.%26txnResponse.target.authorizationCode%3D%26txnResponse.responseReasonCode.responseReasonCode%3D1&pxyResponse.threeDSAcsPageData=&pxyResponse.gatewaySubToken2=&pxyResponse.threeDSTransactionId=&pxyResponse.gatewaySubToken1=&pxyResponse.gatewaySubToken3=&pxyResponse.merchantRefId=&pxyResponse.threeDSErrorId=&pxyResponse.txnPayName=DEF&pxyResponse.responseStatus.code=1&pxyResponse.threeDSSRS=
Gateway Tokenization
API endpoint: HPCI_API_HOSTNAME/iSynSApp/paymentGatewayToken.action
Tokenization Related Parameters:
Parameters | Value |
---|---|
pxyCreditCard.creditCardNumber | [HostedPCI Token] |
pxyCreditCard.cardCodeVerification | [HostedPCI CVV place holder] |
pxyCreditCard.expirationMonth | [Credit Card expire month] |
pxyCreditCard.expirationYear | [Credit Card expire year] |
pxyTransaction.txnPayName | [Profile Name provided by HostedPCI] |
pxyCustomerInfo.billingLocation.firstName | [Client’s first name as it appears on the card] |
pxyCustomerInfo.billingLocation.lastName | [Client’s last name as it appears on the card] |
Along with these Parameters, there are some additional parameters required by certain Gateways. To find the complete parameters please look at the corresponding gateways page. The list can be found in the gateways section of Documentation.
Automated Clearing House (ACH)
API endpoint: HPCI_API_HOSTNAME/iSynSApp/paymentACH.action
ACH Related Parameters:
PARAMETERS | VALUE |
---|---|
pxyACHRecord.bankAccountNumber | Tokenized ACH number value returned by HPCI iFrame |
pxyTransaction.txnPayName | [Profile Name provided by HostedPCI] |
pxyCustomerInfo.billingLocation.firstName | [Client’s first name as it appears on the card] |
pxyCustomerInfo.billingLocation.lastName | [Client’s last name as it appears on the card] |
pxyTransaction.txnAmount | [amount] |
Along with these Parameters, there are some additional parameters required by certain Gateways. To find the complete parameters please look at the corresponding gateways page. The list can be found in the gateways section of Documentation.
Automated Clearing House API Call:
Request:
apiVersion=1.0.1&apiType=pxyhpci&userName=[API_Uname}&userPassKey=[API-Pword]&PxyACHRecord.bankAccountNumber=11000000100000000000004569&pxyTransaction.txnAmount=2.02&pxyTransaction.txnCurISO=CAD&pxyTransaction.merchantRefId=e9fbb16c-d2c8-4&pxyTransaction.txnPayName=DEF_ELV_ACH&pxyCustomerInfo.email=user%40testemail.com&pxyCustomerInfo.customerId=72c10e80-cdc4-4&pxyCustomerInfo.billingLocation.firstName=Ont&pxyCustomerInfo.billingLocation.lastName=Admin&pxyCustomerInfo.billingLocation.address=22+Hilltop+St&pxyCustomerInfo.billingLocation.city=Poinsan&pxyCustomerInfo.billingLocation.state=ON&pxyCustomerInfo.billingLocation.zipCode=M9K8U6&pxyCustomerInfo.billingLocation.country=CAN
Response:
status=success&operId=&authId=71900&pxyResponse.threeDSEnrolled=&pxyResponse.threeDSAcsUrl=&pxyResponse.threeDSErrorDesc=&pxyResponse.processorRefId=080922ED4-51F1721C-17C4-422D-A2D8-35B38B6FB7A8&pxyResponse.processorType=elavonResponse&pxyResponse.threeDSMessageId=&pxyResponse.threeDSSessionId=&pxyResponse.cardOnFileIssuerId=&pxyResponse.threeDSDDCPageData=&pxyResponse.threeDSARS=&pxyResponse.threeDSOrderId=&pxyResponse.threeDSAcsTxnId=&pxyResponse.gatewayToken.status=&pxyResponse.threeDSErrorSubId=&pxyResponse.responseStatus.name=&pxyResponse.threeDSReasonDesc=&pxyResponse.responseAVS2=&pxyResponse.responseStatus=approved&pxyResponse.gatewayToken=&pxyResponse.responseAVS1=&pxyResponse.responseAVS4=&pxyResponse.responseStatus.description=APPROVAL&pxyResponse.threeDSCAVV=&pxyResponse.responseAVS3=&pxyResponse.gatewayToken.fullNativeResp=&pxyResponse.threeDSXid=&pxyResponse.threeDSProtoVersion=&pxyResponse.responseStatus.reasonCode=APPROVAL&pxyResponse.threeDSPARequest=&pxyResponse.threeDSDDCUrl=&pxyResponse.responseCVV1=&pxyResponse.threeDSECI=&pxyResponse.responseCVV2=&pxyResponse.cardOnFileSettlementDate=&pxyResponse.threeDSErrorSubIdType=&pxyResponse.threeDSAcsPageData=&pxyResponse.gatewaySubToken2=&pxyResponse.threeDSTransactionId=&pxyResponse.gatewaySubToken1=&pxyResponse.gatewaySubToken3=&pxyResponse.declineSource=&pxyResponse.threeDSCavvAlgorithm=&pxyResponse.merchantRefId=&pxyResponse.threeDSErrorId=&pxyResponse.responseStatus.code=APPROVAL&pxyResponse.threeDSReasonCode=&pxyResponse.threeDSSRS=
API Response Variables
The API will call responds with the following name-value pairs.
Parameter | Value | Additional Info. |
---|---|---|
status | [success | error] | The Status response variable indicates if the API call is well-formed, with an appropriate result. An error result will indicate that either the request was not well-formed or that the transaction was not successful. A success result will indicate that the request was well-formed and that the attempted transaction was successful. |
pxyResponse.responseStatus | [approved I declined | error | review | 3dsecure] | The only transaction response considered successful for pxyResponse.responseStatus is the approved status. Any other response should be considered an error. In case of a successful transaction, the authorization code may be obtained as per the following response variable: |
pxyResponse.processorRefId | [Valid Authorization Code from Credit Card Processor] | Once the authorization code is obtained through pxyResponse.processorRefId it should be used for subsequent calls for the following operations: CAPTURE, CREDIT, and VOID. See the documentation for these operations below. |
pxyResponse.processorType | [name of payment processor or gateway processing the transaction] | The response value will be one of: pflResponse – Paypal Payflow Processor cybResponse – CyberSource Processor strResponse – Star Card Processor anetResponse – Authorize.Net Processor monResponse – Moneris Response psiResponse – PSiGate Response ponResponse – Paymentech Orbital Processor wproResponse – Paypal Website PaymentPro Processor snetResponse – SecureNet Processor ipayResponse – Planet Payment iPay Processor prismpayResponse – Prism Pay Processor worldpayResponse – WorldPay Processor optimalResponse – Optimal Processor globalcResponse – Global Collect Processor rakutenResponse – Rakuten Processor ogoneResponse – Ogone Processor 3dsecResponse – 3D Secure response msgDispatchResponse – Message Dispatch response fileDispatchResponse – File Dispatch response |
The following response values are used to determine why a particular transaction has failed for approval (decline, error, or review states).
Parameter | Value |
---|---|
pxyResponse.responseStatus.name | [short description of response] |
pxyResponse.responseStatus.code | [alphanumeric code representing response] |
pxyResponse.responseStatus.description | [long description and informational text of response] |
pxyResponse.responseStatus.reasonCode | [Gateway specific reason code] |
This field contains the reason code for a successful or unsuccessful transaction reported by the payment gateway. This field is populated if available.
Parameter | Value |
---|---|
pxyResponse.fullNativeResp | [Gateway specific result set, URL encoded] |
This field returns the entire result set from the payment processor or gateway. The actual gateway used can be found by inspecting the pxyResponse.processorType response field. The native response is flattened into name-value pairs, separated with & and URL encoded.
Fraud Detection Service Parameters (Optional)
- The Authorization (and Sale) API’s also allows for passing fraud detection service parameters.
- Please Enable ‘Fraud Detection Service’ before passing the fraud detection parameters.
- Fraud Detection parameters are passed in an array, notated by [] array syntax.
- Repeat the following parameters pairs for each parameter that is required by the service.
Parameters | Value |
---|---|
fraudChkParamList[x]. name | [Parameter Name] |
fraudChkParamList[x]. value | [Parameter Value] |
fraudChkParamList[x]. type | [Optional [Parameter Type, either “data” or “map”] |
fraudChkParamList[x]. mappedValue | [optional [Parameter Mapped Value] |
fraudChkParamList[x]. groupIdx | [optional [Parameter Group Index] |
Where [x] starts at 0 and increases with each parameter name and value added. Please refer respective documentation provided by the supported fraud detection service (Kount, Retail Decision, MaxMind) to find the required parameters for a successful call.
Fraud Service Related Response Fields
The following response values are used to determine the status of a fraud verification call if fraud management was enabled.
Parameters | Value |
---|---|
frdChkResp.fullNativeResp | [full response of a call to fraud checking service] |
Kount Related Service Parameters (Optional)
As Part of our Kount Integration, Hosted PCI allows us to pass mapped values for AVST, AVSZ, CVVR, UDF according to the Kount documentation.
AVST, AVSZ, CVVR
AVST, AVSZ, CVVR are used to pass address verification and CVV verification codes from the payment gateway to Kount.
Because the codes from the gateway are going to be different from the possible code values for Kount (possible values are “M” or “N”), you need to create a mapping for every call that will define the relationship between gateway codes and the kount codes.
Example: If you are using PayPal Payflow pro and they are reporting back AVS1 code Y and AVS2 code Y and CVV1 code Y (avs1= Y, avs2 = Y, cvv1=Y) and you want those values to be passed to Kount as a match then you are going to populate the following in your request to HostedPCI.
Parameter | Value |
---|---|
fraudChkParamList[x].name | [AVST] |
fraudChkParamList[x].value | [Y] |
fraudChkParamList[x].type | [map] |
fraudChkParamList[x].mappedValue | [M] |
fraudChkParamList[y].name | [AVSZ] |
fraudChkParamList[y].value | [Y] |
fraudChkParamList[y].type | [map] |
fraudChkParamList[y].mappedValue | [M] |
fraudChkParamList[z].name | [CVVR] |
fraudChkParamList[z].value | [Y] |
fraudChkParamList[z].type | [map] |
fraudChkParamList[z].mappedValue | [M] |
All possible mapping combinations that are applicable to your use case and your payment gateway should be included in the request.
UDF
Kount also allows for User Defined Field (UDF) which can be added to the request similar to the way we did the AVS mapping.
– If we want to pass to Kount 2 UDF’s, one for BILL_COMPANY_NAME, and the second SHIP_COMPANY_NAME, we can pass the following.
Parameter | Value |
---|---|
fraudChkParamList[x].groupIdx | [1] |
fraudChkParamList[x].name | [UDFN] |
fraudChkParamList[x].value | [BILL_COMPANY_NAME] |
fraudChkParamList[x].groupIdx | [1] |
fraudChkParamList[x].name | [UDFV] |
fraudChkParamList[x].value | [HostedPCI] |
fraudChkParamList[x].groupIdx | [2] |
fraudChkParamList[x].name | [UDFN] |
fraudChkParamList[x].value | [SHIP_COMPANY_NAME] |
fraudChkParamList[x].groupIdx | [2] |
fraudChkParamList[x].name | [UDFV] |
fraudChkParamList[x].value | [HostedPCI] |
It’s also possible to pass some values from the gateway response dynamically to a UDF, please contact HostedPCI if you need it.
Accertify Fraud Service
HostedPCI has integrated with Accertify Fraud Service in order to extend out options for the fraud services we work with.
Credentials:
- API URL code
- API Username
- API Password
Credentials on File
HostedPCI’s Credentials on File feature allows merchants the ability to store the issuer ID alongside the credit card to be used for a later date. With Credentials on File, Merchants will be able to charge a customer’s card even when the customer is not present. The Credentials on File can be used along with the 3D Secure feature or as a feature on its own.
The following parameters are required to set up a transaction with the credentials on file feature.
Parameter | Value |
---|---|
pxyTransaction.cardOnFileTxnType | [TxnType] |
pxyTransaction.cardOnFileTxnRef | [TxnRedID] |
pxyTransaction.cardOnFileIssuerId | [IssuerID] |
pxyTransaction.cardOnFileOrigAmt | [Original Amount] |
pxyTransaction.cardOnFileFraudIndicator | [FraudIndicator] |
These are not the only parameters required for Credentials on File Transaction. Each of the Gateway is different from the other. To get the full list of parameter please look at the corresponding gateway page. It can be found in the gateway list in the Documentation.
3D Secure (Verified by Visa and MasterCard securecode) Parameters (Optional)
- The Authorization (and Sale) API also allows for passing payer authentication information.
- 3D Secure information is OPTIONAL and will be required only if the 3D Secure service has been SUBSCRIBED with the payment gateway.
Parameters | Value |
---|---|
pxyThreeDSecAuth.actionName | [Empty string when no 3D Secure action is requested. Pass “verifyenroll” when card enrollment needs to be verified. Pass “verifyresp” when an authentication response needs to be verified.] |
pxyThreeDSecAuth.authTxnId | [Authentication id received from “verifyenroll” call.] |
pxyThreeDSecAuth.paReq | [The payer authentication request value received from “verifyenroll” call] |
pxyThreeDSecAuth.paRes | [The payer authentication response value received from pin verification call] |
pxyThreeDSecAuth.authSignComboList[x] | [The combined statuses of Authentication Result + Signature Result that are acceptable. The results are received after the verification call is completed by HPCI service before requesting an Authorization from the payment gateway. Typical values are “YY”, “AY” and “UY”. Where [x] starts at 0 and increases with each item added.] |
Item RelatedParametersOptional)
- The Authorization (and Sale) API’s also for the passing of individual order item information.
- Line item information is Optional.
- Order Items are passed as parameters in an array, notated by [] array syntax. Repeat the following parameters for each order in the order that is being processed.
Parameters | Value |
---|---|
pxyOrder.orderItems[x].itemId | [Merchant Item ID] |
pxyOrder.orderItems[x].itemName | [Merchant Item Name] |
pxyOrder.orderItems[x]. itemDescription | [Merchant Item Description] |
pxyOrder.orderItems[x]. itemQuantity | [item Quantity Ordered] |
pxyOrder.orderItems[x]. itemPrice | [item Price per Unit] |
pxyOrder.orderItems[x]. itemTaxable | [Is Item Taxable Y/N] |
Where [x] starts at 0 and increases with each item added.
3D Secure Related Response Fields
- If the response Status is 3D Secure then the 3D Secure PIN verification is required to proceed with authorization.
- Please review the ‘3D Secure PIN verification’ section for details. Use the following parameters to initiate the PIN verification call:
Parameters | Value |
---|---|
pxyResponse.threeDSAcsUrl | [ACS Url received from the “verifyenroll” call] |
pxyResponse.threeDSTransactionId | [Transaction Id received from the “verifyenroll” call] |
pxyResponse.threeDSPARequest | [Payer Authentication Request received from the “verifyenroll” call] |
These 3 response variables will be provided verbatim from the payment gateway configured for the HPCI API account. Documentation from the payment gateway should be used to discern the error in question.
3D Secure 1.0 Cardinal Commerce Implementation
- HostedPCI offers ThreeD Secure 1.0 implementation with Cardinal Commerce.
- The following parameters are required to make a successful 3D secure 1.0 authentication with Cardinal Commerce.
- The table below contains parameters required to make a ‘verifyenroll’ call to ensure the credit card is eligible for 3d Secure.
- Few different gateways have 3DS flow implemented with Cardinal Commerce including Authorize .Net, Braintree, Chase Paymentech, SafeCharge, and Wirecard.
Parameters |
Value |
pxyThreeDSecAuth.actionName | verifyenroll |
pxyTransaction.txnPayName | 3dsPayProfile – Name of the 3d secure payment profile. |
pxyThreeDSecAuth.callMode | reportall- will return once 3d secure has been authenticated with credentials for second API call |
- If the ‘verifyenroll’ call was successful it will return some parameters with data needed for the second API call (verifyresp).
- The table below lists the parameters required to make a successful pin verification call for 3DS 1.0 with cardinal commerce.
PARAMETERS | VALUE |
---|---|
pxyTransaction.txnPayName | [3ds payment profile name] |
pxyThreeDSecAuth.actionName | [verifyenroll] |
pxyThreeDSecAuth.callMode | reportall |
pxyThreeDSecAuth.authCAVV | [response from the first API call “pxyResponse.threeDSCAVV”] |
pxyThreeDSecAuth.authTxnId | [response from the first API call “pxyResponse.threeDSXid”] |
pxyThreeDSecAuth.authAcsUrl | [response from the first API call “pxyResponse.threeDSAcsUrl”] |
pxyThreeDSecAuth.paReq | [response from the first API call “pxyResponse.threeDSPARequest”] |
pxyThreeDSecAuth.protocolVersion | [response from the first API call “pxyResponse.threeDSProtoVersion”] |
pxyThreeDSecAuth.authECI | [response from the first API call “pxyResponse.threeDSECI”] |
3d Secure 1.0 WorldPay Implementation
- HostedPCI offers 3dSec 1.0 implementation with WorldPay.
- In Order to make a successful verifyenroll call the following parameters are required.
PARAMETER | VALUE |
---|---|
pxyTransaction.txnPayName | [3dsPayProfile] – Name of the 3d secure payment profile. |
pxyThreeDSecAuth.actionName | [verifyenroll] |
pxyCustomerInfo.browserAcceptHeader | [browserAcceptHeader] |
pxyCustomerInfo.browserUserAgentHeader | [browseruserAgentHeader] |
pxyThreeDSecAuth.callMode | [reportall] – will return once 3d secure has been authenticated with credentials for second API call |
pxyCustomerInfo.sessionId | [sessionID] – also needed in the verifyresp call |
pxyCustomerInfo.billingLocation.firstName | [3D] – to initiate world pay 3DSec 1.0 |
- If verifyenroll call was successful it will return parameters required to make verifyresp call.
- The following parameters are required for PIN verification call.
PARAMETER | VALUES |
---|---|
pxyTransaction.txnPayName | [3dPayProfileName] |
pxyThreeDSecAuth.actionName | [verifyresp] |
pxyThreeDSecAuth.authTxnId | [threeDSTransactionId] – returned from the ‘verifyenroll’ call. |
pxyCustomerInfo.sessionId | [sessionID] – same as the verifyenroll call |
pxyThreeDSecAuth.paReq | [pxyResponse.threeDSPARequest] – response from the verifyenroll call |
pxyThreeDSecAuth.authAcsUrl | [pxyResponse.threeDSAcsUrl] – response from the verifyenroll call |
3D Secure 2
- HostedPCI offers 3DS 2 implementation with Cardinal Commerce, Paay, World Pay, Stripe Pi and Sage Pay UK.
- With 3DS 2.0 implementation the 3ds setup needs to occur during the iFrame setup.
- The following parameters are required in the iFrame SRC in order to set up 3DS 2.0.
3DS 2.0 iFrame Sample Code
iFrame Parameters | Values |
---|---|
enable3DSec | [cruise1 / wpflex1] – cruise1 for cardinal commerce 2.0 and wpflex1 for worldpay 2.0. |
selected3DSecPayName | name of the 3d secure payment profile. |
selected3DSecPayCCType | Credit Card Type. can be set to [any] if not specified. |
selected3DSecPayCurISO | The currency of the transaction. can be set to [any] if not specified. |
3D Secure 2.0 implementation with Cardinal Commerce
- In Order to implement ThreeDSec 2.0 with CardinalCommerce following parameters are required.
- The below table contains parameters required for ‘verifyenroll’ call.
PARAMETERS | VALUE |
---|---|
pxyTransaction.txnPayName | [3ds payment profile name] |
pxyThreeDSecAuth.actionName | [verifyenroll] |
pxyThreeDSecAuth.callMode | reportall (optional) – Dont send if sending pxyThreeDSecAuth.authSignComboList[0]=YY. Also, Dont sent if implementing auto Submit (Firctionless) |
pxyThreeDSecAuth.authSignComboList[0]*can have multiple scenarios. need to change the index | YY / AY/ YA or more. Auto Submit transaction to gateway based on the verifyenroll response from Cardinal Commerce. Default value it YY if pxyThreeDSecAuth.callMode does not equal reportall |
pxyThreeDSecAuth.authSessionId | [cruiseSessionId returned within threeDSValuesObj in hpciSiteSuccessHandlerV4 and later versions] |
pxyThreeDSecAuth.authOrderId | [threeDSOrderId returned within threeDSValuesObj in hpciSiteSuccessHandlerV4 and later versions] |
pxyCustomerInfo.browserUserAgentHeader | [Browser User Agent Header] |
pxyCustomerInfo.browserAcceptHeader | [Browser Accept Header] |
- If verifyenroll call was successful it will return parameters required to make verifyresp call.
- The following parameters are required for the verification call.
PARAMETERS | VALUE |
---|---|
pxyTransaction.txnPayName * | [3ds payment profile name] |
pxyThreeDSecAuth.actionName * | [verifyresp] |
pxyThreeDSecAuth.authTxnId * | [response from the first API call “pxyResponse.threeDSTransactionId”] |
pxyThreeDSecAuth.authSessionId | [cruiseSessionId returned within threeDSValuesObj in hpciSiteSuccessHandlerV4 and later versions] |
pxyThreeDSecAuth.authCAVV | [response from the first API call “pxyResponse.threeDSCAVV”] |
pxyThreeDSecAuth.paReq | [response from the first API call “pxyResponse.threeDSPARequest”] |
pxyThreeDSecAuth.protocolVersion | [response from the first API call “pxyResponse.threeDSProtoVersion”] |
pxyThreeDSecAuth.authECI | [response from the first API call “pxyResponse.threeDSECI”] |
3D Secure 2 Implementation with Paay
In order to implement 3D Secure with Paay, the Paay 3DS payment profile must include these parameters during profile setup.
PARAMETER NAME | REQUIRED VALUE |
---|---|
Merchant URL | e.g: https://api-sandbox.3dsintegrator.com/v2 |
API Key | Paay API Key |
API Secret | Paay API Secret |
API Identifier | Paay API Identifier |
- In Order to initiate 3DS 2 process with Paay the following parameters are required during the API call:
- The table below contains the parameter required for the ‘verifyenroll’ API call.
PARAMETERS | VALUES |
---|---|
pxyCustomerInfo.billingLocation.firstName | [ AUTHORISED or REFUSED] – to initiate 3ds challange process |
pxyCustomerInfo.browserAcceptHeader | [browserAcceptHeader] |
pxyCustomerInfo.browserUserAgentHeader | [browserUserAgentHeader] |
pxyTransaction.txnPayName | [3dsecProfileName] |
pxyThreeDSecAuth.actionName | [verifyenroll] |
- If ‘verifyenroll‘ was successful it will return parameters required for verification call.
- The table below contains parameters required to make the ‘verifyresp‘ API call with Worldpay 3ds 2.
PARAMETERS | VALUES |
---|---|
pxyThreeDSecAuth.authTxnId | [pxyResponse.threeDSTransactionId] – returned from the ‘verifyenroll’ call] |
pxyTransaction.txnPayName | [3dPayProfileName] |
pxyThreeDSecAuth.actionName | [verifyresp] |
3D Secure 2 Implementation with World Pay
In order to implement 3D Secure 2, the World Pay payment profile must include these three parameters during profile setup.
PARAMETER NAME | REQUIRED VALUE |
---|---|
3DS Parameters (enable=Y;apiKey=XXX) | enable=Y;apiKey=ae9715ef-99d8-4467-a3bb-8c463c10edf0;apiIdentifier=5fda1ca955f105709e269351;orgUnitId=5fda1ca94e370853219266ee;ttlMillis=0 |
3DS Setup Init URL | https://centinelapistag.cardinalcommerce.com/V1/Cruise/Collect |
3DS Override PIN URL | https://centinelapistag.cardinalcommerce.com/V2/Cruise/StepUp |
- In Order to initiate ThreeDSecure 2 process with WorldPay the following parameters are required during the API call:
- The table below contains the parameter required for the ‘verifyenroll’ API call.
PARAMETERS | VALUES |
---|---|
pxyThreeDSecAuth.authSessionId | [cruiseSessionId returned within threeDSValuesObj in hpciSiteSuccessHandlerV4 and later versions] |
pxyThreeDSecAuth.authOrderId | [threeDSOrderId returned within threeDSValuesObj in hpciSiteSuccessHandlerV4 and later versions] |
pxyCustomerInfo.billingLocation.firstName | [ AUTHORISED or REFUSED] – to initiate 3ds challange process |
pxyCustomerInfo.browserAcceptHeader | [browserAcceptHeader] |
pxyCustomerInfo.browserUserAgentHeader | [browserUserAgentHeader] |
pxyTransaction.txnPayName | [3dsecProfileName] |
pxyThreeDSecAuth.actionName | [verifyenroll] |
- If ‘verifyenroll‘ was successful it will return parameters required for verification call.
- The table below contains parameters required to make the ‘verifyresp‘ API call with Worldpay 3ds 2.
PARAMETERS | VALUES |
---|---|
pxyThreeDSecAuth.authTxnId | [pxyResponse.threeDSTransactionId] – returned from the ‘verifyenroll’ call] |
pxyTransaction.txnPayName | [3dPayProfileName] |
pxyThreeDSecAuth.actionName | [verifyresp] |
pxyThreeDSecAuth.authSessionId | [same as the verifyenroll call] |
pxyThreeDSecAuth.paReq | [pxyResponse.threeDSPARequest] – response from the verifyenroll call |
pxyThreeDSecAuth.authAcsUrl | [pxyResponse.threeDSAcsUrl] – response from the verifyenroll call |
pxyThreeDSecAuth.messageId | [pxyResponse.threeDSMessageId] – response from the verifyenroll call |
3D Secure 2 Implementation with Stripe Pay Intent
- In order to implement 3Dsecure 2.0 with stripe pay intent, the following parameters are required.
- The table below contains the additional required parameters during the first 3Ds API call (‘verifyenroll’).
PARAMETER | VALUES |
---|---|
pxy.Transaction.txnPayName | [NameofStripePayProfile] |
pxyThreeDSecAuth.callMode | [reportall] |
pxyThreeSecAuth.actionName | [verifyenroll] |
pxyCustomerInfo.browserUserAgentHeader | [Browser User Agent Header] |
pxyCustomerInfo.browserAcceptHeader | [Browser Accept Header] |
- If verifyenroll call was successful it will return parameters required to make the second API call (‘verifyresp’).
- The table below contains parameters required for the ‘veriresp’ call.
PARAMETER | VALUES |
---|---|
pxy.Transaction.txnPayName | [NameofStripePayProfile] |
pcyThreeSecAuth.actionName | [verifyresp] |
pxyThreeDSecAuth.authTxnId | [threeDSTransactionId – returned from the ‘verifyenroll’ call] |
pxyThreeDSecAuth.messageId | [Response from verifyenroll call – pxyResponse.threeDSMessageId] |
pxyThreeDSecAuth.authAcsUrl | [Response from verifyenroll call – pxyResponse.threeDSAcsUrl] |
3D secure 2 implementation with Sage Payment
- In order to implement 3D secure 2.0 with sage pay, the following parameters are required.
- The table below contains the additional required parameters for the first API call (verifyenroll).
PARAMETERS | VALUES |
---|---|
pxyTransaction.txnPayName | [Sage Pay Payment profile name ] |
pxyThreeDSecAuth.actionName | [verifyenroll] |
pcyThreeDSecAuth.callMode | [reportall] |
pxyCustomerInfo.sessionId | [sessionId] |
pxyCustomerInfo.browserAcceptHeader | [browser accept header] |
pcyCustomerInfo.browserUserAgentHeader | [browser user agent header] |
- If ‘verifyenroll’ call was successful and 3ds was enrolled the response will return some parameters required for the second API call (verifyresp).
- The table below contains parameters required for the ‘verifyresp’ call.
PARAMETERS | VALUES |
---|---|
pxyThreeDSecAuth.actionName | [verifyresp] |
pcyThreeDSecAuth.authTxnId | [pxyResponse.threeDsTransactionID – response of verifyenroll call] |
pxyThreeDSecAuth.paReq | [pxyResponse.threeDSPARequest – response ofverifyenroll call] |
pxyThreeDSecAuth.authAcsUrl | [pxyResponse.threeDSAcsUrl – response ofverifyenroll call] |
pxyCustomerInfo.sessionId | [same as verifyenroll call] |
3D secure 2 implementation with Redsys Rest
In order to implement 3D Secure 2, the Redsys Rest payment profile must include the 3DS OTP Notification URL during the payment profile setup.
PARAMETER NAME | Possible VALUE |
---|---|
3DS OTP Notification URL | https://ccframe.hostedpci.com/iSynSApp/appUserVerify3DResp!verifyResp.action |
3ds 2.0 Redsys Rest “verifyenroll” call
- In Order to implement ThreeDSecure 2.0 with Redsys Rest the following parameters are required.
- The table below contains the parameter required for the verifyenroll call.
PARAMETERS | VALUES |
---|---|
pxyCustomerInfo.browserAcceptHeader | [browserAcceptHeader] |
pxyCustomerInfo.browserUserAgentHeader | [browserUserAgentHeader] |
pxyThreeDSecAuth.callMode | [reportall] |
pxyTransaction.txnPayName | [3dsecProfileName] |
pxyThreeDSecAuth.actionName | [verifyenroll] |
3ds 2.0 Redsys Rest “verifyresp” call
- If ‘verifyenroll’ was successful it will return parameters required for ‘verifyresp’ call.
- The table below contains parameters required to make the second auth call with Redsys Rest 3ds 2.0.
PARAMETERS | VALUES |
---|---|
pxyThreeDSecAuth.authTxnId | [pxyResponse.threeDSTransactionId] – returned from the ‘verifyenroll’ call] |
pxyTransaction.txnPayName | [3dPayProfileName] |
pxyThreeDSecAuth.actionName | [verifyresp] |
pxyThreeDSecAuth.protocolVersion | [pxyResponse.threeDSProtoVersion] – response from the verifyenroll call |
3D secure 2 implementation with Dlocal
In order to implement 3D Secure 2, the Redsys Rest payment profile must include the 3D Secure termURL during the payment profile setup.
PARAMETER NAME | POSSIBLE VALUE |
---|---|
3D Secure termURL | https://ccframe.hostedpci.com/iSynSApp/appUserVerify3DResp!verifyResp.action |
The parameters listed on the page are required along with the mandatory AUTH transaction parameters to make a successful 3DSecure transaction.
3DS 2.0 “Verifyenroll” Call
PARAMETERS | VALUE |
---|---|
pxyTransaction.txnPayName | [3ds payment profile name] |
pxyThreeDSecAuth.actionName | [verifyenroll] |
pxyThreeDSecAuth.callMode | reportall |
pxyThreeDSecAuth.merchantSessionId | [Optional for Dlocal 3DS – can be seen in return Url] |
pxyCustomerInfo.officialDocNumber | [Optional for Dlocal for certain Countries.] |
3DS 2.0 “verifyresp” Call
PARAMETERS | VALUE |
---|---|
pxyTransaction.txnPayName | [3ds payment profile name] |
pxyThreeDSecAuth.actionName | [verifyresp] |
pxyThreeDSecAuth.messageId | [] |
pxyThreeDSecAuth.authTxnId | [returned in the Verifyenroll call] |
Delayed Bin (3DS 2.0)
- This feature works with Cardinal Cruise Implementation.
- At HostedPCI we offer delayedBin feature with 3ds 2.0 implementation.
- DelayedBin feature allows clients to delay the 3ds setup process.
- To enable the Delay Bin feature the iFrame SRC needs to declare “enable3DSec=waitbin”.
- The client can declare the 3ds setup parameters after receiving CC Bin.
- Invoking 3DS setup parameter within a successhandler : sendHPCISet3DSecParamMsg(“cruise1”, “DEF_3DSEC”, “any”, “any”);
There are two ways to implement DelayedBin feature with EarlyTokenization and without EarlyTokenization.
With Early Tokenization.
The image above is the network call of the page containing iFrame with delayedbin and earlytokenization. This process took 1600 ms to complete meaning in 1600ms the form was filled, submitted, returned tokens and card information, and submitted that info. In this process, a token was generated and returned while the user was still filling out the form.
Without Early Token:
- Allows clients to change the credit card number until the form is submitted.
- Token and card numbers are processed and returned after the form has been submitted.
The image above is the network call of the page containing iFrame with delayedbin but not earlytokenization. This process took almost 7000 ms to complete as the Tokenization process does not begin until the form is submitted. In this process, a token was generated and returned while the user was still filling out the form. This process took 4 times longer than the process with earlyTokenization.
Phone Session API Guide
- This guide provides implementation details to set up a telephonic call session and get the mapped credit card for the credit card entered via the telephone.
- The HostedPCI token provided back by the IVR can be stored within your system for future use. The token will remain active for 18 months from the last time it is used.
Prerequisite
PARAMETER NAME | PARAMETER VALUE |
---|---|
API Username | Provided by HPCI after the activation of the HPCI account. |
API Passkey | Pass-Keys are created for individual telephone agent Username through the HostedPCI portal. |
API URL | Provided by HPCI after the activation of the HPCI account. |
* The individual UserName / PassKey combination of the agent in question should be used to create each session.
Call Session Setup Service
- HostedPCI phone session setup service is called to initiate a session on the online portal so that it can be used by the telephonic call.
- This call should be made only once for every phone call.
A session setup service call to HostedPCI requires the following parameters posted to the URL:
http:///iSynSApp/manageCCMapPhoneAPI.action?cmd=createsession&userName=&userPassKey=&promptLang=&cvvEntry=&sessionKeyType=&userMarker1=&userMarker2=&userMarker3=
PARAMETER NAME | PARAMETER VALUE |
---|---|
apiVersion | 1.0.1 |
apiType | pxyhpci |
userName | [API username from HostedPCI] |
userPassKey | [API passkey from HostedPCI] |
cmd | [createsession] |
promptLang | [en_US] |
cvvEntry | [Default value: request, possible values: request | skip] |
sessionKeyType | [Default value: user, possible values: user | venue] |
userMarker1 | [Optional parameter for the user-based session key, the required parameter for venue based session key. Setup user identifying marker for venue based session key to assign sessions handled by a client user.] |
userMarker2 | [Optional parameter. Setup user identifying marker for venue based session key to assign sessions handled by a client user.] |
userMarker3 | [Optional parameter. Setup user identifying marker for venue based session key to assign sessions handled by a client user.] |
ccExpiry | [Default value: skip, possible values: request | skip] |
- The venue-based phone sessions can be created by the phone session API user ID/passkey combination.
- AT least one user marker is necessary to successfully create a venue session and assign the phone session to the user handling the call bridge.
- The API user-id caller handles the responsibility of assigning suitable unique user markers using available user marker fields 1,2, or 3 on the phone session setup API.
- The CVV and Expiry can be collected during the IVR call if the Merchant requires them. To enable this feature please send cvvEntry=request and ccExpiry=request in the API call.
If the call is successful the following return parameters will be provided in a URL encoded result set:
status=success&sessionId=125040&sessionType=ccmap&sessionStatus=open&sessionKey=2034025040&sessionTaskCount=1&sessionTask[1].type=sessionsetup&sessionTask[1].status=created&sessionTask[1].promptCode=created_entersession&sessionTask[1].completionCode=waiting&sessionTask[1].completionCode=waiting&sessionTask[1].exceptionMsg=&sessionTask[1].comment=&sessionTask[1].paramName=&sessionTask[1].paramValue=&sessionTask[1].createTS=
PARAMETER NAME | PARAMETER VALUE |
---|---|
status | [success|error] |
sessionId | [7 digit session id that is used to identify the IVR session] |
sessionType | [Ccmap] |
sessionStatus | [open] |
sessionKey | [Session key to be entered by the telephone operator over the phone call] |
sessionTaskCount | [Task count list for the session] |
sessionTask.type | [sessionsetup| ccmapsetup | cccvvsetup] |
sessionTask.status | [Created | success | failed] |
sessionTask.promptCode | [Created_session | created_enterccnum | created_entercccvv] |
sessionTask.completionCode | [waiting | success | error] |
sessionTask.exceptionMsg | [Message for the exception] |
sessionTask.comment | [Comments] |
sessionTask.createTS | [Create time for the session] |
Call Session Status Service
- HostedPCI phone session status service is called to check the progress of a session so the interaction on the phone service can be reported Periodically.
- This can be invoked multiple times per phone session.
A Session status update service call to HostedPCI requires the following parameters posted to the URL:
http:///iSynSApp/manageCCMapPhoneAPI.action?cmd=showprogress&userName=&userPassKey=&selectedPcsId=
PARAMETER NAME | PARAMETER VALUE |
---|---|
userName | API username from HostedPCI |
userPassKey | API passkey from HostedPCI |
cmd | showprogress |
selectedPcsId | 7 digit session-id that was received when IVR session was created |
Required Parameters:
If the call is successful the following return parameters will be provided based on the progress of the session:
status=success&sessionId=&sessionType=ccmap&sessionStatus=complete&sessionKey= &sessionTaskCount=3&sessionTask[1].type=sessionsetup&sessionTask[1].status=success&sessionTask[1].promptCode=created_entersession&sessionTask[1].completionCode=success&sessionTask[1].completionCode=success&sessionTask[1].respToken1=&sessionTask[1].respToken2=&sessionTask[1].respToken3=&sessionTask[1].exceptionId=&sessionTask[1].exceptionMsg=&sessionTask[1].comment=&sessionTask[1].paramName=&sessionTask[1].paramValue=&sessionTask[1].createTS= &sessionTask[2].type=ccmapsetup&sessionTask[2].status=success&sessionTask[2].promptCode=created_enterccnum&sessionTask[2].completionCode=success&sessionTask[2].completionCode=success&sessionTask[2].respToken1=&sessionTask[2].respToken2=&sessionTask[2].respToken3=&sessionTask[2].exceptionId=&sessionTask[2].exceptionMsg=&sessionTask[2].comment=&sessionTask[2].paramName=mappedcc&sessionTask[2].paramValue= &sessionTask[2].createTS=<>createTime&sessionTask[3].type=cccvvsetup&sessionTask[3].status=success&sessionTask[3].promptCode=created_entercccvv&sessionTask[3].completionCode=success&sessionTask[3].completionCode=success&sessionTask[3].respToken1=100&sessionTask[3].respToken2=&sessionTask[3].respToken3=&sessionTask[3].exceptionId=&sessionTask[3].exceptionMsg=&sessionTask[3].comment=Masked+CVV%3A100&sessionTask[3].paramName=&sessionTask[3].paramValue=&sessionTask[3].createTS=
PARAMETER NAME | PARAMETER VALUE |
---|---|
status | [success|error] |
sessionid | [7 digit session id that is used to identify the IVR session] |
sessionType | [Ccmap] |
sessionStatus | [open|closed|terminate] |
sessionKey | [Session key to be entered by the telephone operator over the phone call] |
sessionTaskCount | [Task count list for the session] |
sessionTask.type | [sessionsetup| ccmapsetup | cccvvsetup] |
sessionTask.status | [Created | success | failed] |
sessionTask.promptCode | [Created_session | created_enterccnum | created_entercccvv] |
sessionTask.completionCode | [waiting | success | error] |
respToken1 | [Extra details for the response. This field will contain the mapped CVV token for task type cccvvsetup] |
respToken2 | [Extra details for the response.] |
respToken3 | [Extra details for the response] |
sessionTask.exceptionMsg | [Message for the exception] |
sessionTask.exceptionId | [ID for the exception] |
sessionTask.comment | [Comments] |
sessionTask.createTS | [Create time for the session] |
sessionTask.paramName | [Mappedcc] |
sessionTask.paramValue | [Tokenized credit card number] |
Clear Call CVV Service
- HostedPCI phone CVV clearing service is called to clear any stored CVV values for the session.
- This call should be made only once for every phone call.
- This call is not required, the CVV will be cleared after it is used for the Authorize or Sale call or at the end of session expiry.
A CVV clearing service call to HostedPCI requires the following parameters posted to the URL:
http:///iSynSApp/manageCCMapPhoneAPI.action?cmd=clearcvv&userName= &userPassKey= &selectedPcsId=
Required Parameters:
PARAMETER NAME | PARAMETER VALUE |
---|---|
userName | API username from HostedPCI |
userPassKey | API passkey from HostedPCI |
cmd | clearcvv |
selectedPcsId | 7 digit session-id that was received when IVR session was created |
If the call is successful the following return parameters will be provided in a URL encoded result set:
status=success&sessionId=125040&sessionType=ccmap&sessionStatus=open&sessionKey=2034025040& sessionTaskCount=1&sessionTask[1].type=sessionsetup&sessionTask[1].status=created& sessionTask[1].promptCode=created_entersession&sessionTask[1].completionCode=waiting& sessionTask[1].completionCode=waiting&sessionTask[1].exceptionMsg=&sessionTask[1].comment=& sessionTask[1].paramName=&sessionTask[1].paramValue=&sessionTask[1].createTS=
PARAMETER NAME | PARAMETER VALUE |
---|---|
status | [success|error] |
sessionId | [7 digit session id that is used to identify the IVR session] |
sessionType | [Ccmap] |
sessionStatus | [open|closed|terminate] |
sessionKey | [Session key to be entered by the telephone operator over the phone call] |
sessionTaskCount | [Task count list for the session] |
sessionTask.type | [sessionsetup| ccmapsetup | cccvvsetup] |
sessionTask.status | [Created | success | failed] |
sessionTask.promptCode | [Created_session | created_enterccnum | created_entercccvv] |
sessionTask.completionCode | [waiting | success | error] |
sessionTask.exceptionMsg | [Message for the exception] |
sessionTask.comment | [Comments] |
sessionTask.createTS | [Create time for the session] |
Terminate Call Session Service
- HostedPCI phone session terminates service is called to terminate the phone session by administrator request.
- The Phone session will be terminated when ‘#’ Key is entered on the phone session.
- This call should be made only once for every call.
- This call is not required, the call can progress to a natural completion.
A session termination service call to HostedPCI requires the following parameters posted to the URL:
http:///iSynSApp/manageCCMapPhoneAPI.action?cmd=terminatesession&userName=&userPassKey=&selectedPcsId=
Required Parameters
PARAMETER NAME | PARAMETER VALUE |
---|---|
userName | API username from HostedPCI |
userPassKey | API passkey from HostedPCI |
cmd | terminatesession |
selectedPcsId | 7 digit session-id that was received when IVR session was created |
If the call is successful the following return parameters will be provided in a URL encoded result set:
status=success&sessionId=125040&sessionType=ccmap&sessionStatus=terminate&sessionKey=2034025040& sessionTaskCount=1&sessionTask[1].type=sessionsetup&sessionTask[1].status=created& sessionTask[1].promptCode=created_entersession&sessionTask[1].completionCode=waiting& sessionTask[1].completionCode=waiting&sessionTask[1].exceptionMsg=&sessionTask[1].comment=& sessionTask[1].paramName=&sessionTask[1].paramValue=&sessionTask[1].createTS=
PARAMETER NAME | PARAMETER VALUE |
---|---|
status | [success|error] |
sessionid | [7 digit session id that is used to identify the IVR session] |
sessionType | [Ccmap] |
sessionStatus | [terminate] |
sessionKey | [Session key to be entered by the telephone operator over the phone call] |
sessionTaskCount | [Task count list for the session] |
sessionTask.type | [sessionsetup| ccmapsetup | cccvvsetup] |
sessionTask.status | [Created | success | failed] |
sessionTask.promptCode | [Created_session | created_enterccnum | created_entercccvv] |
sessionTask.completionCode | [waiting | success | error] |
sessionTask.exceptionMsg | [Message for the exception] |
sessionTask.comment | [Comments] |
sessionTask.createTS | [Create time for the session] |
Phone API Error Codes
The following status or error codes may be returned by HPCI Phone API calls. Errors will be returned in the sessionTask.exceptionMsg field.
Status Codes / Messages
- MCMP_ACT_1 – Session created
- MCMP_ACT_3 – Session cleared, CVV removed from cache on request
Errors Codes / Messages
- MCMP_ACT_2 – Packet replay error
- MCMP_ACT_4 – Phone session not found
- MCMP_ACT_5 – Unknown command
Creating an API Passkey Through the HPCI Portal
To create an individual user passkey, login to the production HPCI portal for the user name in question (the phone agent) and navigate to account Update Passkey
Enter the password of the agent again and click “Generate key”. You will get a success message.
To view the passkey, enter the agent password again and click on “View key”. The key can be stored and used in the application used to generate call sessions through the API for the HostedPCI IVR solution.
Dispatch Web Services API Guide
- The HostedPCI Dispatch Web Services API can be accessed by any eCommerce system that needs to submit credit card transactions to a 3rd party web service with the use of the HPCI credit card tokens.
- Tokens can be obtained through the implementation of the HPCI Express iFrame solution or the mobile page proxy solution.
- This document assumes that HPCI tokens have been generated and available for use with the HPCI Dispatch Web Service API.
- API Transaction services included in this document: DISPATCH
Implementation Platforms
HPCI Dispatch Web Service API can be used in any programming language that supports HTTPS calls. Examples include Java, PHP, and C #.Net.
Setting up API Calls
All API calls to HostedPCI are made over HTTPS to an HPCI hostname that will be provided to you during the account setup. Parameters are passed to HCPI through standard the HTTPS POST method. Name-Value pairs are separated by & characters and are URL Encoded.
Required Parameters for All API Calls
- apiVersion, value “1.0.1”
- apiType, value “pxyhpci”
- userName, value [API UserId]
- userPassKey, value [API Passkey]
Specifying the Dispatch Profile Name
Multiple dispatch endpoints can be set up with HPCI and specified per API call. Dispatch profile names can be specified with the parameter below. This parameter is required. Dispatch profile names must be pre-arranged with the HPCI team.
- dispatchRequest.profileName, value [Name of Dispatch Profile to use]
Reading Results from API Calls
Once an HTTPS call is made to an HPCI Web Service API, results will be returned in standard Name-Value pair format with URL Encoded values.
Credit Card Dispatch Transaction (DISPATCH)
API Endpoint: http://HPCI_API_HOSTNAME/iSynSApp/paymentMsgDispatch.action
Additional Required Parameters:
Dispatch Content Related Parameters
- dispatchRequest.contentType, value [Content type for the dispatch request to destination e.g: urlencode / xml / html / plain / json ]
- dispatchRequest.request, value [Fully prepared message for delivery to destination with place holders for Credit Card and CVV tokens]
- dispatchRequest.prefixRequest, value [Any prefix that needs to be prefixed to the request data e.g: Softvoyage needs xml as the prefix]
Credit Card Token Related Parameters
Token details are passed as parameters in an array, notated by [ ] array syntax. Repeat the following parameters for each token that is being processed.
Where [x] starts at 0 and increases with each item added.
- ccParamList[x].ccMsgToken, value [Name of the place holder token for credit card number in the request message, e.g: %%CC1%%]
- ccParamList[x].ccToken, value [Tokenized CC value for the place holder value, this value is retrieved from the iframe]
- ccParamList[x].cvvMsgToken, value [Name of the place holder token for CVV in the request message, e.g: %%CVV1%%]
- ccParamList[x].cvvToken, value [Tokenized CVV value for the place holder CVV]
Header Related Parameters (Optional)
HTTP Header values may also be sent to the destination along with the message payload. Details are passed as parameters in an array, notated by [ ] array syntax. Repeat the following parameters for each token that is being processed.
Where [x] starts at 0 and increases with each item added.
- headerList[x].strValue1, value [Name of the header for destination]
- headerList[x].strValue2, value [Value of the header for destination]
API Response Variables
This API call responds with the following name-value pairs.
- status, value [success | error]
The Status response variable indicates if the API call is well-formed, with an appropriate result. It does not guarantee a successful credit card transaction with a complete authorization or capture if the status is returned as a success. Other parameters must be checked, see below
- pxyResponse.responseStatus, value [approved I declined | error | review | dispatched]
The transaction response considered successful for pxyResponse.responseStatus is the approved or dispatched status. Any other response should be considered an error. In case of an error transaction, the error code may be obtained as per the following response variable:
- pxyResponse.responseStatus.code, value [alphanumeric code representing response]
- pxyResponse.responseStatus.description, value [long description and informational text of response]
- pxyResponse.dispatchResp, value [Dispatch response]
The dispatch response variable contains the scrubbed response from the dispatch endpoint.
File Dispatch Web Services API Guide
The hostedPCI File Dispatch Web Services API can be accessed by any ecommerce or call centre system that need to submit files of credit card transactions to a 3rd party web service or processors with the use of the HPCI credit card token. Tokens can be obtained through the implementation of the HPCI Iframe solution or the HPCI IVR solution. This document assumes that HPCI tokens have been generated and available for use with the HPCI File Dispatch Web Service API.
We have implemented services with Chase Account Updater and Auric System..
Implementation Platforms
HPCI Dispatch Web Service API can be used in any programming language that supports HTTPS calls. Examples include Java, PHP, and C #.Net.
Setting up API Calls
All API calls to HostedPCI are made over HTTPS to an HPCI hostname that will be provided to you during account setup. Parameters are passed to HCPI through standard the HTTPS POST method. Name-Value pairs are separated by & characters and are URL Encoded.
File Dispatch API Action URL
“https://api-[venue name].c1.hostedpci.com/iSynSApp/paymentFileDispatch.action”
apiVersion | This parameter is required for making API calls to HPCI, and should be set to the value “1.0.1” |
apiType | This parameter is required for making API calls to HPCI, and this parameter should be set as “pxyhpci” |
userName | This information is provided by HPCI and is required in order to determine which vault is being used. |
userPassKey | This information is provided by HPCI and is required to confirm the vault that is being used. |
Specifying the File Dispatch Profile Name
HostedPCI allows for multiple endpoints to be configured using our solution, and are specified using the profile name. The parameter listed below is required for all File Dispatch API calls made to HostedPCI.
dispatchRequest.profileName | his parameter is required for making API calls regardless of the number of profiles, and the “profile name ” must be pre-arranged with the HostedPCI team. |
Additional Required Parameters
When using the File Dispatch API it is important to ensure that all required parameters are being used, if a required parameter is missing the API action will result in an error.
File Dispatch Related Parameters
dispatchRequest.contentType | This parameter provides details about the content type for the File Dispatch the request to the destination. Example: urlencode / xml / html / plain / json |
dispatchRequest.request | This parameter is the fully prepared message for delivery to destination with place holders for Credit Card and CVV tokens |
Preparing and Sending Files to HostedPCI
Sample File
The layout and contents of a file will be decided between the customer and the 3rd party processor. HostedPCI only cares about the token field for mapping. Below is a basic example of a possible file. The type of file being sent also does not matter to HostedPCI as long as we know where to grab the token and place the credit card.
Sample
Card Number, Expiry, Amount
4242000000104242, 05/16, 45.45
4111000000301111, 09/17, 65.23
4444000000051111, 10/18, 56.79
Front End Processing
Once the file is prepared it must be uploaded to the companies server in order to be sent to HostedPCI.
jQuery("#filedispatchBtn").click(function(){ var file = jQuery("#filedispatch_file").val(); var blob = new Blob([file], { type: "text/plain"}); var formData = new FormData(); formData.append("tokenFile", blob, "data.csv"); formData.append("dispatchRequest.destFileName", "data.csv"); formData.append("dispatchRequest.profileName" , jQuery("#paymentProfile_filedispatch").val()); jQuery.ajax({ url: "FileDispatchServlet", type: "POST", data: formData, processData: false, // tell jQuery not to process the data contentType: false // tell jQuery not to set contentType }).done(function(data) { //Process the ajax call result.. }); });
Server to Server Call
private static final String PXY_MSGDISPATCH = "/iSynSApp/paymentFileDispatch.action"; private static final String PXYPARAM_APIVERSION = "apiVersion"; private static final String PXYPARAM_APIVERSION_NUM = "1.0.1”; private static final String PXYPARAM_APITYPE = "apiType"; private static final String PXYPARAM_APITYPE_PXYHPCI = "pxyhpci"; private static final String PXYPARAM_DISPATCHREQUEST_PROFILENAME = "dispatchRequest.profileName"; private static final String PXYPARAM_DISPATCHREQUEST_DESTFILENAME = "dispatchRequest.destFileName"; private static final String PXYPARAM_USERNAME = "userName"; private static final String PXYPARAM_USERPASSKEY = "userPassKey"; public static String callUrl(String urlString, MapparamMap, String fileName, File dispatchFile) { String urlReturnValue = ""; String charset = "UTF-8"; String boundary = Long.toHexString(System.currentTimeMillis()); // Just generate some unique random value. String CRLF = "\r\n"; // Line separator required by multipart/form-data. try { URLConnection connection = new URL(urlString).openConnection(); connection.setDoOutput(true); connection.setRequestProperty("Content-Type", "multipart/form-data; boundary=" + boundary); PrintWriter writer = null; try { OutputStream output = connection.getOutputStream(); writer = new PrintWriter(new OutputStreamWriter(output, charset), true); // Send normal param. for (Entry paramEntry : paramMap.entrySet()) { writer.append("--" + boundary).append(CRLF); writer.append("Content-Disposition: form-data; name=\"" + paramEntry.getKey() + "\"").append(CRLF); writer.append("Content-Type: text/plain; charset=" + charset).append(CRLF); writer.append(CRLF); writer.append(paramEntry.getValue()).append(CRLF).flush(); } // Send text file. writer.append("--" + boundary).append(CRLF); writer.append("Content-Disposition: form-data; name=\"tokenFile\"; filename=\"" + fileName +"\"").append(CRLF); writer.append("Content-Type: text/plain; charset=" + charset).append(CRLF); writer.append(CRLF).flush(); BufferedReader reader = null; try { reader = new BufferedReader(new InputStreamReader(new FileInputStream(dispatchFile), charset)); for (String line; (line = reader.readLine()) != null;) { writer.append(line).append(CRLF); } } finally { if (reader != null) try { reader.close(); } catch (IOException logOrIgnore) {} } // End of multipart/form-data. writer.append("--" + boundary + "--").append(CRLF); writer.flush(); // Get the response BufferedReader rd = new BufferedReader(new InputStreamReader(connection.getInputStream())); String line; while ((line = rd.readLine()) != null) { urlReturnValue = urlReturnValue + line; } rd.close(); } finally { if (writer != null) writer.close(); } } catch (Exception e) { e.printStackTrace(); urlReturnValue = ""; } return urlReturnValue; } private String dispatchOnly(String serviceUrl, String userName, String userPassKey, String fileName, String destFileName, File dispatchFile) { // make the remote call String callUrl = serviceUrl + PXY_MSGDISPATCH; // prepare the api call Map paramMap = new HashMap (); paramMap.put(PXYPARAM_APIVERSION, PXYPARAM_APIVERSION_NUM); paramMap.put(PXYPARAM_APITYPE, PXYPARAM_APITYPE_PXYHPCI); paramMap.put(PXYPARAM_USERNAME, userName); paramMap.put(PXYPARAM_USERPASSKEY, userPassKey); paramMap.put(PXYPARAM_DISPATCHREQUEST_PROFILENAME, "DISPATCHEXAVAULT"); if(destFileName != null && !destFileName.isEmpty()) paramMap.put(PXYPARAM_DISPATCHREQUEST_DESTFILENAME, destFileName); logMessage("========================================================"); logMessage("Make the call: " + callUrl); logMessage("Call payload: " + paramMap); String callResult = callUrl(callUrl, paramMap, fileName, dispatchFile); logMessage("Call result:" + callResult); // parse the url encoded key value pairs Map resultMap = DemoUtil.parseQueryString(callResult); // get the network call status String callStatus = resultMap.get(PXYRESP_CALL_STATUS); if (callStatus != null && callStatus.equals(PXYRESP_CALL_STATUS_SUCCESS)){ logMessage("Successful transaction"); authId = resultMap.get(PXYRESP_AUTH_ID); logMessage("Auth Ref Id:" + authId); } else { logMessage("Unsuccessful transaction"); String statusCode = resultMap.get(PXYRESP_RESPSTATUS_CODE); String statusName = resultMap.get(PXYRESP_RESPSTATUS_NAME); String statusDesc = resultMap.get(PXYRESP_RESPSTATUS_DESCRIPTION); logMessage("Auth Status Code:" + statusCode); logMessage("Auth Status Name:" + statusName); logMessage("Auth Status Desc:" + statusDesc); } return callResult; }
API Response Variables
This API call responds with the following name-value pairs. The response being provided back is only of the upload success or failure there will be no status of the credit card processing.
status | The Status response variable indicates if the API call is well formed, with an appropriate result. It does not guarantee a successful credit card transaction with a complete authorization or capture if the status is returned as success. Other parameters must be checked, see below. The value will either be success or failure. |
pxyResponse.responseStatus | The transaction response considered successful for pxyResponse.responseStatus is the approved or dispatched status. Any other response should be considered an error. In case of an error transaction, the error code may be obtained as per the following response variables below. The possible values are either approved, declined, error, review and dispatched. |
authId | is an enteral number provided by HostedPCI for your records only. |
pxyResponse.processorType | This parameter provides you with the type of response being provided, the value will always be fileDispatchResponse |
pxyResponse.fileRowCount | This parameter provides you with an update on how many columns have been provided within the file. This will indicated how many tokens were provided to HostedPCI. |
pxyResponse.responseStatus.code | This parameter provides you with an alphanumeric code that can assist with understanding the response being provided back as well as debugging. |
pxyResponse.responseStatus.description | This parameter will provide a brief description of the response being provided, which can assist with any errors that may occur. |
pxyResponse.dispatchResp | The dispatch response variable contains the scrubbed response from the dispatch endpoint, the value will be dispatch response. |
Chase Account Updater
Hosted PCI has integrated with Chase Account Updater. With this Integration our clients will be able to update the cards in their vault and continue to use it to process even if the card numbers, expiry date or other details has been updated.
Chase Account Updater API URL
https://api-[venue name].c1.hostedpci.com/iSynSApp/paymentChaseAcctUpdateDispatch.action
Step 1 – Chase Account Updater Dispatch Call
The first step of the Chase Account Updater Process. The step is making a dispatch call with the file in a specific format. Please take a look at a sample request Dispatch file.
sample of Dispatch File
Please make sure each line length is 121 (put empty space at the end)
Dispatch call API Request sample:
apiType=pxyhpci&apiVersion=1.0.1&dispatchRequest.destFileName=PID.FILENAME.format&dispatchRequest.profileName=HPCI profileName&dispatchRequest.reqUserName=AccountUpdUsername&dispatchRequest.reqUserPwd=AccountUptPassword&dispatchRequest.requestMode=dispatch&userName=HPCIUsername&userPassKey=HPCIPasskey
dispatchRequest.destFileName | The name of the Dispatch file. As per Chase the name should be: PID.fileID.extension |
dispatchRequest.profileName | Name of the Chase Account Updater Profile in the Merchant’s Venue. |
dispatchRequest.reqUserName | Chase Account Updater Dispatch Username. |
dispatchRequest.reqUserPwd | Chase Account Updater Dispatch Password. |
dispatchRequest.requestMode | dispatch | listfiles | fetch |
Step 2 – Chase Account Updater List Files Call
This is the second step of the Chase Account Updater Process. This step should occur 10 minutes after the dispatch was completed. This call will return the list of the files in the Client’s Chase Account Updater portal. In the response there will be a file with _resp in the file name which will contain detail about the earlier dispatch file.
i.e. PID.fileID_RANDOMNUMS_resp.pgp (DispatchFileName_RandomNums_resp.pgp)
ListFiles call API Request sample:
apiType=pxyhpci&apiVersion=1.0.1&dispatchRequest.profileName=HPCIProfileName&dispatchRequest.reqUserName=AccountUpdUsername&dispatchRequest.reqUserPwd=AccountUpdPassword&dispatchRequest.requestMode=listfiles&userName=HPCIUsername&userPassKey=HPCIPasskey
Step 3 – Chase Account Updater Fetch Call
This is the third step of the Chase Account Updater Process. This process will make a fetch call to the file which name was returned in the list files call (Step 2).
fetch file name: PID.fileID_RANDOMNUMS_resp.pgp
Fetch call API Request sample:
apiType=pxyhpci&apiVersion=1.0.1&dispatchRequest.destFileName=PID.fileID_RANDOMNUMS_resp.pgp&dispatchRequest.profileName=HPCIProfileName&dispatchRequest.reqUserName=AccountUpdUsername&dispatchRequest.reqUserPwd=AccountUpdPassword&dispatchRequest.requestMode=fetch&userName=HPCIUsername&userPassKey=HPCIPasskey
sample of the fetch file (dispatch status)
This is the response file which contains information on the status of the dispatch call.
This file is same as the Dispatch file with extra details added to the record lines.
Step 4 – Chase Account Updater List Files Call
This is the Fourth step of the Chase Account Updater Process. This step should be done everyday if there are records expected to be returned. This call will return the files in the Client’s Chase Account Updater portal. Please look out for files with the todays date and card brand.
i.e. PID.MID.221220.VAU_resp.txt
The response file name breakdown
PID = Client’s Chase Account Updater PID
MID = Client’s Chase Account Updater Merchant ID
221220 = Today’s date (YYMMDD)
VAU_resp / MAU_resp = VISA Account Update file / MasterCard Account Update response file
txt = file format
ListFiles call API Request sample:
apiType=pxyhpci&apiVersion=1.0.1&dispatchRequest.profileName=HPCIProfileName&dispatchRequest.reqUserName=AccountUpdUsername&dispatchRequest.reqUserPwd=AccountUpdPassword&dispatchRequest.requestMode=listfiles&userName=HPCIUsername&userPassKey=HPCIPasskey
Step 5 – Chase Account Updater Fetch Call
This is the Fifth step of the Chase Account Updater Process. This process will make a fetch call to the file which name was returned in the previous list files call (Step 4).
fetch file name: PID.MID.221220.VAU_resp.txt
Fetch call API Request sample:
apiType=pxyhpci&apiVersion=1.0.1&dispatchRequest.destFileName=PID.MID.221220.VAU_resp.txt&dispatchRequest.profileName=HPCIProfileName&dispatchRequest.reqUserName=AccountUpdUsername&dispatchRequest.reqUserPwd=AccountUpdPassword&dispatchRequest.requestMode=fetch&userName=HPCIUsername&userPassKey=HPCIPasskey
Auric System
Dispatch Call
Dispatch call with Auric is the same process as the regular HPCI File Dispatch request. Please see the documentation HERE.
Fetch Call
In order to make fetch call with Auric Please call this Endpoint.
https://api-[venue name].c1.hostedpci.com/iSynSApp/paymentAuricFileDispatch.action
Sample Auric Fetch call:
apiType=pxyhpci&apiVersion=1.0.1&dispatchRequest.destFileName=DestinationFileName&dispatchRequest.profileName=HPCIProfileName&dispatchRequest.reqUserName=AuricUsername&dispatchRequest.reqUserPwd=AuricPassword&userName=HPCIAPIUsername&userPassKey=HPCIAPIPassword
Gateway Parameter Guide
Acapture services were integrated by HostedPCI in 2017, we support the following credit card processing features by Acapture.
Implemented Features | Auth Sale (Auth + Capture) Capture Void Credit Soft Descriptors |
Authentication and security credentials | User ID Password Entity ID |
Adyen services were integrated by HostedPCI since 2015, we support the following credit card processing features provided by Adyen.
Implemented Features | Auth Sale (Auth + Capture) Capture Void Credit |
Authentication and security credentials | wsUser wsPassword Merchant ID |
AdyenRest services were integrated by HostedPCI since 2019, we support the following credit card processing features provided by AdyenRest.
Implemented Features | Auth Sale (Auth + Capture) Capture Void Credit |
Authentication and security credentials | Username Password |
Adyen Json services were integrated by HostedPCI in 2021, we support the following credit card processing features provided by Adyen Json.
Implemented Features | Auth Sale (Auth + Capture) Capture Void Credit Card on File 3DS 2 Passthrough Soft Descriptors |
Authentication and security credentials | Username Password Account Name API Key URL prefix – Random Name (LIVE) URL prefix – Company Name (LIVE) |
Authorize.net services were integrated by HostedPCI since 2010, we support the following credit card processing features by Authorize.Net.
Implemented Features | Auth Sale (Auth + Capture) Capture Void Credit Gateway Tokenization 3DS 2 Passthrough |
Authentication and security credentials | Login ID Transaction Key |
Authorize.net services were integrated by HostedPCI since 20222, we support the following credit card processing features by American Express.
Implemented Features | Auth Sale (Auth + Capture) Capture Void Credit 3DS 2 Passthrough Card on File |
Authentication and security credentials | Origin (Username) Merchant ID (password) Merchant Country Code Merchant Region Authorization Route Indicator Submission Route Indicator Merchant Type Category Code Submitter Code |
Bambora services were integrated by HostedPCI since 2013, we support the following credit card processing features provided by Bambora.
Implemented Features | Auth Sale (Auth + Capture) Capture Void Credit Credentials on File |
Authentication and security credentials | User ID Password Merchant ID |
Braintree services were integrated by HostedPCI in 2016, we support the following credit card processing features by Braintree.
Implemented Features | Auth Sale (Auth + Capture) Capture Void Credit Credentials on File 3DS 2 Passthrough Soft Descriptors |
Authentication and security credentials | Merchant ID Public Key Private Key |
CardConnect services were integrated by HostedPCI in 2015, we support the following credit card processing features by CardConnect.
Implemented Features | Auth Sale (Auth + Capture) Capture Void Credit Gateway Tokenization |
Authentication and security credentials | Username Password Merchant ID Terminal ID URL Prefix |
Card Stream services were integrated by HostedPCI in 2021, we support the following credit card processing features by Card Stream.
URL: www.cardstream.com/
Implemented Features | Auth Sale (Auth + Capture) Capture Void Credit |
Authentication and security credentials | Merchant ID Signature |
CenPOS services were integrated by HostedPCI since 2014, we support the following credit card processing features by CenPOS.
Implemented Features | Auth Sale (Auth + Capture) Capture Void Credit Gateway Tokenization |
Authentication and security credentials | MerchandID UserID Password |
Charge Logic services were integrated by HostedPCI since 2017, we support the following credit card processing features provided by Charge Logic.
Implemented Features | Auth Sale Gateway Tokenization |
Authentication and security credentials | StoreNo APIKey ApplicationNo ApplicationVersion |
Chase Account Updater has been integrated with HostedPCI since 2022. This service allows Merchants to Update the Credit Card data in their Vault which have been updated since.
Implemented Features | Display Fetch Fetch File list |
Authentication and security credentials | SFTP Username SFTP Password PGP Public Key PGP Private Key PGP Private Key Pass Phrase |
Chase Payment Batch services were integrated by HostedPCI since 2016, we support the following credit card processing features provided by Chase Payment Batch.
Implemented Features | Display Fetch Fetch File list |
Authentication and security credentials | SFTP Username SFTP Password PGP Private Key PGP Private Key Pass Phrase |
Chase Paymentech services were integrated by HostedPCI since 2011, we support the following credit card processing features by Chase Paymentech.
Implemented Features | Auth Sale (Auth + Capture) Capture Void Credit Gateway Tokenization 3DS 2 Passthrough Soft Descriptors |
Authentication and security credentials | Merchant ID Bin Terminal ID |
Supported Parameters | pxyOrder.shippingReference (Shipping Reference) |
In order for Payments to be delivered to Chase clients have to whitelist our Submitter ID on your merchant account.
Submitter ID: 980491
CyberSource services were integrated by HostedPCI since 2009, we support the following credit card processing features by CyberSource.
Implemented Features | Auth Sale (Auth + Capture) Capture Void Credit Soft Descriptors |
Authentication and security credentials | Merchant ID (username) Transaction Key |
CyberSource Account Updater was integrated by HostedPCI in 2017, we support the following credit card processing features.
Implemented Features | Auth Sale (Auth + Capture) Capture Void Credit |
Authentication and security credentials | Username Password PGP Private Key PGP Private Key Password Merchant ID P12 Certificate name SSL Key |
DataCash services were integrated by HostedPCI in 2016, we support the following credit card processing features by DataCash.
Implemented Features | Auth Sale (Auth + Capture) Capture Void Credit |
Authentication and security credentials | Client ID Password |
Divitia Global services were integrated by HostedPCI since 2015, we support the following credit card processing features provided by Divitia Global.
Implemented Features | Auth Sale (Auth + Capture) |
Authentication and security credentials | VID Password Track ID |
Dlocal services were integrated by HostedPCI since 2018, we support the following credit card processing features provided by Dlocal.
URL: https://dlocal.com/
Implemented Features | Auth Sale (Auth + Capture) Capture Void Credit Gateway Tokenization 3DS Full Integration Soft Descriptors |
Authentication and security credentials | Merchant xLogin Merchant xTransKey Secret Key Notification_url |
Supported Parameters | pxyCustomerInfo.officialDocNumber (Tax IDs for Brazil and Mexico)
pxyTransaction.merchantProductName (Product name that will appear on statement ) pxyOrder.description (Description of charge ) |
Ebanx services were integrated by HostedPCI since 2022, we support the following credit card processing features provided by Ebanx.
URL: www.ebanx.com/en/
Implemented Features | Auth Sale (Auth + Capture) Capture Void Credit Gateway Tokenization 3DS 2 Passthorugh |
Authentication and security credentials | Public Integration Key Integration Key |
Ebiz Charge services were integrated by HostedPCI since 2020, we support the following credit card processing features provided by EbizCharge.
URL: www.ebizcharge.com
Implemented Features | Auth Sale (Auth + Capture) Capture Void Credit Gateway Tokenization |
Authentication and security credentials | UserID Password Security ID |
Eigen services were integrated by HostedPCI since 2013, we support the following credit card processing features by Eigen.
Implemented Features | Auth Sale (Auth + Capture) Capture Credit |
Authentication and security credentials | Terminal ID Hash Password |
Elavon services were integrated by HostedPCI in 2016, we support the following credit card processing features by Elavon.
Implemented Features | Auth Sale (Auth + Capture) Capture Void Credit Gateway Tokenize Automated Clearing House (ACH) |
Authentication and security credentials | Merchant ID User ID PIN |
Elavon services were integrated by HostedPCI in 2016, we support the following credit card processing features by Elavon.
Implemented Features | Auth Sale (Auth + Capture) Capture Void Credit Gateway Tokenization |
Authentication and security credentials | Username Password Refuned Password |
Elavon Relaex 2 services were integrated by HostedPCI in 2023, we support the following credit card processing features by Elavon.
Implemented Features | Auth Sale (Auth + Capture) Capture Void Credit Credentials on File Gateway Tokenization 3D Secure 2.x |
Authentication and security credentials | MerchantId Account Id Shared Secret Refund Password Rebate Password |
EMerchantpay services were integrated by HostedPCI in 2021, we support the following credit card processing features provided by Emerchantpay.
Implemented Features | Auth Sale (Auth + Capture) Capture Void Credit 3DS 2 Passthrough Soft Descriptors Card On File |
Authentication and security credentials | Username Password AccountID/Token |
Eway services were integrated by HostedPCI in 2022, we support the following credit card processing features provided by Eway.
URL: www.eway.com.au/
Implemented Features | Auth Sale (Auth + Capture) Capture Void Credit 3DS 2 Passthrough |
Authentication and security credentials | Password Key Partner ID |
First Data IPG services were integrated by HostedPCI since 2021, we support the following credit card processing features by First Data Payment.
Implemented Features | Auth Sale (Auth + Capture) Capture Void Credit 3DS 2 Passthrough Credentials on File Soft Descriptors |
Authentication and security credentials | API Key API Secret API Store ID APP Name |
First Data Global Gateway services were integrated by HostedPCI, we support the following credit card processing features by First Data Global Gateway.
Implemented Features | Auth Sale (Auth + Capture) Capture Void Credit |
Authentication and security credentials | Gateway ID Gateways Password |
First Data Payeezy services were integrated by HostedPCI in 2016, we support the following credit card processing features.
URL: https://www.firstdata.com/en_us/all-features/payeezy.html
Implemented Features | Auth Sale (Auth + Capture) Capture Void Credit Gateway Tokenization Credentials on File Soft Descriptors |
Authentication and security credentials | API Key API Secret Merchant Token |
First Data Virtual Terminal (previouisly knows as Linkpoint) services were integrated by HostedPCI since 2012, we support the following credit card processing features by First Data Virtual Terminal.
Implemented Features | Auth Sale (Auth + Capture) Capture Void Credit |
Authentication and security credentials | P.12 certificate |
Fluidpay services were integrated by HostedPCI since 2022, we support the following credit card processing features by FluidPay.
URL: www.fluidpay.com/
Implemented Features | Auth Sale (Auth + Capture) Capture Void Credit Gateway Tokenize 3DS 2 Passthrough Card on File |
Authentication and security credentials | API Username API Password API Key |
Global Collect services were originally integrated by HostedPCI in 2013, However we have recently updated our API integration.
Implemented Features | Auth Sale (Auth + Capture) Capture Void Credit |
Authentication and security credentials | API Key ID Secret API Key |
Supported Parameters | pxyCustomerInfo.birthDate (Customer’s Birth Date)
pxyCustomerInfo.billingLocation.title (Billing Title) pxyCustomerInfo.shippingLocation.title (Shipping Title) |
Global Collect services were originally integrated by HostedPCI in 2013, However we have recently updated our API integration.
Implemented Features | Auth Sale (Auth + Capture) Capture Void Credit |
Authentication and security credentials | API Key ID Secret API Key Merchant ID |
Global Payment services were integrated by HostedPCI since 2019, we support the following credit card processing features provided by Global Payment.
Implemented Features | Auth Sale (Auth + Capture) Capture Void Credit Gateway Tokenization |
Authentication and security credentials | Merchant ID Shared Secret Refund Password (Not enabled by default) |
Helcim services were integrated by HostedPCI since 2014, we support the following credit card processing features provided by Helcim.
Implemented Features | Auth Sale (Auth + Capture) Capture Void Credit Gateway Tokenize |
Authentication and security credentials | Merchant ID (AccountID) API Token |
Highradius services were integrated by HostedPCI since 2024, we support the following credit card processing features provided by Highradius.
URL: www.highradius.com
Implemented Features | Auth Sale (Auth + Capture) Capture Void Credit Gateway Tokenize |
Authentication and security credentials | Client System Id Security Key |
iATS Payments services were integrated by HostedPCI since 2013, we support the following credit card processing features provided by iATS.
Implemented Features | Sale Credit |
Authentication and security credentials | User ID Password |
iATS Netgate Payments services were integrated by HostedPCI since 2022, we support the following credit card processing features provided by iATS.
Implemented Features | Sale Credit Gateway Tokenize Automated Clearing House (ACH) |
Authentication and security credentials | Agent Code Password |
Ingenico services were integrated by HostedPCI since 2012, we support the following credit card processing features provided by Ingenico Payment Services.
Implemented Features | Auth Sale (Auth + Capture) Capture Void Credit |
Authentication and security credentials | User ID Password PSP ID |
iPay services were integrated by HostedPCI since 2011, we support the following credit card processing features provided by iPay.
Implemented Features | Auth Sale (Auth + Capture) Capture Void Credit |
Authentication and security credentials | Username Password Terminal ID |
JetPay Pay services were integrated by HostedPCI in 2022, we support the following credit card processing features.
Implemented Features | Auth Sale (Auth + Capture) Capture Void Credit 3DS 2 Passthrough Gateway Tokenize |
Authentication and security credentials | Terminal ID APP Version APP name Developer ID |
Klik & Pay services were integrated by HostedPCI in 2017, we support the following credit card processing features.
Implemented Features | Auth Sale (Auth + Capture) Capture Void Credit |
Authentication and security credentials | Account ID Private Key |
Merchant eSolution Pay services were integrated by HostedPCI in 2022, we support the following credit card processing features.
URL: www.merchante.com/
Implemented Features | Auth Sale (Auth + Capture) Capture Void Credit Gateway Tokenize |
Authentication and security credentials | Profile ID Profile Key |
Moneris services were integrated by HostedPCI since 2012, we support the following credit card processing features by Moneris.
Implemented Features | Auth Sale (Auth + Capture) Capture Void Credit Gateway Tokenization Credentials on File |
Authentication and security credentials | Store ID API token |
Mundipagg services were integrated by HostedPCI in 2015, we support the following credit card processing features by Mundipagg.
Implemented Features | Auth Sale (Auth + Capture) Capture Void Credit |
Authentication and security credentials | Merchant Key |
Supported Parameters | pxyCustomerInfo.gender (Customer’s Gender)
pxyCustomerInfo.officialDocNumber (Official Document Number) pxyOrder.itemId (Order Item ID) pxyOrder.unitCostInCents, pxyOrder.totalCostInCents (Unit Price in Cents, Total Cost in Cents) |
NetBilling services were integrated by HostedPCI since 2015, we support the following credit card processing features provided by NetBillings.
Implemented Features | Auth Sale (Auth + Capture) Capture Void Credit |
Authentication and security credentials | Affiliate ID (password) Site ID |
Network Merchants (NMI) services were integrated by HostedPCI since 2012, we support the following credit card processing features by Network Merchants.
URL: https://www.nmi.com/
Implemented Features | Auth Sale (Auth + Capture) Capture Void Credit Gateway Tokenization Soft Descriptors |
Authentication and security credentials | Username Password |
NPC Skipjack services were integrated by HostedPCI since 2014, we support the following credit card processing features provided by NPC Skipjack.
Implemented Features | Auth Capture Void Credit |
Authentication and security credentials | Serial Number Developer Serial Number |
Optimal Payments services were integrated by HostedPCI since 2013, we support the following credit card processing features provided by Optimal Payments.
Implemented Features | Auth Sale (Auth + Capture) Capture Void Credit |
Authentication and security credentials | Store ID Store Password Merchant Account Number |
PagSeguro services were integrated by HostedPCI since 2024, we support the following credit card processing features provided by PagSeguro.
Implemented Features | Sale (Auth + Capture) Capture Credit |
Authentication and security credentials | Store ID API Key |
Paya Connect services were integrated by HostedPCI since 2020, we support the following credit card processing features provided by Paya Connect
URL: https://paya.com/
Implemented Features | Auth Sale (Auth + Capture) Capture Void Credit Gateway Tokenization |
Authentication and security credentials | UserID User API key Location ID |
Payfabric services were integrated by HostedPCI since 2023, we support the following credit card processing features provided by Payfabric.
Implemented Features | Auth Sale (Auth + Capture) Capture Void Credit 3DS 2 Passthrough |
Authentication and security credentials | Username Password Vendor Name Partner Name |
Paygasus services were integrated by HostedPCI since 2024, we support the following credit card processing features provided by Paygasus.
URL: www.paygasus.com
Implemented Features | Auth Sale (Auth + Capture) Capture Void Credit Gateway Tokenization Card On File |
Authentication and security credentials | securityKey |
Payroc services were integrated by HostedPCI since 2021, we support the following credit card processing features provided by Payroc.
URL: www.payroc.com/
Implemented Features | Auth Sale (Auth + Capture) Capture Void Credit Gateway Tokenization |
Authentication and security credentials | API UID API Key API Terminal ID |
Pay Trace services were integrated by HostedPCI since 2020, we support the following credit card processing features provided by Pay Trace.
Implemented Features | Auth Sale (Auth + Capture) Capture Void Credit Gateway Tokenization |
Authentication and security credentials | Username Password Integrator ID |
PayFlow Pro services were integrated by HostedPCI since 2009, we support the following credit card processing features by PayFlow Pro.
Implemented Features | Auth Sale (Auth + Capture) Capture Void Credit |
Authentication and security credentials | PayPal username PayPal password Vender name Partner name |
Paypal Rest services were integrated by HostedPCI since 2023, we support the following credit card processing features by Paypal Rest
Implemented Features | Auth Sale (Auth + Capture) Capture Void Credit Gateway Tokenize |
Authentication and security credentials | Client ID Client Secret |
Paypal Website Payment Pro was integrated by HostedPCI since 2013, we support the following credit card processing features provided by Website Payment Pro.
Implemented Features | Auth Sale (Auth + Capture) Capture Void Credit |
Authentication and security credentials | API username API password Signature |
PayU services were integrated by HostedPCI since 2016, we support the following credit card processing features provided by PayU.
URL: https://corporate.payu.com/
Implemented Features | Auth Sale (Auth + Capture) Capture Void Credit |
Authentication and security credentials | API Login API Key Merchant ID Account ID |
Supported Parameters | pxyTransaction.txnFingerPrintData (Device Session ID)
pxyTransaction.txnInstallmentCount (The number of installments) pxyCustomerInfo.sessionId (Transaction Cookie) |
Prism Pay services were integrated by HostedPCI since 2011, we support the following credit card processing features by Prism Pay.
Implemented Features | Auth Sale (Auth + Capture) Capture Void Credit |
Authentication and security credentials | Account ID Merchant PIN Sub Account ID |
ProPay services were integrated by HostedPCI since 2015, we support the following credit card processing features by ProPay.
Implemented Features | Auth Sale (Auth + Capture) Capture Void Credit |
Authentication and security credentials | Account Number Certification String |
PSI Gate services were integrated by HostedPCI since 2011, we support the following credit card processing features by PSI Gate.
Implemented Features | Auth Sale (Auth + Capture) Capture Void Credit Credentials on File |
Authentication and security credentials | Store ID Passphrase Custom Merchant Ref. |
QuickBooks services were integrated by HostedPCI in 2021, we support the following credit card processing features provided by QuickBooks.
Implemented Features | Auth Sale (Auth + Capture) Capture Void Credit Gateway Tokenization |
Authentication and security credentials | UserName Password Refresh Token |
Rakuten services were integrated by HostedPCI since 2019, we support the following credit card processing features provided by Rakuten.
Implemented Features | Auth Sale (Auth + Capture) Capture Void Credit |
Authentication and security credentials | wp_id wp_password Service ID Service access Key |
Rapyd services were integrated by HostedPCI since 2022, we support the following credit card processing features provided by Rapyd.
URL: www.rapyd.net/
Implemented Features | Auth Sale (Auth + Capture) Capture Void Credit 3DS 2 Passthrough Card On FIle Gateway Tokenize |
Authentication and security credentials | Access Key Secret Key Pay Method Type |
Redecard services were integrated by HostedPCI since 2015, we support the following credit card processing features provided by Redecard.
Implemented Features | Auth Sale (Auth + Capture) Capture Void Credit |
Authentication and security credentials | Filiacao |
Redecard services were integrated by HostedPCI since 2015, we support the following credit card processing features provided by Redecard.
Implemented Features | Auth Sale (Auth + Capture) Capture Void Credit |
Authentication and security credentials | Username Password |
Redsys services were integrated by HostedPCI since 2015, we support the following credit card processing features provided by Redsys.
Implemented Features | Auth Sale (Auth + Capture) Capture Void Credit |
Authentication and security credentials | Username PasswordS Terminal |
Redsys Rest services were integrated by HostedPCI since 2023, we support the following credit card processing features provided by Redsys.
Implemented Features | Auth Sale (Auth + Capture) Capture Void Credit Credentials on File 3DS 2 Full Integration |
Authentication and security credentials | Username PasswordS Terminal |
SafeCharge services were integrated by HostedPCI since 2018, we support the following credit card processing features provided by SafeCharge.
Implemented Features | Auth Sale (Auth + Capture) Capture Void Credit Gateway Tokenization 3DS 2 Passthrough Soft Descriptors |
Authentication and security credentials | Merchant ID Merchant Key Merchant Site ID |
Supported Parameters | pxyTransaction.merchantPhoneNum (Display phone number on the clients statement)
pxyCustomerInfo.browserUserAgentHeader (The customers browsers header) |
Sage Payment services were integrated by HostedPCI since 2017, we support the following credit card processing features by Sage Payments.
Implemented Features | Auth Sale (Auth + Capture) Capture Void Credit Gateway Tokenization |
Authentication and security credentials | MerchantID/UserName Merchant Key/Password |
Sage Payment PI services were integrated by HostedPCI since 2017, we support the following credit card processing features by Sage Payments.
URL: https://developer.sage.com/api/payments/integration-services/own-form-integration/
Implemented Features | Auth Sale (Auth + Capture) Capture Void Credit Gateway Tokenization 3DS Full Integration |
Authentication and security credentials | Merchant ID/Username Merchant Key/Password Vendor Name |
Skrill Payment services were integrated by HostedPCI since 2021, we support the following credit card processing features by Skrill Data Payment.
Implemented Features | Auth Sale (Auth + Capture) Capture Void Credit |
Authentication and security credentials | Client ID Client Secret Merchant ID |
Skrill Payment services were integrated by HostedPCI since 2023, we support the following credit card processing features by Slimcd Payment Gateway.
URL: https://slimcd.com
Implemented Features | Auth Sale (Auth + Capture) Capture Void Credit Gateway Tokenize |
Authentication and security credentials | Username Client ID |
Stripe services were integrated by HostedPCI since 2013, we support the following credit card processing features by Stripe.
Implemented Features | Auth Sale (Auth + Capture) Capture Void Credit Gateway Tokenization 3DS Full Integration Soft Descriptors |
Authentication and security credentials | Secret Key |
StarCard services were integrated by HostedPCI since 2019, we support the following credit card processing features by Stripe.
Implemented Features | Auth Sale (Auth + Capture) Capture Void Credit |
Authentication and security credentials | Username/Facility Number |
TransFirst services were integrated by HostedPCI since 2014, we support the following credit card processing features by TransFirst.
URL: http://www.tsys.com/solutions/products-services/merchant/products/payment-gateway/
Implemented Features | Auth Sale (Auth + Capture) Capture Void Credit |
Authentication and security credentials | TransFirst Express RegKey Express Gateway ID Merchant Account ID |
TrustCommerce services were integrated by HostedPCI since 2019, we support the following credit card processing features provided by TrustCommerce.
Implemented Features | Auth Sale (Auth + Capture) Capture Void Credit Gateway Tokenization |
Authentication and security credentials | Customer ID Password |
Trust Payment services were integrated by HostedPCI since 2021, we support the following credit card processing features provided by Trust Payment.
Implemented Features | Auth Sale (Auth + Capture) Capture Void Credit Gateway Tokenization |
Authentication and security credentials | Username Password Site Reference |
USAePay services were integrated by HostedPCI since 2017, we support the following credit card processing features by USAePay.
Implemented Features | Auth Sale (Auth + Capture) Capture Void Credit Gateway Tokenization |
Authentication and security credentials | Source Key Pin |
Vantiv services were integrated by HostedPCI since 2017, we support the following credit card processing features by Vantiv.
Implemented Features | Auth Sale (Auth + Capture) Capture Void Credit Gateway Tokenization Omni Token Soft Descriptors |
Authentication and security credentials | Account ID Account Token Accepter ID Terminal ID Application ID |
Vantiv Litle services were integrated by HostedPCI since 2017, we support the following credit card processing features by Vantiv Litle.
Implemented Features | Auth Sale (Auth + Capture) Capture Void Credit Gateway Tokenization |
Authentication and security credentials | Username Password Merchant ID |
Supported Parameters | pxyTransaction.txnExtraParam1 (Additional parameter)
pxyTransaction.processorRefId (Required for refunds and voids only) pxyThreeDSecAuth.paRes (Used for making 3DS checks) pxyThreeDSecAuth.authTxnId (Required for using 3DS) pxyCustomerInfo.profileGatewayId (Gateway ID) |
Vantiv Raft services have integrated by HostedPCI, we support the following credit card processing features by Vantiv Raft.
Implemented Features | Auth Sale (Auth + Capture) Capture Credit Gateway Tokenization |
Authentication and security credentials | License Merchant ID |
VitalPay were integrated by HostedPCI, we support the following credit card processing features provided by VitalPay..
URL: https://vitalpay.us/
Implemented Features | Auth Sale (Auth + Capture) Capture Void Credit |
Authentication and security credentials | Username Password Merchant ID |
VariPay were integrated by HostedPCI since 2020, we support the following credit card processing features provided by VariPay.
URL: https://varipay.com/
Implemented Features | Auth Sale (Auth + Capture) Capture Void Credit |
Authentication and security credentials | Username Password MerchantID |
Versapay services were integrated by HostedPCI since 2022, we support the following credit card processing features provided by Versapay.
URL: www.versapay.com/
Implemented Features | Auth Sale (Auth + Capture) Capture Void Credit Gateway Tokenize |
Authentication and security credentials | API Username API Password |
VIP Pass services have been integrated with HostedPCI since 2023, we support the following credit card processing features provided by VIP pass.
URL: www.vippass.com
Implemented Features | Sale (Auth + Capture) Capture |
Authentication and security credentials | API ID API Key |
Wire Cardservices were integrated by HostedPCI since 2014, we support the following credit card processing features provided by WireCard.
Implemented Features | Auth Sale (Auth + Capture) Capture Void Credit 3DS 2 Passthrough Soft Descriptors |
Authentication and security credentials | Username Password Merchant Account ID |
World Pay services were integrated by HostedPCI since 2012, we support the following credit card processing features by World Pay.
Implemented Features | Auth Sale (Auth + Capture) Capture Void Credit Send XML Gateway Tokenize Credentials on File 3DS 2 Full Integration Idempotency Key |
Authentication and security credentials | Username Password |
Supported Parameters | pxyCustomerInfo.sessionId (World Pay Session ID) |
SecureNet services were integrated by HostedPCI since 2011, we support the following credit card processing features by SecureNet.
Implemented Features | Auth Sale (Auth + Capture) Capture Void Credit Soft Descriptors |
Authentication and security credentials | Secure ID Secure Key |
Supported Parameters | pxyOrder.invoiceNumber (Invoice Number) |
Common error codes
ERROR CODE | DESCRIPTION |
---|---|
PPA_ACT_1 | User not logged-in, please check the user name and passkey are valid |
PPA_ACT_2 | Invalid version, please use the correct version |
PPA_ACT_3 | Too many mapping failures, contact HPCI admin |
PPA_ACT_4 | SSL Required for the request, please https to submit the request |
PPA_ACT_5 | Credit card mapping failure, please make sure only mapped credit card numbers are used for the request |
PPA_ACT_6 | Payment gateway not configured for the currency, please contact HPCI to setup the correct gateway details |
PPA_ACT_7 | Credit card operation failed, please check the gateway specific return codes |
PPA_ACT_8 | Invalid amount, please check the amount sent |
PPA_ACT_9 | Dependent credit card operation not found, please provide the correct reference number for the dependent transaction |
PPA_ACT_10 | Unknown error, please contact HPCI |
PPA_ACT_11 | Invalid operation, please verify the request |
PPA_ACT_12 | Required parameter missing, please make sure missing parameter is provided |
PPA_ACT_13 | CVV mapping failed, please verify the request |
PPA_ACT_14 | Invalid expiry, please verify credit card expiry |
PPA_ACT_15 | Credit card payment failed |
PPA_ACT_16 | Used a duplicate transaction for the same reference number |
PPA_ACT_17 | Credit card payment declined |
PPA_ACT_18 | CC Token expired |
PPA_ACT_19 | CC Token Invalid |
PPA_ACT_20 | Not Found Token |
PPA_ACT_21 | ACH Token expired |
PPA_ACT_22 | ACH Token Invalid |
PGT_SER_1 | Unknown provider. |
PGT_SER_2 | Could not auth. |
PGT_SER_3 | Could not void |
PGT_SER_4 | Could not find |
PGT_SER_5 | Processing transaction |
PGT_SER_6 | Not implemented |
PGT_SER_7 | Capture not found. |
PGT_SER_8 | Points system not enabled |
PGT_SER_9 | Gateway parameter is missing. Please review the additional response fields for more details. |
PGT_SER_10 | Parameter not supported |
PGT_SER_11 | Result empty |
PGT_SER_12 | Could not initialize |
PGT_SER_13 | Invalid amount |
PGT_SER_14 | Unknown Auth transaction |
PGT_SER_15 | Unknown Sale transaction |
PGT_SER_16 | Unknown Void transaction |
PGT_SER_17 | Unknown Capture transaction |
PGT_SER_18 | Unknown Credit transaction |
PGT_SER_19 | Could not complete credit |
PGT_SER_20 | Call timeout |
PGT_SER_21 | Unknown lookup exception |
PGT_SER_22 | Preprocessor filter transaction rejected. Custom rule invoked. |
PGT_SER_23 | Could not tokenize |
PGT_SER_24 | Could not capture |
PGT_SER_25 | Processing mode not supported |
PGT_SER_26 | Unknown ACH Submit Exception |
PGT_SER_27 | Invalid Parameter |
PGT_SER_28 | Gateway Token creation failed |
PGT_SER_29 | Gateway Token not found |
MCC_1 | iFRAME error, Credit card not valid |
MCC_2 | IFRAME error, CVV not valid |
MCC_3 | Gateway Token profile name missing |
MCC_4 | Gateway Token profile currency missing |
MCC_5 | Gateway Token profile name amount missing |
MCC_6 | Gateway Token profile not found |
MCC_7 | Auth validation failed |
MCC_8 | Duplicate CC Token |
MCC_9 | Could not create Token |
MCC_10 | Exp month not valid |
MCC_11 | Exp year not valid |
MCC_12 | First Name not valid |
MCC_13 | Last Name not valid |
AMC_ACT_2 | This error is a packet replay error. This happens when a user has attempted to resubmit a form multiple times, it is usually through the use of back button. |
AMC_ACT_3 | CVV Invalid. |
AMC_ACT_4 | Three DS Info not found. |
AMC_ACT_5 | GooglePay Setup Error |
AMC_ACT_6 | Profile Setup Error |
AMC_ACT_7 | CC / ACH Mapping stopped |
URU_3 | This error means that the socked timeout, this can occur because there is a temporary issue with the payment gateway. |
TDS_SER_1 | Three DS Data Could not Verify |
TDS_SER_2 | Three DS Data not found |
TDS_SER_3 | Three DS Could not Verify Response |
TDS_SER_4 | Unknown Three DS provider |
Salesforce App Documentation
Installing the HostedPCI App
HostedPCI is now on the Salesforce AppExchange, where you can download our Salesforce iFrame as well as our IVR solution to accept your credit card information securely while still keeping everything organized within Salesforce.
The HostedPCI App can be installed from the Salesforce AppExchange. Login in to your Salesforce account a proceed to the AppExchange, once there search for HostedPCI and select “Get it Now”. When installing the HostedPCI App please ensure it is being installed in production and not in the sandbox.
Configuring the HostedPCI Salesforce App
Once the HostedPCI App is installed you can begin configuring the number of users you would like to have access to the App. There are 3 main options for configuring your users, You can either configure one specific user or for all users, you can also select to Admin users only. The next step in the configuration process is ensuring to select SSL encrypted as well as grant access to these third-party websites.
Once that is done, login into your Salesforce account to finish the configuration, proceed to “Set Up” under your account name. Then go to the Administration panel on the left-hand side, scroll down and select develop, and within develop menu select “Sites”. Once there select “Labels”, go to “Public Access Settings”, scroll down, and under “Enabled Visualforce Page Access” section click on “Edit”. Select “ThreeDSecPin”, “HostedPCICheckoutMsg” from the left list, click “Add” > “Save”. To complete the configuration process click “Edit” under profile details, scroll down and under “Custom Object Permissions”, enable “Read, Create, Delete, Edit” for Payments and Tokens object. Click “Save”.
Manual Installation
Payment Terminal
Payment Terminal Tab is a HomeTab for HostedPCIApp.
- Salesforce requests a new iframe from HostedPCI.
- HostedPCI verifies the website and webpage are correct.
- HostedPCI sends the iframe to the Salesforce page.
- The user fills the payment form and clicks “Submit”.
- iFrame is being sent back to HostedPCI for the tokenization of the credit card.
- The token is delivered back to the form and populates all the required hidden fields (CC, CVV, and BIN numbers) in the form.
- Form submits payment requests with credit card token, CVV token, expiry date, and amount.
- HostedPCI submits payment requests with a real credit card, real CVV, expiry date, and amount.
- HostedPCI gets the payment response from the bank.
- HostedPCI sends the response along with other information back to the Salesforce site.
- Salesforce page can then collect the response with all the information and display it back to the user.
Token Tab
A user can see tokens stored in the database as well as related payments.
Payments
A user can see transaction history.
Call Center
- The customer calls into your call center
- Your customer service representative (CSR) will begin the process by gathering the customer’s order as well the additional information needed
- Once the customer is ready to enter their credit card information the CSR will then explain to the customer that they are going to make a 3-way call to a secure credit card processing system for them to enter their card number in.
- At this time the CSR will create a new session on the HostedPCI to gather the session key needed to begin the IVR call.
- Once the IVR call is made and the session key is inserted the CSR will insert the customer into the 3-way call
- The customer will be prompted to enter their card information by the IVR, the difference with our system is that the customer is never separated from the CSR.
- When the customer is finished entering their card information the CSR will end the 3-way call with the IVR and continue with the rest of the call.
- Once the session is finished a token will pop up on the CSR’s screen which can then be used to finish the transaction.
HostedPCI Settings
Used for HostedPCI App configurations.
Prerequisites
Installation
- Download and unzip Salesforce.com.zip file .
- Open build.properties file in path_to_unzipped_file/deploy.
- Enter your login credentials for Salesforce.com.If your password is XXX and security Token is 123 then sf.password = XXX123
sf.username = your_username sf.password = your_password
Windows
- Open Command Prompt.
cd path_to_unzipped_file cd deploy ant
Macs
- Open Terminal
$cd path_to_unzipped_file $cd ./deploy $ant
- Login in to your Salesforce Org.
Go to “Setup”. - In the “Administration” panel on the left go to “Manage Users” > “Permission Sets”.
In the “Permission Sets” list on the right click “HostedPCI Developer”. - On the right-click “Manage Assignments”.
- On the right choose a user(s) you want to assign the app to. A user must have the permission of using apps.
- Click “Add Assignments”.
- Click “Done”.
- In the app menu on the top right click “HostedPCI”.
Public Website
Prerequisites
In order to use public web site , the “Sites” feature has to be enabled in your Salesforce Org.
Installation
- Login in to your Salesforce Org.
Go to “Setup”. - In the “Administration” panel on the left go to “Develop” > “Sites”.
- On the right-click “New”.
- Enter site details, for the “Active Site Home Page” select “HostedPCICheckout” page.
- Go to “Sites”. Click on the “Site Label”.
- Click on “Public Access Settings”. Scroll down, under the “Enabled Visualforce Page Access” section click on “Edit”. Select “ThreeDSecPin”,”HostedPCICheckoutMsg” from the left list, click “Add” > “Save”.
- Click “Edit” under profile details, scroll down and under “Custom Object Permissions”, enable “Read, Create, Delete, Edit” for Payments and Tokens object.
- Click “Save”.