Hosted Payment Page

This page describes how to incorporate Vesta’s Hosted Payment Page (HPP) into your application. HPP gives you a way to add secure payment features to your website while limiting your exposure to PCI regulations. The steps below describe how HPP integrates with your existing checkout process:

  1. When your customer completes shopping and is ready to check out, display a web form to collect any additional information that is required by the OrderCreate endpoint.

  2. When your customer is ready to pay, send a POST request to the OrderCreate endpoint of the HPP REST API with the customer details in the body of the request.

    The OrderCreate response includes a URL for the payment form.

  3. Display the URL from the response in an iFrame on your checkout page. Your customer enters payment details, and Vesta assesses the transaction for risk and submits the payment for processing.

    When Vesta finishes processing the transaction, Vesta POSTs the results to a webhook URL that you specify during setup.

  4. Display a page informing your customer of the results of the transaction and handle order fulfillment as normal.

This page includes the following information:

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

Prerequisites

Contact your Integration Specialist to set up a walkthrough of the Hosted Payment Page and to enable it for your account.

In order to use HPP in your application, you must ensure that the following items are in place before proceeding with the integration:

  • Enterprise Acquiring Account - HPP requires an enterprise acquiring account so that Vesta can submit transactions for processing on your behalf.
  • API Password - You must send your API password with every request that you make to the Vesta APIs. Obtain your API password by navigating to the Settings page of the Vesta Portal and selecting API Keys from the Developer Settings pane.

Integration

The sections below describe how to configure and add a hosted payment page to your application.

Configure the payment page

Follow the steps below to set the color scheme and logos for you payment page and receipts:

  1. Log into your vPortal account and select Settings from the left hand navigation. Then click on Checkout Settings in the Product Settings section to open the HPP configuration page:

    hpp-configure-checkout_settings

  2. Set your business name and email address as shown below:

    hpp-configure-checkout_settings

  3. Enter the domain that you intend to use for the Hosted Payment Page:

    hpp-configure-checkout_settings

    Vesta uses the HPP domain to generate the URLs you will use to display the HPP, which ensures that the payment page can only be presented on your domain.

  4. In the Customization section, shown below, define the appearance of the payment form for mobile and desktop screens and the receipt that Vesta generates for each transaction:

    hpp-configure-checkout_settings

    1. Upload your company’s logo. Your logo file must be a .png, .jpg, or .jpeg and cannot be larger than 1MB.

    2. Define your brand colors by typing Hex values into the text boxes, or by using the color picker that opens when you click on the color swatch.

      The sample form will update automatically to show your changes.

    3. Review the appearance of the payment form and the receipt email by clicking on the Mobile, Desktop, and Email buttons in the upper right of the Customization section.

  5. At the top of the Checkout Settings screen, click on WEBHOOK SETTINGS, to define your webhook URL and password, if applicable. The Webhooks tab will open, as shown below:

    hpp-configure-checkout_settings

  6. Enter the following information in the Webhooks section:

    • Order Status Webhook URL - This is the URL that Vesta will use to return transaction results.
    • Order Status Password - This field is optional. If your webhook requires a password, enter the password that Vesta should use when POSTing data.

Add the HPP to your application

The steps below describe how to implement the hosted payment page as part of your online store:

  1. When your customer is ready to checkout, collect any additional information required for the OrderCreate request.

  2. Send a POST request to the OrderCreate endpoint of the HPP REST API with the customer, shopping card, and reference details in the request body.

    Be sure to include the following fields in the OrderCreate request:

    • PartnerTransactionID - Your unique identifier for the transaction. Vesta uses the value that you set for the PartnerTransactionID to identify the transaction when returning the results.
    • EmailAddress - The customer’s email address. If you include an email address, Vesta uses the email address to send a receipt.

    The OrderCreate resource returns a success or error message to let you know whether the Payment Page can be displayed. If the resource returns a success response, the response includes a URL for the payment page.

  3. Display an iFrame on your checkout page that loads the payment page URL returned by the OrderCreate resource.

    NOTE: If for any reason, you cannot render the page in an iFrame, it is possible to redirect your customer’s browser to the payment page URL.

    Your customer enters payment details on the HPP and clicks a submit button.

    When your customer submits the payment details, Vesta analyzes the transaction and submits it for processing. In regions where it is mandated, or if your business requests additional identity verification, Vesta performs Secure Customer Authentication by sending the transaction to 3DSecure authentication. For the few transactions that require an identity challenge, the cardholder is asked to enter a one-time passcode.

    Vesta posts the transaction results to the webhook URL that you defined during setup.

  4. Capture the transaction results. The body of the post will include a TransactionID field that will be populated with the value that you set in the PartnerTransactionID field in the OrderCreate request body. The body will also include a PaymentStatus field that defines the status of the transaction.

    NOTE: If the post to your webhook fails for any reason, you can obtain the transaction results by sending a POST request to the OrderStatusGet endpoint of the HPP API with account information and the transaction ID in the body of the request.

  5. Display a page on your application that notifies your customer of the transaction status. Complete order fulfillment using your typical process.

Once the transaction is complete, the results will be available in vPortal for review and reporting purposes.