Payment Guarantee Integration

This page describes how to incorporate Payment Guarantee into your application.

This page includes the following information:

  • Prerequisites - Make sure you have the items defined in the Prerequisites section in place before implementing Payment Guarantee.
  • Integration - Follow the steps in the Integration section to add Payment Guarantee to your application.

Prerequisites

In order to implement Payment Guarantee you must incorporate the following elements into your application:

  • Security - Set up encrypted data transmission and obtain your API credentials:
    • Encrypted Data Transmission - Your application must use TLS 1.2 or greater to protect information sent between your systems and Vesta.
    • API Credentials - Your API account name and password are available in vPortal. They are used to authenticate your requests to the Payment Guarantee API.
  • Tokenization - Add a JavaScript call to your checkout page to implement Vesta’s tokenization solution. If you are already PCI compliant, this is not necessary. The script sends a card number 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.
  • Behavioral Analytics - Implement Data Collector as described in the Developer Resources section of this site. Data Collector sends user behavior data to Vesta, which Vesta analyzes for indications of fraud. You will need your Data Collector user ID, which is provided by Vesta during onboarding.
  • Device Fingerprinting - Implement Device Fingerprinting in your mobile or web app to collect data about the device used to access your services.
  • Payment Guarantee API - Implement the Payment Guarantee REST API as described in the Vesta API documentation. API requests must come from your system’s back end and cannot be sent from your user’s browser.
    • Risk Information XML - Every request to the ChargePaymentFraudRequest endpoint must include the Risk Information XML that you use to send additional details about the transaction to Vesta. It is important to include as much information as possible in the Risk Info XML. Use the specifications on the Risk Information XML page to generate an appropriate XML file for your business.

Vesta provides sandbox and production environments for developing and deploying your application. Sandbox credentials are available in vPortal, and production credentials are supplied once your application has passed the certification process.

Integration

The steps below describe how to incorporate Payment Guarantee into your application:

1. Request a Session ID

As soon as your app launches, send a POST request to the GetSessionTags endpoint of the Payment Guarantee API.

Include the following information in the body of the request:

  • AccountName - Your API account name.
  • Password - Your API account password.
  • TransactionID - A unique identifier for this session. Generate this value on your system to track the session.

The resource will return webSessionID and OrgID values that you will use in later steps.

See the GetSessionTags resource definition for details.

2. Initialize Data Collector

When your application launches, initialize Data Collector by sending session details to Vesta. The specific steps depend on whether you are building a mobile or web app. See the Data Collector Integrations page for details.

Mobile

During app initialization, call the Data Collector start(); method.

The start(); method takes the following parameters:

  • Application - An instance of the current application.
  • webSessionID - The webSessionID value returned by the GetSessionTags resource in step 1.
  • LoginID - Your Data Collector user ID that was generated by Vesta during onboarding.

See the Data Collector SDK documentation for your platform for details about initializing Data Collector.

Web

Include the appropriate JavaScript on every page of your website. Embed your Behavioral Data Collector Account Name and the webSessionID returned by the GetSessionTags resource in the URL in the script. The sample code below shows where you must add the Account Name and ID values, but you must use the correct code for your region, which is available on the Behavioral Data Collector Web Integration page:

 <!-- Begin Sandbox Data Collector tags below -->
<script src="https://{regional-url}/DCCSProxy/Service/vdccs.js?AccountName=XXXX&WebSessionID=YYYY" async type=“text/javascript”></script>

3. Generate a Device Fingerprint

Generate a Device Fingerprint to send detailed information about the customer’s device to Vesta. The specific steps depend on whether you are building a mobile or web app.

Mobile

The Device Fingerprinting integration generates the device fingerprint automatically. See the Device Fingerprinting Integrations page for details. Proceed with the next step.

Web

Pass the webSessionID and OrgID values that you obtained from the GetSessionTags response in step 1 to the HTML that you added to your site when you implemented Device Fingerprinting. Then run the code.

The sample code below shows where you must add the ID values, but you must use the correct HTML for your region, which is available on the Device Fingerprinting - Web Integration page:

<!-- Begin fingerprinting tags below -->

<p style="background:url(https://{regional-url}/DF/fp/clear.png?org_id="{OrgID}"&session_id="{WebSessionID}"&m=1)"></p>

<img src="https://{regional-url}/DF/fp/clear.png?org_id="{OrgID}"&session_id={WebSessionID}"&m=2" alt=""/>

<script src="https://{regional-url}/DF/fp/check.js?org_id="{OrgID}"&session_id="{WebSessionID}" type="text/javascript"></script>

<!-- End fingerprinting tags -->

You must generate a Device Fingerprint before the user checks out. It can take up to five seconds to generate a Device Fingerprint; therefore, ensure that the script is the last piece of the checkout page to load, and disable the Submit button until the the page has loaded completely.

4. Request a Risk Assessment and Guarantee

The risk assessment returns a boolean indicating whether Vesta will guarantee the transaction. You can request a risk assessment before (pre-auth) or after (post-auth) submitting the transaction to your gateway for approval.

Pre-Auth

Complete this step before submitting the transaction to your gateway for authorization.

Send a POST request to the ChargePaymentRequest endpoint with the RiskInformation XML and the transaction details in the request body. See the ChargePaymentRequest resource definition for details.

Vesta returns a a boolean indicating whether the payment will be guaranteed.

At this point, you can choose whether or not to submit the transaction for authorization.

If you submit the transaction for authorization, continue with step 5. If not, skip to step 6.

Post-Auth

Complete this step after submitting the transaction to your gateway for authorization.

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 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.

See the ChargePaymentFraudReqeust resource definition for details. Proceed with step 6.

5. Send Vesta the Authorization Results (Pre-Auth Only)

Send a POST request to the AuthResult endpoint with the authorization results from your gateway in the body of the request.

Vesta will return an updated guarantee decision. You can then decide whether to submit the transaction for settlement.

6. Notify Vesta of Your Decision

Send a POST request to the Disposition endpoint to tell Vesta whether you decided to settle or cancel the transaction. Vesta will use information about your decision to continue to improve your risk assessment results.