Payment Guarantee (Enterprise Acquiring) Integration

This page describes how to incorporate Payment Guarantee (Enterprise Acquiring) 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 Enterprise Acquiring.
  • Integration - Follow the steps in the Integration section to add Enterprise Acquiring to your application.

Prerequisites

In order to implement Enterprise Acquiring 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 (Enterprise Acquiring) 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 guarantee and authorization from Vesta.
  • Behavioral Analytics - Implement the Behavioral Data Collector as described in the Developer Resources section of this site. Behavioral Data Collector sends user behavior data to Vesta, which Vesta analyzes for indications of fraud. You will need your Behavioral 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 (Enterprise Acquiring) API - Implement the Enterprise Acquiring 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 ChargePaymentRequest 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 application certification process.

Integration

The steps below describe how to incorporate Enterprise Acquiring into your application:

1. Request a Session ID

As soon as your app launches, send a POST request to the GetSessionTags endpoint of the Enterprise Acquiring 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 the Behavioral Data Collector

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

Mobile

During app initialization, call the Behavioral 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 Behavioral Data Collector user ID that was generated by Vesta during onboarding.

See the Behavioral Data Collector SDK documentation for your platform for details about initializing the Behavioral 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 iOS or Android. 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 and Capture a Payment Authorization

Enterprise Acquiring offers 1-step and 2-step transaction processing options:

  • 1-step - At checkout, Vesta generates a guarantee decision, and if the transaction is safe, Vesta immediately submits the transaction for authorization.
  • 2-step - At checkout, Vesta submits the transaction for pre-authorization. Vesta then incorporates the authorization response into the guarantee decision. Vesta returns the decision to you, and you can decide whether to submit the transaction for settlement.

The sections below describe how to implement the 1-step and 2-step options.

1-step

Send a POST request to the ChargePaymentRequest endpoint with the RiskInformation XML and the transaction details in the request body. Set the value of the autodisposition field to 1. See the ChargePaymentRequest resource definition for details.

Vesta returns the authorization results of the transaction, and if the transaction is approved, Vesta handles submitting the transaction for settlement.

2-step

Follow the steps below to submit a transaction for 2-step processing:

  1. Send a POST request to the ChargePaymentRequest endpoint with the RiskInformation XML and the transaction details in the request body. Set the value of the autodisposition field to 0. See the ChargePaymentRequest resource definition for details.

    Vesta returns a guarantee decision.

  2. Send a POST request to the Disposition endpoint. Based on Vesta’s risk decision, set the value of the DispositionType field to 1 if you want to submit the transaction for settlement, or 2 if you want to cancel the transaction. See the Disposition resource definition for details.

    Vesta will handle submitting the transaction for settlement or cancelling the transaction with the acquirer.

    NOTE: You must submit the Disposition request within 72 hours or Vesta will cancel the transaction in accordance with transaction processing regulations.

The status of the transaction will be available in vPortal as the transaction proceeds from authorization to settlement.