Onboarding

Setting up Payment Protect is simple. Use the Partner Portal to obtain security credentials, then add basic Javascript and API requests to your shopping and checkout pages.

Security

Vesta generates API credentials, which you must use to authenticate calls from your system to Vesta’s APIs. All data sent to Vesta must be encrypted using TLS 1.2 or greater, which ensures your organization’s security and your customer’s privacy. Vesta also offers a card number tokenization service, which can limit the scope of PCI requirements that you must follow by removing card numbers from your systems.

API Credentials

When you sign up for Payment Protect, Vesta generates your API credentials and gives you access to the Vesta customer portal. You will use your API credentials to authenticate all of your requests to the Payment Protect API. Log in to the customer portal and navigate to the Account Info page to obtain your API Credentials, as shown below:

vesta_creds

Tokenization

Payment Protect incorporates a tokenization solution, which can reduce your PCI compliance requirements by preventing primary account numbers (PANs) from being transmitted by your systems. Vesta requires tokenization of all PANs that are submitted to Vesta. Vesta offers temporary tokens for one-time authorization and permanent tokens, which you can use to authorize recurring transactions. Adding a JavaScript call to your checkout page is all it takes to implement Vesta’s tokenization solution. The scripts send card numbers directly to Vesta’s server, which returns a token that you can use to submit a request for a risk assessment.

Implementation

Add JavaScript and API calls to your website or app during development. Then, in the background while your customers shop, send information to Vesta for analysis. At checkout, request a risk assessment, pre or post-auth, using our REST API.

Overview

During development, add scripts to your landing pages, product pages, and checkout pages:

  • Landing and Product Pages - Add Behavioral Analytics JavaScript to all of your website’s pages. Vesta uses the scripts to keep track of each page that your customer visits while on your site, so that it can assess your customer’s behavior for indicators of fraud.
  • Checkout Page - Add Device Fingerprinting and Behavioral Analytics JavaScripts to your checkout page. The Device Fingerprinting script sends information about the customer’s device to Vesta, which is analyzed for fraud. The Behavioral Analytics script sends updated behavioral data to Vesta. Vesta generates and returns a risk assessment and payment guarantee based on the device and behavior data.

To use Payment Protect, send information to Vesta while your customer shops and during checkout. Vesta returns a risk assessment during checkout:

  • While your customer shops - Use the Payment Protect API to get a WebSessionID and OrgID as soon as a customer lands on your site. Pass the IDs from page to page as your customer shops by embedding them in the Behavioral Analytics scripts that you added during development.
  • At checkout - Add the IDs to the Device Fingerprinting and Behavioral Analytics scripts. When the scripts run, Vesta requests a Device Fingerprint and generates a risk assessment. You can request the risk assessment before or after you submit the transaction to the gateway.

Vesta provides sandbox and production environments for developing and deploying your website. The URLs are available in the Partner Portal.

Development

During development, follow the guidelines in the sections below to add Behavioral Analytics and Device Fingerprinting to your website. Complete specifications and sample code are available in the Vesta portal.

Behavioral Analytics

Vesta uses a session ID to track a customers’ shopping behavior to assess whether they are committing fraud. The steps below describe how to implement Behavioral Analytics. All of the required code is provided by Vesta:

  1. Add code to request a session ID that runs if the page is the first page that a new customer lands on. Send a POST request to the GetSessionTags endpoint to request a session ID. The resource returns a WebSessionID and an OrgID.
  2. Add code to your website that accepts the WebSessionID and OrgId as attributes, which Vesta uses to maintain a history of your customer’s behavior.
  3. Add code to your checkout page that requests a risk assessment by sending the WebSessionID and OrgID to Vesta’s servers for analysis.

Device Fingerprinting

Device Fingerprinting works in conjunction with Behavioral Analytics by identifying the device, originating IP address, and location of the device used by your customer to create a purchase. By combining Device Fingerprinting and Behavioral Analytics, Vesta can generate an accurate risk assessment that allows us to detect fraud and guarantee safe transactions.

The steps below describe how to implement Device Fingerprinting.

  1. Add Vesta’s Device Fingerprinting JavaScript to your checkout page.
  2. When a customer lands on your checkout page, embed the WebSessionID and OrgID in the script. Vesta will generate the device fingerprint.

Use

Payment Protect applies both Behavioral Analytics and Device Fingerprinting to assess risk. The sections below describe the typical API calls that your site will make as a customer shops and pays for purchases. With Payment Protect, you can request a risk assessment before or after you submit the payment for authorization:

  • Pre-Auth - Sending the transaction to Vesta before you submit the transaction to your gateway for authorization can save you processor fees by allowing you to decline the sale based on risk without ever sending it for approval. Use the ChargePaymentFraudRequest, AuthResult, and Disposition API operations to get a risk assessment before authorization, send the authorization response to Vesta, and update Vesta of the transaction’s final status.
  • Post-Auth - Sending the transaction for assessment after sending it to your gateway for authorization gives you the opportunity to cancel the transaction before settlement. Vesta can use your bank’s authorization decision to improve the accuracy of our risk assessment. Use the ChargePaymentFraudRequest and Disposition API operations to request risk assessment after obtaining authorization for the transaction and to update Vesta of the transaction’s final status.

Vesta requires the following information in the request bodies of the ChargePaymentFraudRequest operation:

  • Risk information XML - The risk information XML includes customer, account, shipping, and transaction-related information that Vesta uses to accurately assess a transaction’s risk.
  • API credentials - Your API user name and password, obtained from the Vesta portal.
  • Payment account information - The account holder’s name, address, and contact information, and any payment method-related data, like the CVV and expiration date.

Risk Information XML

To obtain the best results from Payment Protect, it is vital to include as much information as possible in the Risk Information XML.

The XML must include information about the purchaser (including payment account information), the sales channel, any current promotions applied to the sale, the date and time of the transaction, your order ID, billing and shipping information, shopping cart data, and any custom data that you track. The complete format of the Risk Assessment XML and an example are available in the Vesta portal. It is crucial that your company provide accurate information in the Risk Information XML with each transaction so that Vesta can accurately assess the fraud risk of the transaction.

The attributes listed above highlight important components of the ChargePaymentFraudRequest request bodies. The complete specifications are included in the Vesta Developer Documentation.

Pre-Auth

To request a risk assessment before sending a transaction for authorization you will use the following API operations:

  1. Charge Payment Fraud Request Operation - Send a POST request to the ChargePaymentFraudRequest endpoint with the Risk Information XML and the transaction details in the request body. Do not include the acquirer-related parameters in the body of ChargePaymentFraudRequest when requesting a pre-auth risk assessment.

    Vesta returns a risk assessment. At this point, you can choose whether or not to submit the transaction to your acquirer for authorization.

  2. Disposition - Optionally, send a POST request to the Disposition endpoint to notify Vesta of the final status of the transaction, including whether you submitted it for settlement or cancellation. If you choose to use the Disposition endpoint, be sure to set the value AutoDisposition parameter to 0 in the body of your initial request to the ChargePaymentFraudRequest endpoint.

Post-Auth

To request a risk assessment after submitting a transaction for authorization you will use the following API operations:

  1. Charge Payment Fraud Request - Send a POST request to the ChargePaymentFraudRequest endpoint with the Risk Information XML and the transaction details in the request body. Include the authorization status of the transaction and other details returned by your acquirer in the body of the request.

    Vesta returns a risk assessment. You can choose whether to submit the transaction for settlement or to cancel the transaction if needed.

  2. Disposition - Optionally, send a POST request to the Disposition endpoint to notify Vesta of the final status of the transaction, including whether you submitted it for settlement or cancellation. If you choose to use the Disposition endpoint, be sure to set the value AutoDisposition parameter to 0 in the body of your initial request to the ChargePaymentFraudRequest endpoint.