Onboarding

Setting up Payment Guarantee 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 Guarantee, 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 Guarantee 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 Guarantee 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 and guarantee from Vesta.

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 and request risk and guarantee results at checkout:

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 Guarantee, send information to Vesta while your customer shops and during checkout. Vesta returns a payment guarantee and risk assessment during checkout:

  • While your customer shops - Use the Payment Guarantee 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 and payment guarantee decision. You can request the risk assessment and payment guarantee 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 along with complete API specifications.

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 GET 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 score 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 Guarantee applies both Behavior 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 Guarantee, you can request a risk assessment and guarantee 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 ChargePaymentRequest, 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. 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 ChargePaymentRequest and ChargePaymentFraudRequest, which Vesta uses to generate a risk score and payment guarantee decision:

  • Risk information XML - The risk information XML includes customer, account, 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.
  • Shipping information - The shipping address associated with the order.

Risk Information XML

To obtain the best results from Payment Guarantee, 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 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 ChargePaymentRequest and ChargePaymentFraudRequest request bodies. The complete specifications are included in the API documentation in the Vesta Portal.

Pre-Auth

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

  1. Charge Payment Request Operation - Send a POST request to the ChargePaymentRequest endpoint with the RiskInformation XML and the transaction details in the request body. Vesta returns a risk assessment and a boolean indicating whether the payment will be guaranteed. At this point, you can choose whether or not to submit the transaction for authorization.
  2. AuthResult - Send a POST request to the AuthResult endpoint to update Vesta with the authorization status of the transaction. Vesta will return an updated risk assessment and payment guarantee decision based on the authorization status. You can choose whether to submit the transaction for settlement or to cancel the transaction.
  3. Disposition - 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.

Post-Auth

To request risk assessment and payment guarantee 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 RiskInformation XML and the transaction details in the request body. The request body of the ChargePaymentFraudRequest must also include the authorization status of the transaction returned by your gateway. Vesta returns a risk assessment and a boolean indicating whether the payment will be guaranteed. You can choose whether to submit the transaction for settlement or to cancel the transaction if needed.
  2. Disposition - 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.