Skip to main content

Implement Payment Pages 2.0 via Direct POST

Zuora

Implement Payment Pages 2.0 via Direct POST

Alternative to embedding the Payment Pages iFrame on your website, you can create an HTML form version of a Payment Page that posts directly to Zuora to create a payment method. This implementation approach gives you full control over the look and feel of your payment form. With Direct POST, 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 that no payment data is stored on your servers
  • Securing your form from submission vulnerabilities such as cross-site scripting
  • Securing your form from redirection to a non-Zuora server upon submission

With PCI-DSS v3 and higher, you may be subject to stricter PCI-compliance audit requirements with this approach.

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

  • When your Payment Page is implemented via 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 Payment Pages implemented via iFrame. 
  • In Direct POST version of Payment Pages, you pass the passthrough parameters and gateway options into your HTML form as <input> elements. 

The following is an example of a pass-through 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"/>

The high-level steps for implementing a Direct POST to Payment Pages are:

  1. Configure Payment Pages 2.0
  2. Obtain the Public Key for Payment Pages 2.0
  3. Generate the Digital Signature for Payment Pages 2.0
  4. Validate the Digital Signature for Payment Pages 2.0
  5. Construct your HTML form for the Direct POST
  6. Verify the callback response

The steps are similar to the steps for implementing the iFrame version of Payment Pages. Only the Step #5 is specific to the Direct POST method. The following section provides more detail for this step.

Construct Your HTML Form for Direct POST

To build an HTML form for a Payment Page:

  1. Add <form> element for the Payment Page.
  2. Include the following attributes and a list of <input> elements to the Payment Page <form>.
    • name: Name of the Payment Page form
    • method: "POST"
    • action
      • API Sandbox:
        • "https://apisandbox.zuora.com/apps/PublicHostedPageLite.do"
        • "https://sandbox.na.zuora.com/apps/PublicHostedPageLite.do"
        • "https://sandbox.eu.zuora.com/apps/PublicHostedPageLite.do"
      • Production:
        • "https://www.zuora.com/apps/PublicHostedPageLite.do"
        • "https://na.zuora.com/apps/PublicHostedPageLite.do"
        • "https://eu.zuora.com/apps/PublicHostedPageLite.do"
  3. Use <input> elements to include Payment Page fields that you need to collect the payment information. The fields to be included should match the fields that were enabled in the Payment Page configuration in the Zuora application. See Direct POST Form Fields for Payment Pages 2.0 for the supported fields.

The following is an example HTML Form for Payment Pages 2.0 of the credit card payment type:

<form name="Payment2Form" action="https://apisandbox.zuora.com/apps/PublicHostedPageLite.do" 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="token" value="<[token]>"/> 
   <input type="hidden" name="signature" value="<[signature]>"/> 
   <input type="hidden" name="host" value="<[host domain]>"/> 
   <input type="hidden" name="field_key" value="<[public key]>"/> 
   <input type="hidden" name="encrypted_fields" value="#field_creditCardNumber#field_cardSecurityCode#field_creditCardExpirationMonth#field_creditCardExpirationYear"/>
   <input type="hidden" name="encrypted_values" value="<[encrypted values]>"/>
   <input type="hidden" name="field_style" value="iframe"/> 
   <input type="hidden" name="field_passthrough1" value="<[pass through value]>"/> 
   <input type="text" name="field_creditCardType" value="<[card type]>"/>
   <input type="text" name="field_creditCardHolderName" value="<[cardholder name]>"/>
   <input type="text" name="field_creditCardCountry" value="<[country]>"/>
   <input type="text" name="field_creditCardState" value="<[state]>"/>
   <input type="text" name="field_creditCardAddress1" value="<[address1]>"/>
   <input type="text" name="field_creditCardAddress2" value="<[address2]>"/>
   <input type="text" name="field_creditCardCity" value="<[city]>"/>
   <input type="text" name="field_creditCardPostalCode" value="<[postal code]>"/>
   <input type="text" name="field_phone" value="<[phone]>"/>
   <input type="text" name="field_email" value="<[email]>"/>
</form>

Best practices for Direct POST

Direct POST gives you more control over your end user experience. As such, you are responsible for implementing your own anti-fraud controls and preventing malicious use.

By default, all new Payment Pages require CAPTCHA. However, you need to disable CAPTCHA on any new Payment Pages created for use with Direct POST. Your page could experience unhandled errors if CAPTCHA is not disabled. 

For the existing Payment Pages implemented through Direct POST, it is recommended that you review your approach for managing malicious use and anti-fraud submission controls.

To better manage security settings for Payment Pages, we strongly recommend that you create a payment page using only iFrame or only Direct POST.