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 section describes the steps that you need to take to dynamically generate the security signature of the hosted iFrame.
Generate a URL
To load the hosted page, you will make a request to Zuora for the iFrame using security measures. You can see a sample iFrame code in the HTML code section at the bottom of the Preview Hosted Payment Method Page.
The iFrame URL from the preview page is valid for 30 minutes after it is generated. You must add logic to dynamically generate the timestamp/token when calling the hosted page.
The following are the required parameters for the iFrame URL:
The domain depends on which Zuora server you are using. For example:
See Zuora Data Centers for the URLs of domains.
ID (Page ID)
The ID (Page ID) is a unique identifier for each hosted page you can create. The ID can be retrieved from clicking Show Page Id next to the hosted page name in the Page List section.
To find your tenant ID, navigate to Settings > Administration Settings > Manage Tenant Profile. This page displays information about your tenant, including your Tenant Id.
Create a timestamp in UTC (GMT) format in milliseconds, for example,
The token is a random alphanumeric token of 32 characters that has not been used in the past 48 hours, for example, 7av18bEz97Jrq9K6z0QPyvJpIqIxSmZc. Every page submission consumes a token. Once a token have been consumed, it is blacklisted for 48 hours. When a Hosted Payment Page needs to be reloaded, for example, after an unsuccessful submission, a new token must be created to generate a new iFrame.
Retrieve the API Security Key
You will use the API security key to generate the signature. The API security key is the only parameter used in signature generation that is not transmitted in the public URL.You must include the Hosted Pages API security key with the signature.
To obtain the API security key:
- Navigate to Settings > Payments > Setup Hosted Pages.
- Click get api security key
- Copy the key from the pop-up dialog.
Generate a Signature
To generate the signature for the URL, create a string that concatenates the following input values:
- Tenant ID
- API security key
Use the following format for the string:
Do not add a space or other character between the token and the API security key.
For example, using the following values:
- Id: 4028e697325f8e970132603326446b33
- Tenant: 10514
- Timestamp: 1316846058955
- Token: 7av18bEz97Jrq9K6z0QPyvJpIqIxSmZc
- API security key: PEq1yiahIyFO6XxpyuCWyLoG4ym_HAklH2-FfAisLuk=
The resulting concatenated string would look like the following:
Encode the String
After you generate the signature for the URL, you must encode the resulting string.
To encode the URL signature:
- Encode the signature string in the UTF-8 format.
- Generate a hash using MD5 and convert it to Base16. PHP generates MD5 as Base16 by default, so this step is necessary for language such as Java and .NET which generate MD5 Base10 by default. A sample result after this step would be "
- Convert the string to Base64 in URL Safe Mode. Base 64 in URL Safe Mode refers a base 64 format that is safe to be used in URL, altering the available alphabet of the base 64 which replaces
_(respectively). The sample resulting output should be "
The result from the step 3 above is the signature to be used for the iFrame URL.
Refer to the demo projects sample code section for examples on how to do this encoding.
Next, Embed and Submit the iFrame.