HPP Integration

This page describes how to use the Hosted Payment Page REST API to incorporate HPP into your web 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 cart, 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.

    To redirect your customer to the payment page, send the following additional fields in the CreateOrder request:

    • IsIframe - An integer that notifies Vesta whether you will be redirecting your customer to the Payment Page URL:

      • 0 - You will redirect your customer to the payment page URL and display the HPP as an entire page.
      • 1 - You will display the HPP in an iFrame embedded in your checkout page. 1 is the default value for the IsIframe field.

    • RedirectURL - The URL of your payment confirmation page. Vesta will redirect your customer to this URL 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.

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

    Use the HPPMode field to enable multi-step payments. If multistep payments are enabled, the user can add or edit address information directly on the form. Any address information that you include in the OrderCreate request body will be pre-populated on the form. Set the HPPMode field to one of the following values to enable/disable billing/shipping address entry on the payment form:

    • "1" - Single Step - The user enters payment information.
    • "2" - Multi Step Digital Goods - The user enters payment information and can add or edit billing address information.
    • "3" - Multi Step Physical Goods - The user enters payment information and can add or edit billing and shipping address information. This feature will be available soon.

    To use the Deferred Payment Confirmations feature, set the value of the AutoDisposition field to 0 in the CreateOrder request. If you do not send the AutoDisposition field or if you set the value to 1, Vesta will automatically confirm the transaction.

    To specify a display language for the payment page, set a value for the LocaleCode field in the request body. LocaleCode accepts ISO 639-1 language codes as strings (e.g. "en-US" and "es"). The localization feature currently supports US English and Spanish languages. If you do not set a value for LocaleCode, the display language is set using your customer’s browser settings. If you send an invalid value, the display language will be set to the default value: US English.

    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.

    Your customer enters payment details on the HPP.

    If your customer updates billing or shipping information on the payment form, Vesta will request an updated tax amount from your application. Vesta sends a POST request to the Tax Retrieval Webhook URL that you defined in vPortal with the following fields in the body:

    • ShoppingCartID - The ShoppingCartID that you specified in the OrderCreate request.
    • Country - The two-character country code associated with the new address.
    • Region - The updated region or state name.
    • Password - The password that you entered when you set up the Tax Retrieval Webhook URL in vPortal.

    Your application should calculate and return the new tax amount or send an error message as shown in the examples below:

    • New Tax Amount - If the request is successful and the HTTP response type is 200 send the new tax amount in the response body as shown below:

      {
    "TaxAmount" : "10.57"
}

    • Error - If the request is unsuccessful, if there is an error calculating the tax, or if the HTTP response type is anything other than 200, send an error message in the response body as shown below:

      {
    "Message" : "Country Not Supported"
}

    The table below defines the allowed error messages:

    HTTP Error Code Error Message Description
    400 (Bad Request) Country Not Supported Country not valid or not supported in tax calculator.
    400 (Bad Request) Region Not Supported Region or State not valid or not supported.
    401 Unauthorized Access The Password is incorrect or missing.
    403 Forbidden The system making the request does not have permission to access the resource.
    404 (Not Found) Shopping Cart Not Found The provided Shopping Cart ID cannot be found.
    500 Internal Server Error The server is misconfigured.

    Vesta will use your response to update the payment form and transaction total, and your customer can proceed with entering payment information if needed.

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