Quick Start Guide

QuickStart – Integration 2018-01-15T18:05:34+00:00
> QuickStart > Transactions

Building a Basic Sale Transaction

Although there are many different calls you can make to our API our example below will focus on building a basic sale transaction request.  The concepts learned here will apply to most of our API requests.

Sale transactions run through the Zift system utilize a basic REST API.   The API is called via method POST over HTTPS and the request should contain the API Operation, Authentication Information, Merchant Context,  Payment Details and Customer Information. You may optionally include identification information from your system.

Where to send your request? – API Endpoints

When starting your integration it is recommended that you use our sandbox environment. Once you are satisfied with your integration you can connect to our production system. Below are the API endpoints for our sandbox and production.

  • Production: https://secure.ziftpay.com/gates/xurl?
  • Sandbox: https://sandbox-secure.ziftpay.com/gates/xurl?

NOTE:  Your credentials will be different for each environment.

Basic transaction components

While all of the above may seem like a lot of information the request is actually very simple. The table below explains how to build a basic sale request. Additional parameters and associated details can be found in our Full API Reference Manual.

Building Your Request

Column 1 Column 2 Column 3 Column 4
Item #1 Description
Specifies which merchant account to use for this transaction. Description Discount: $2.00
https://secure.ziftpay.com/gates/xurl?&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
Item #4 Description Discount: $4.00
All Items Description Your Total: $10.00
API Parameter Description Values Example Value
API Operation
requestType Specifies the type of operation to be performed.  In this example we are focusing on sale transaction operations. Values sale
https://secure.ziftpay.com/gates/xurl?&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
Authentication
username Username for your API user account. NOTE: This is not the same as your portal account.  String api-user-1234
password Password for your API user account.  String mypass1234
https://secure.ziftpay.com/gates/xurl?&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
Merchant Context
merchantAccountCode Specifies which merchant account to use for this transaction.  Your API user may be associated with more than one merchantAccountCode  String 21234
https://secure.ziftpay.com/gates/xurl?&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
Payment Details
amount Specifies the total amount of the transaction in cents (not dollars).  5 dollars  = 500 cents String 500
accountType Specifies the payment method to be used with this transaction Value R
accountNumber If accountType (above) is set to C this field contains the credit card number

If accountType is set to C or S this field contains the checking or savings account number.

 String 4111111111111111
accountAccessory If accountType(above) is set to C this field contains the credit card expiration date.  Month and year are represented by 4 digits.  Example August 2017 = 0817.

If accountType is set to C or S this field contains the routing number.

 String 0817
holderName Specifies the name of the card or account holder  String Lionel Cosgrove
transactionIndustryType Specifies the industry related to this transaction   Values RE
https://secure.ziftpay.com/gates/xurl?&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
Customer Information
street Street address of customer.  String 123 My Street
city City of customer  String My City
state State of customer  String UT
zip Zip Code of customer  String 87653
https://secure.ziftpay.com/gates/xurl?&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
External Identifiers
transactionCode External system identifier.  Stored on transaction record.  Returned in transaction response.  String 000000001
https://secure.ziftpay.com/gates/xurl?&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

 

Transaction Response

When you have submitted a transaction to the Zift Gateway you will get a response back indicating the status of the transaction.   Below is a list parameters sent back as part of the API response.

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=

Hosted Payment Pages

HPPs are hosted on our site and enable you to process credit card or ACH transactions for you or your merchants 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.

Where to send your request? – API Endpoints

When starting your integration it is recommended that you use our sandbox environment.  Once you are satified with your integration you can connect to our production systems.   Below are the API endpoints for our systems.

  • Production: https://secure.ziftpay.com/gates/xurl?
  • Sandbox: https://sandbox-secure.ziftpay.com/gates/xurl?

NOTE:  Your credentials will be different for each environment.

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.   Information on a basic sale transaction is one tab to your left.   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.    See below for a breakdown of the parameters.

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
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
notifyURL=http://yournotifyurl.com
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
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
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

API 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’

http://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. R = Credit Card
S = Savings Account
C = Checking Account
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 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
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 cannot upload their own customizations into the Zift system.  Merchants can work with Zift Support to facilitate changes to their HPPs.
Tab content
Tab content