Skip to main content

Implement Hosted Payment Method Pages via Direct POST


Implement Hosted Payment Method Pages via Direct POST

This article is for the Hosted Payment Method Pages (HPM) 1.0. Zuora has deprecated HPM1.0. There are no further plans for HPM 1.0 and Zuora will no longer provide support for any issues with HPM 1.0. Payment Pages 2.0 are now generally available, and are a replacement for HPM 1.0. To migrate from HPM 1.0 to Payment Pages 2.0, see this migration guide.

This article describes how to implement Hosted Payment Method pages via Direct POST.

Alternative to embedding the Hosted Payment Method pages iFrame on your website, you can create your own HTML form on your website that posts directly to Zuora to create a payment method. This method allows you a full control over the look and feel of your payment form while reducing your PCI compliance scope since the sensitive payment data is transferred from the web browser directly to the Zuora server via HTTPS.

While PCI scope is reduced using the Direct POST, your merchant bank will require you to follow PCI compliance best practices when securely submitting your HTML form to Zuora, including:

  • Ensuring no payment data is being stored on your servers
  • Securing your form from submission vulnerabilities such as cross-site scripting
  • Securing your form from being redirected to a non-Zuora server upon submission

There are some differences to note between the features and implementations of the iFrame versus the POST:

  • When your Hosted Payment Method page is implemented via the Direct Post, your re-loaded form cannot contain the previously entered user inputs. You can use the retains value feature described in error handling only with the Hosted Payment Method pages implemented via iFrame. 
  • The Direct POST supports the passthrough parameters and gateway options features described in customizing Hosted Payment Method pages. The only difference is that instead of passing in the field names in the URL in the iFrame, you would pass the same field names into your HTML form as field elements.
    • The following is an example of a passthrough parameter in an HTML form:
      • <input type="hidden" name="field_passthrough1" value="Capture"/>
    • The following is an example of a gateway options parameter in an HTML form:
      • <input type="hidden" name="param_gwOptions_globalIPaddress" value="SomeAddress"/>

High-level Steps

Use the following steps to do a direct post to Hosted Payment Method pages:

  1. Configure your Hosted Payment Method pages in Zuora
  2. Generate a signature for the POST
  3. Construct your HTML form for the POST 
  4. Provide a callback page
  5. Verify the callback response

The steps above are similar to the steps to implement the Hosted Payment Method pages iFrame with the exception of step 3: constructing the HTML form for the POST. The following section provides more detail for this step.

Construct Your HTML Form for the POST

Design your user interface and construct the <form> element as follows. These fields displayed in snippet below are mandatory fields for the form submission. Please refer to Generate a signature for the POST to determine what values to input for the bold fields below:

<form action="" name="HostedPaymentMethodPageForm" method="post">

<input type="hidden" name="method" value="submitPage"/>
<input type="hidden" name="id" value="[page id]"/>
<input type="hidden" name="tenantId" value="[tenant id]"/>
<input type="hidden" name="timestamp" value="[current timestamp]"/>
<input type="hidden" name="token" value="[token]"/>
<input type="hidden" name="signature" value="[signature]"/>

...all other fields...


Go on to complete the form to include field elements that you need to collect the payment information. The fields to be included should match the fields that were enabled in the Hosted Payment Method pages configuration in the Zuora application. 

The name of the field should be in the format: field_[field name]. Refer to the Hosted Payment Method pages fields section on what field names can be used.

For example, adding credit card number and cardholder name as inputs in the form would look like the following: 

<input type="text" name="field_creditCardNumber" maxlength="16"/>
<input type="text" name="field_creditCardHolderName" size="40"/>
An example of a complete form could look something like this (depending on your payment gateway requirements):

<form action="" name="HostedPaymentMethodPageForm" method="post">
  <input type="hidden" name="method" value="submitPage"/>
  <input type="hidden" name="id" value="<[page Id]>"/>
  <input type="hidden" name="tenantId" value="<[tenantId]>"/>
  <input type="hidden" name="timestamp" value="<[current timestamp]>"/>
  <input type="hidden" name="token" value="<[token]>"/>
  <input type="hidden" name="signature" value="<[signature]>"/>
  <select name="field_creditCardType">
      <option value="">‐ Select Card Type ‐</option>
      <option value="AmericanExpress">AmericanExpress</option>
      <option value="Discover">Discover</option>
      <option value="MasterCard">MasterCard</option>
      <option value="Visa">Visa</option>
  <input type="text" name="field_creditCardNumber" maxlength="16" size="40"/>
  <input type="text" name="field_creditCardExpirationMonth" />
  <input type="text" name="field_creditCardExpirationYear" />
  <input type="text" name="field_creditCardHolderName" size="40"/>  
  <input type="Submit" value="Submit"/>

The fields marked as “required” in the Hosted Payment Method pages configuration will be validated by Zuora when it is being submitted. Be sure to include the fields as part of the form submission.

The fields that are required for payment gateways but not marked as "required" in the Hosted Payment Method page configuration will still be validated as required fields for payment method creation.