HPE Integration

This page describes how to incorporate the Hosted Payment Elements (HPE) iFrame into your web application. The steps below describe how to use HPE to submit card details to Vesta for tokenization, and handle the response:

Copy the HPE HTML from vPortal and add it to your payment page where you want to collect card data. The code below shows an example of the HPE HTML:
```
<iframe src="http://vesta-hosted-payment-elements/HPE-UI/?config=CONFIG-ID-HERE" style="position: relative; display: initial; id="hpeIframe" width="100%"></iframe>
```
The code that you copy will include the GUID of the iFrame where the code above shows “CONFIG-ID-HERE”. See the HPE Configuration page for details about obtaining the HTML.

Add an event listener to your page that will handle the JSON returned by HPE. The code below provides an example to get you started:

// Add Event Listener
useEffect(() => {
   window.addEventListener('message', handleMessage);
}, []);
   
const handleMessage = (e) => {
   if (validateMessage(e.data)) {
      // Action JSON Blob here, e.g. check Status of Elements etc.
   }
};
   
// Check Request Type of message, if it = 'VestaPaymentElements' return true and read JSON.
const validateMessage = (msg) => {
   if (!msg) {
      console.log('validation failed - no data');
      return false;
   }
   if (!msg.RequestType || msg.RequestType !== 'VestaPaymentElements') {
      //console.log('validation failed - no RequestType');
      return false;
   }
};
return true;

When your customer enters payment information in the HPE iFrame, HPE validates the values and posts messages to the listening frame. Configure the code above to check the Code field in the Status object of the JSON messages for each applicable data element, CardNumber, CardExpiryDate, and CardCVV. When the value of Code is 0, the payment field has been validated, and the token values, defined below, will be available in the CollectedData object:
- Token - The tokenized card number. You will send this value in the AccountNumber field of the Direct API request described in the next step.
- EncryptedData - The encrypted expiration date and CVV, if sent. You will send this value in the CipherText field of the Direct API request described in the next step.
The code below shows an example success response when HPE is configured to capture only the card number and create a permanent token:
```
{
   "RequestType": "VestaPaymentElements",
   "Status": {
      "Complete": true,
      "Code": "0",
      "Message": "Complete"
   },
   "CollectedData": {
      "Token": "4111900000000017",
      "First6": null,
      "Last4": null,
      "CardType": null
   },
   "CollectionElements": [{
         "Name": "CardNumber",
         "Status": {
            "Complete": true,
            "Code": 0,
            "Message": "Valid Card Number."
         },
         "Length": 16
      }
   ]
}
```

To get a risk assessment, capture the value of the Token and, if applicable, the EncryptedData fields and use your Direct API integration to submit a request to the appropriate resource for your subscription:

Payment Guarantee - Send a request using the ChargePaymentRequest endpoint.
Payment Protect - Send a request using the ChargePaymentFraudRequest endpoint.

Send the values defined below for temporary or permanent tokens:

Temporary Tokens - Send the value of the Token field in the AccountNumber field of the request. If you used HPE to collect the CVV and expiration date, send the value of the EncryptedData field in the CipherText field of the request, and leave the CVV and ExpirationMMYY fields empty. If you collected the CVV and expiration date separately, send the values in the CVV and ExpirationMMYY fields.
Permanent Tokens - You must collect the expiration date and CVV on your own. Send the Token value in the AccountNumber field and send the expiration date and CVV in the ExpirationMMYY and CVV fields.

The example below shows a request to the Payment Guarantee ChargePaymentRequest endpoint with values set for the AccountNumber, CipherText, CVV, and ExpirationMMYY, fields:

{
   "AccountHolderAddressLine1": "9666 Ignacio Prairie",
   "AccountHolderCity": "Gerardobury",
   "AccountHolderCountryCode": "US",
   "AccountHolderFirstName": "John",
   "AccountHolderLastName": "Doe",
   "AccountHolderPostalCode": "55742",
   "AccountHolderRegion": "Vermont",
   "RiskInformation": "<riskinformation><item productcode=\"MRC1\" description=\"Matchbox Race Car\"price=\"50.00\"quantity=\"1\"extendedprice=\"6.99\" isvirtualgood=\"false\" /></riskinformation>",
   "AccountHolderAddressLine2": "Suite 628",
   "AccountName": "<Replace with your API Account credentials>",
   "AccountNumber": "340001234527890",
   "AccountNumberIndicator": "1",
   "Amount": "34.85",
   "AutoDisposition": "0",
   "CVV": "105",
   "CipherText": "F22846F60482457F4F1...",
   "CreatedByUser": "John-Doe",
   "ExpirationMMYY": "1230",
   "MerchantRoutingID": "<Replace with your identification number associated with the merchant account.>",
   "NumberOfPayments": "2",
   "PartnerCustomerKey": "0GK2-CIQ5-ZA85-ZB14-2URR-GB1V-SIMJ",
   "Password": "<Replace with your API Account credentials>",
   "PaymentDescriptor": "ChargePaymentRequest",
   "PaymentSource": "WEB",
   "PlanType": "1",
   "RecurringArrangementID": "123XNQCKULS",
   "ReportingInformation": "<?xml version='1.0' encoding='UTF-8'?><PartnerReportingAttributes xmlns='http://www.vesta.io/ReportingAttributes'xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance' xsi:schemaLocation='http://www.vesta.io/ReportingAttributesReportingAttributes.xsd'><Parameter01>ReportingInformation</Parameter01></PartnerReportingAttributes>",
   "StoreCard": "0",
   "TransactionID": "SCQD-CGZT-BRVS-6KE2-VANB-Q9ZB-D5GJ",
   "WebSessionID": "P1TQ-DKZ2-0JNE-AIU4-6S12-J2V0-JXK3-KMA6I"
}

Handle the API response and complete the transaction as required by your subscription:
- Payment Protect - The API resource returns a risk score and fraud analysis for the transaction. Depending on Vesta’s assessment, reject the transaction or submit it to your processor for payment. See the Integration guide for Payment Protect for details about handling the fraud assessment, submitting the transaction for processing, and updating Vesta with the gateway’s response.
- Payment Guarantee - The API resource returns the payment status: successful, Vesta denied, or bank declined. See the Integration guide for Payment Guarantee for details of the payment response codes.

Example HPE Responses and Values

The information below defines the values for the Code field returned by HPE and shows example error and success responses.

Status Code Values

The value of the Code field in the response from HPE updates as your customer adds details to the form displayed in the HPE iFrame. The table below defines the values for the Code field:

Response Code	Message
0	Success
1	Error Occurred
519	In Progress
520	Ready
901	Session Expired (Vesta MT Session)

Card Capture Only Responses

The sections below provide examples of the responses returned by HPE when HPE is confirgure to capture a credit card number and generate a permanent token.

Initial State

HPE sends a response with the value of the Code field set to 520 when it is waiting for a customer to begin card entry:

{
   "RequestType": "VestaPaymentElements",
   "Status": {
      "Complete": false,
      "Code": 520,
      "Message": "Ready"
   },
   "CollectedData": {
      "Token": "",
      "First6": "",
      "Last4": ""
   },
   "CollectionElements": [{
         "Name": "CardNumber",
         "Status": {
            "Complete": false,
            "Code": 512,
            "Message": "Invalid Card Number - Card Number too short."
         },
         "Length": ""
      }
   ]
}

Card Number Too Short

When the customer begins entering a card number, HPE returns an object with the Code field in the Status object set to 519. Until the card number is the expected length, the CollectionElements object will include a message indicating that the card number is too short:

{
   "RequestType": "VestaPaymentElements",
   "Status": {
      "Complete": false,
      "Code": 519,
      "Message": "In Progress"
   },
   "CollectedData": {
      "Token": "",
      "First6": "",
      "Last4": "",
      "CardType": ""
   },
   "CollectionElements": [{
         "Name": "CardNumber",
         "Status": {
            "Complete": false,
            "Code": 512,
            "Message": "Invalid Card Number - Card Number too short."
         },
         "Length": 4
      }
   ]
}

Card Number Fails Mod-10 Check

If the card number fails the mod-10 check, HPE returns a response like the one shown below:

{
   "RequestType": "VestaPaymentElements",
   "Status": {
      "Complete": false,
      "Code": 519,
      "Message": "In Progress"
   },
   "CollectedData": {
      "Token": "",
      "First6": "",
      "Last4": "",
      "CardType": ""
   },
   "CollectionElements": [{
         "Name": "CardNumber",
         "Status": {
            "Complete": false,
            "Code": 511,
            "Message": "Invalid Card Number - Card Number Not Valid Mod 10."
         },
         "Length": 14
      }
   ]
}

Success

When the card number passes the length and mod-10 checks, HPE returns a success response, as shown below:

{
   "RequestType": "VestaPaymentElements",
   "Status": {
      "Complete": true,
      "Code": "0",
      "Message": "Complete"
   },
   "CollectedData": {
      "Token": "4111900000000017",
      "First6": null,
      "Last4": null,
      "CardType": null
   },
   "CollectionElements": [{
         "Name": "CardNumber",
         "Status": {
            "Complete": true,
            "Code": 0,
            "Message": "Valid Card Number."
         },
         "Length": 16
      }
   ]
}

Card Number, CVV, and Expiration Date Collection

The sections below provide examples of the responses returned by HPE when HPE is configured to capture the card number, cvv, and expiration date for use as a one-time payment.

Initial State

HPE sends a response with the value of the Code field set to 520 when it is waiting for a customer to begin card entry:

{
   "RequestType": "VestaPaymentElements",
   "Status": {
      "Complete": false,
      "Code": 520,
      "Message": "Ready"
   },
   "CollectedData": {
      "Token": "",
      "EncryptedData": "",
      "First6": "",
      "Last4": "",
      "ExpiryDate": ""
   },
   "CollectionElements": [{
         "Name": "CardNumber",
         "Status": {
            "Complete": false,
            "Code": 512,
            "Message": "Invalid Card Number - Card Number too short."
         },
         "Length": ""
      }, {
         "Name": "CardExpiryDate",
         "Status": {
            "Complete": false,
            "Code": 512,
            "Message": "Invalid Expiry Date - Expiry date too short."
         },
         "Length": ""
      }, {
         "Name": "CardCVV",
         "Status": {
            "Complete": false,
            "Code": 512,
            "Message": "Invalid CVV - CVV too short."
         },
         "Length": ""
      }
   ]
}

Card Number, CVV, or Expiration Date Too Short

When the customer begins entering data, HPE returns an object with the Code field in the Status object set to 519. Until the all the data is the expected length, the CollectionElements object will include one or more messages indicating the invalid data:

{
   "RequestType": "VestaPaymentElements",
   "Status": {
      "Complete": false,
      "Code": 519,
      "Message": "In Progress"
   },
   "CollectedData": {
      "Token": "",
      "EncryptedData": "",
      "First6": "",
      "Last4": "",
      "CardType": "",
      "ExpiryDate": ""
   },
   "CollectionElements": [{
         "Name": "CardNumber",
         "Status": {
            "Complete": true,
            "Code": 0,
            "Message": "Valid Card Number."
         },
         "Length": 16
      }, {
         "Name": "CardExpiryDate",
         "Status": {
            "Complete": true,
            "Code": 0,
            "Message": "Valid Expiry Date."
         },
         "Length": 4
      }, {
         "Name": "CardCVV",
         "Status": {
            "Complete": false,
            "Code": 512,
            "Message": "Invalid CVV - CVV too short."
         },
         "Length": 2
      }
   ]
}

Success

When all of the data elements pass the length check, HPE returns a success response, as shown below:

{
   "RequestType": "VestaPaymentElements",
   "Status": {
      "Complete": true,
      "Code": "0",
      "Message": "Complete"
   },
   "CollectedData": {
      "Token": "4111800000003062",
      "EncryptedData":
      "261157052579044F5A6FC6F19F3D8F84594C335EBB8399DB7752D8B53FA9EFB135F3ACFD5879
      7CD82E9604BEFAB78A6F1FC23D5E20FDB0C82C7FB2B6DBE15B37",
      "First6": "411111",
      "Last4": "1111",
      "CardType": "4",
      "ExpiryDate": "1223"
   },
   "CollectionElements": [{
         "Name": "CardNumber",
         "Status": {
            "Complete": true,
            "Code": 0,
            "Message": "Valid Card Number."
         },
         "Length": 16
      }, {
         "Name": "CardExpiryDate",
         "Status": {
            "Complete": true,
            "Code": 0,
            "Message": "Valid Expiry Date."
         },
         "Length": 4
      }, {
         "Name": "CardCVV",
         "Status": {
            "Complete": true,
            "Code": 0,
            "Message": "Valid CVV."
         },
         "Length": 3
      }
   ]
}