Web App Direct API Integration Guide

This page provides all of the information you will need to integrate Payment Guarantee or Payment Protect with your eCommerce site using the Vesta Platform REST API.

We provide the following additional resources to support your Direct API integration:

Make sure you have all of the prerequisites in place, then follow the steps in the Integration section to add Vesta’s fraud detection to your site.

Prerequisites

Ensure that you have the following items before beginning development:

  • Authentication Credentials - Obtain your API user name and password during the Authentication step of the Certification process. You will use them to request API Keys.

  • Acquirer Documentation - You need access to your acquirer’s documentation so that you can submit transactions directly. Vesta requires information that is returned by your gateway when you submit the transaction for approval, and Vesta may ask you for details about your acquirer’s responses.

Integration

The information below describes how to use the Vesta Platform REST API to integrate Vesta’s fraud prevention into your web app.

The image below illustrates the one-step and two-step Direct API integration transaction flows:

Direct API App Flow

1. Add the Data Collector script to your master page

Add the following data collector script to the master page of your web app:

<script src="host/static/dcextension.js"></script>

It is important to add this <script> tag to your master page so that it is included on every page of your application. Vesta uses it to drive aspects of our transaction evaluation.

When you run your app, you will receive the message “Vesta Data Collector loaded” after the script is loaded.

Vesta’s Behavioral Data Collector improves our risk assessment and fraud detection services. This integration enhances the device and behavioral tracking information we obtain from your application.

2. Generate authentication credentials for your API requests

Every request to the Vesta Platform API requires a valid access token. The steps below describe how to use the /accessTokenand /refreshToken endpoints to obtain and manage the access tokens that you use to authenticate your requests:

Generate an initial access token

When your app first loads, you will need to generate an access token that you will use to authenticate subsequent requests to the API.

Click to expand step-by-step instructions for generating an access token.
  1. Send a request to the /accessToken endpoint with your apiKey in the body of the request. Your apiKey is constructed by concatenating your Account and secret values together separated by a colon character, :, and then encoding them in Base64.
    The steps below describe the process:
    1. Get your Account name and secret from the Vesta Console:
      • Account = “Sandbox”
      • Secret = “1234567890”
    2. Concatenate the values with a colon as a separator:
      • Sandbox:1234567890
    3. Encode the concatenated values using Base64:
      • U2FuZGJveDoxMjM0NTY3ODkw
    4. Use the value you generated for the apiKey in your request /accessToken:
      { “apiKey”:”U2FuZGJveDoxMjM0NTY3ODkw” }
      The API returns an access token and a refresh token.
  2. Use the access token in the authorization header of your requests to the API.

The access token has a lifespan of 30 minutes, during which you can use the access token to authenticate requests to the API. When the access token expires, you must use the refresh token to obtain a new access token as described in the Generate a new access token section below.

Generate a new access token from a refresh token

When your access token expires, use the /refreshToken endpoint to generate a new access token/refresh token pair.

Click to expand step-by-step instructions for generating a new access token from a refresh token.
  1. Send a request to the /refreshToken endpoint with the refresh token in the body of the request.
    The API returns a new access token and a new refresh token.
  2. Use the new access token to authenticate requests to the API and use the refresh token to generate a new access token if needed. You do not need to use the /refreshToken endpoint when your application first loads.

3. Activate the transaction and begin data collection

Call the following JavaScript function the first time a customer loads your application:

window.VestaJSDataCollector.activate

The function returns a transactionId, which you will use to track the customer’s actions while shopping and during checkout.

4. Capture transaction events

Every time a customer adds, updates, or removes items from a shopping card, send a POST request to the /transactions/{transactionID} endpoint with the shopping cart data in the body of the request:

{
  "ProductCode": "string",
  "ProductDescription": "string",
  "Quantity": 0,
  "Amount": {
    "amount": 0,
    "currencyCode": "string"
  },
  "EventType": "string",
  "Discount": {
    "amount": 0,
    "currencyCode": "string"
  },
  "GiftCard": true,
  "ProductType": "string",
  "UniqueCartId": "string"
}

See the /transactions/{transactionId} endpoint definition for details.

5. Evaluate the transaction

When your customer is ready to check out, obtain an evaluation of the transaction risk from Vesta.

The transaction evaluation steps depend on whether you use Payment Guarantee or Payment Protect and whether you want to use a one-step or two-step process.

Payment Guarantee

One-step: Click here to view step-by-step instructions for one-step transaction evaluation using Payment Guarantee.
  1. Submit the transaction to your payment gateway to obtain authorization from the bank. If the bank declines the transaction, you can choose to cancel the transaction and request a different payment method from your customer. If the bank approves the transaction, continue with step 2.

  2. Send a POST request to the /transactions/evaluate{transactionId} endpoint of the Vesta API. Be sure to set the value of transactionEvaluationStep to OneStepPostAuth.

    The response includes Vesta’s guarantee decision, Guaranteed or Not Guaranteed, and insights about the reason for the decision.

  3. Based on the response, submit the transaction to the bank for payment or cancel the transaction.
  4. Send Vesta the final transaction status.


Two-step: Click here to view step-by-step instructions for two-step transaction evaluation using Payment Guarantee.

  1. Send a POST request to the /transactions/evaluate/{transactionId} endpoint of the Vesta API. Set the value of transactionEvaluationStep to PreAuth.

    Vesta returns a preauth decision with one of the following values:

    • Guaranteeable - Vesta thinks the transaction is safe. Send the transaction to your bank for authorization.
    • Not Guaranteed - Vesta thinks the transaction is risky. You may choose to cancel the transaction to save the processing fees or continue by submitting the transaction to the bank for authorization. If you continue, you will have a chance to request an updated evaluation based on the bank’s response.
  2. Submit the transaction to the bank for authorization and capture the response.

  3. Send a POST request to the /transactions/evaluate/{transactionId} endpoint of the Vesta API with the bank’s authorization reponse in the body. Set transactionEvaluationStep to PostAuth.

    Vesta returns a postauth decision with one of the following values:

    • Guaranteed - The transaction is safe. Vesta will cover any costs associated with a chargeback.
    • Not Guaranteed - Vesta will not guarantee the transaction. If you decide to submit the transaction for payment, Vesta will not cover the costs associated with a chargeback. We recommend that you cancel the transaction with the bank.
  4. Based on the response, submit the transaction to the bank for payment or cancel the transaction.
  5. Send Vesta the final transaction status.

Payment Protect

One-step: Click here to view step-by-step instructions for one-step transaction evaluation using Payment Protect.
  1. Submit the transaction to your payment gateway to obtain authorization from the bank. If the bank declines the transaction, you can choose to cancel the transaction and request a different payment method from your customer. If the bank approves the transaction, continue with step 2.

  2. Send a POST request to the /transactions/evaluate/{transactionId} endpoint of the Vesta API. Be sure to set the value of transactionEvaluationStep to OneStepPostAuth.

    The response includes the following information:

    • Score - The risk score is a number from 0 to 100 that indicates how risky the transaction is. A higher number indicates a riskier transaction.
    • Insights - Insights give information about why Vesta assigned the risk score. For example, the customer’s phone number may not match the billing address phone number.
    • Risk Band - The risk band adds usable information to the risk score and has one of the following values: very safe, safe, moderate, risky, or very risky.
  3. Based on the response, submit the transaction to the bank for payment or cancel the transaction.
  4. Send Vesta the final transaction status.


Two-step: Click here to view step-by-step instructions for two-step transaction evaluation using Payment Protect.

  1. Send a POST request to the /transactions/evaluate/{transactionId} endpoint of the Vesta API. Set the value of transactionEvaluationStep to PreAuth.

    Vesta returns a preauth decision with one of the following values:

    • Score - The risk score is a number from 0 to 100 that indicates how risky the transaction is. A higher number indicates a riskier transaction.
    • Insights - Insights give information about why Vesta assigned the risk score. For example, the customer’s phone number may not match the billing address phone number.
    • Risk Band - The risk band adds usable information to the risk score and has one of the following values: very safe, safe, moderate, risky, or very risky. Based on Vesta’s response, you can decide whether to cancel the transaction or submit it to the gateway for authorization. If you continue, you will have a chance to request an updated evaluation based on the bank’s response.
  2. Submit the transaction to the bank for authorization and capture the response.

  3. Send a POST request to the /transactions/evaluate/{transactionId} endpoint of the Vesta API with the bank’s authorization response in the body. Set transactionEvaluationStep to PostAuth.

    Vesta returns a postauth decision with a updated score, insights, and risk band values.

  4. Based on the response, submit the transaction to the bank for payment or cancel the transaction.
  5. Send Vesta the final transaction status.

6. Send Vesta the transaction status

Use the /transactions/transactionStatus endpoint to send Vesta any final details about the transaction. Whether a transaction is risky and you decide to cancel the order, or the transaction is safe and you decide to accept it, Vesta uses the final transaction status to improve our recommendations for your future transaction.

Send a PATCH request to the transactions/transactionStatus endpoint with the Order Number, the transaction ID, an Oder Status value and Payment Status in the body of the request. The Order Status field accepts the following values: Cancelled, Fulfilled, Paid, or Partially Paid. The Payment Status field accepts the following values: Captured, Declined, Issuer Declined, or Voided.

If you receive an access denied response at any point during the steps above, use the Refresh Token operation to generate a new Access Token/Refresh Token pair.