Quick Start Guide

Hosted Payment Page 2018-01-15T18:05:33+00:00

Hosted Payment Pages

HPPs are hosted on our site and allow you to process credit card or ACH transactions for you or your users without having to handle sensitive account data within your environment or implement more complex integrations.

Integration with our HPP solution is as simple as redirecting the user/customer to a URL on our system. If you are looking for a quick integration or are trying to limit your exposure scope to sensitive data HPPs may be the best integration option for you.

HPP Integration Overview

Transaction API vs. Hosted Payment Pages

We like to keep things simple.  Unlike many other gateways, Zift uses the same API calls for our HPPs as we do for a typical transaction API call. The first thing to do is become familiar with how the transaction API request works. Refer to Sale Transaction (Credit Card) for more information on how to use our API.

Once you understand how a basic transaction API request works all you have to do is add four parameters to the API request to trigger the HPP integration. Below is a comparison of a typical sale transaction API call compared to an HPP call.

Typical API Request HPP Request
requestType=sale
userName=api-user-1234
password=mypass1234
merchantAccountCode=21234
amount=500
accountType=R
accountNumber=4111111111111111
accountAccessory=0817
holderName=Lionel+Cosgrove
transactionIndustryType=RE
street=123+My+Street
city=My+City
state=UT
zipCode=87653
transactionCode=000000001
requestType=sale
userName=api-user-1234
password=mypass1234 < see Security Note
merchantAccountCode=21234
amount=500
accountType=R
accountNumber=4111111111111111  < see Security Note
accountAccessory=0817
holderName=Lionel+Cosgrove
transactionIndustryType=RE
street=123+My+Street
city=My+City
state=UT
zipCode=87653
transactionCode=000000001
notifyURL=http://yournotifyurl.com  < HPP fields
cancelURL=http://yourcancelurl.com
returnURL=http://yourreturnurl.com
styleURL=

In the above example you can see there are four parameters added to the original API request. These four parameters will control how the HPP behaves when a payment is processed.

Security Note – Passing Card and Account Data
Take care when redirecting users/customers or sending out links to HPP pages via methods such as email. In this example you can see the merchant credentials are present in the request which could be stored in someone’s inbox or otherwise viewed in the browser location line. When using our HPP pages it is highly recommended to use our ‘Authenticate’ call to generate a temporary password before sending users/customers to the HPP URL. See the tab to your right for details on how to generate temporary passwords.

Security Note – Temporary Passwords
In this HPP example the parameters accountNumber and accountAccessory have been removed from the transaction request. You should not pass payment method information into the HPP such as credit card number or expiration date. The parameters should be removed or have empty values when using HPPs. Passing sensitive payment data through these parameters may change your PCI scope.

Building Your Request

Parameter Description Values Example Value
HPP Operation
notifyURL Presence of this parameter triggers appearance of HPP. If definite URL is specified within the notifyURL field, the result of the transaction is delivered to this URL. URL must be preceded with http or https. ‘none’

‘full URL’

https://YourNotifyURL.com/
cancelURL This parameter controls the behavior of the cancel button.  If this value is ‘blank’ the button will not appear.  If a full URL is specified the button will appear and take the user to the specified URL when clicked. ‘blank’

‘full URL’

‘blank’
returnURL This parameter controls the behavior of the continue/return button on the results page.  If this value is ‘blank’ the button will not appear.   If a full URL is specified the button will appear and take the user to the specified URL when clicked. ‘blank’

‘full URL’

‘blank’
styleURL This parameter specifies the URL for the style sheet used in the HPP. If this value is ‘blank’ the default style will govern the display of the HPP. If a full URL is specified the specified CSS file will govern the display attributes of the HPP page. ‘blank’

‘full URL’

‘blank’
accountType This parameter controls the type of HPP is displayed Credit Card or ACH. Values R
https://secure.ziftpay.com/gates/xurl?&requestType=sale&userName=api-user-1234&password=mypass1234
&merchantAccountCode=21234&amount=500&accountType=R&accountNumber=&accountAccessory=
&holderName=Lionel+Cosgrove&transactionIndustryType=RE&street=123+My+Street&city=My+City&state=UT
&zipCode=87653&transactionCode=000000001&notifyURL=http://YourNotifyURL/com&cancelURL=
&returnURL=&styleURL=

HPP Display Example

Getting a transaction response

Since your user/customer is completing their transaction on the Zift site you will not receive a typical API response.   Instead you will use the notifyURL option as specified above.  When the transaction is complete the URL specified in notifyURL will be called by the Zift system.  The following information will be sent via method POST over HTTPS to your URL.

responseType=sale
approvalCode=018930
providerAvsResponseCode=Y
accountNumberMasked=4***********1111
avsResponseCode=4E
responseCode=A01
avsResultCode=4E
entryModeType=MX
cscResponseCode=
balance=
referenceNumber=9198951
cycleCode=2366331
entryMediumType=MC
holderVerificationModeType=
holderName=Lionel Cosgrove
amount=50
extendedAccountType=VD
warningCode=00
accountType=R
transactionCode=000000001
transactionDate=20160818
token=VD20000000000000053648
merchantAccountCode=21234
feeAmount=
providerReferenceNumber=26
originalAmount=50
accountAccessory=0817
providerCscResponseCode=
responseMessage=Approved+%28Success%29
currencyCode=USD
processorCode=018930
terminalMessage=
processorResponse=

Customizing Your HPP

Our HPP solution allows you to customize just about any aspect of your HPP page.   Most integrators will modify elements such as company logo and form layout.   In addition to customizing the appearance of your HPP you can also change the behavior of the form elements.  For example you can lock fields such as Amount so that passed in value cannot be changed by the user/customer.

Security Note – HPP Customizations
Due to the sensitive nature of the data passed through our HPP feature changes to Hosted Payment Pages are subject to review. As a result individual merchants or platforms cannot upload their own customizations into the Zift system. Merchants/Platforms can work with Zift Support to facilitate changes to their HPPs.