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. Redirect your customer to the payment form URL or display the URL in an iFrame on your checkout page.

    Note: In order to offer Apple Pay as a payment option, you must redirect your customer to the URL. The Apple Pay option cannot be offered when you display the payment page in an iFrame.

    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, and, if needed, redirects your customer to a confirmation page that you specify.

  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.

    If you intend to redirect your customer to the Payment Page, you must also include the following fields in the OrderCreate request:

    • IsIframe - Notifies Vesta that you will be redirecting your customer to the Payment Page URL.
    • RedirectURL - The URL of the payment confirmation page that Vesta will use to redirect your customer after processing the payment. Vesta will also POST the TransactionID for the payment to this URL, which you can use to obtain the transaction results.

    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 the Payment Page using one of the following methods:

    • iFrame - Add an iFrame to your checkout page that loads the payment page URL returned by the OrderCreate resource.
    • Redirect - Redirect your customer’s browser to the URL returned by the OrderCreate resource. In order for your customers to be able to use Apple Pay, you must use a redirect to display the payment page.

    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. If you used a redirect to display the Payment Page, Vesta also posts the results to the RedirectURL that you specified in the OrderCreate request.

  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. Once transaction processing is complete, Vesta returns the customer to your site using one of the following methods:

    • iFrame - If you displayed the Payment Page using an iFrame, you can redirect your customer to a page on your application that notifies your customer of the transaction status.
    • Redirect - If you displayed the Payment Page using a redirect, Vesta redirects the customer to the RedirectURL that you specified in the OrderCreate request.

    Display a page the notifies your customer of the results of the transaction, that you obtained in step 4, and complete order fulfillment using your typical process.

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