Quick Start Guide

Merchant Creation 2018-01-15T18:05:32+00:00

Merchant Creation (provisioning)

Creating merchant payment accounts for the users of your SaaS or platform is as simple as using our hosted payment pages. In our documents we call this process ‘Provisioning’  or ‘Onboarding’.  Our provisioning API allows you to send new merchant application information for your users to Zift for immediate account setup.

As part of the provisioning process we will return the new ‘accountId’ via a callback API.  You will use the accountID in other API calls such as sale transaction.   Below is an overview of how to use our provisioning API.  You can also visit our full provisioning API reference.

Where To Send Your Provisioning API Requests – API Endpoints

When starting your integration we recommend 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://manage.ziftpay.com/gates/onboarding?
  • Sandbox: https://sandbox-manage.ziftpay.com/gates/onboarding?

Different API Endpoints
The API endpoints for the provisioning API are different from transaction processing API endpoints.
Your credentials will be different for each environment.

Provisioning Process Integration Overview

Integration

Before you begin integrating with the Zift provisioning API, please make sure you have the following information:

  • Username
  • Password
  • Profile Type
  • Reseller ID
  • Portfolio ID
  • Fee Template Code

Building Your Authentication Request

Below is the basic API call setup information.   Information on how to send  merchant specific data into the provisioning process can be found in our Full Provisioning API documentation.

Parameter Description Values Example Value
API Operation
requestType Specifies the type of operation to be performed. In this example we are focusing a new provisioning application. create create
https://sandbox-manage.ziftpay.com/gates/onboarding?requestType=create&userName=api-user-1234
&password=mypass1234&profileType={}&resellerId=25&merchantId=&portfolioId=522
&feeTemplateCode=500010&isEmbedded=1&pageFormat=OBDA&notifyURL=https://ziftpay.com/cbtest/notify.php
&cancelURL=&returnURL=https://myreturnrul.com/&returnURLPolicy=redirect
Authentication
username Username for your API user account. NOTE: This is not the same as your merchant portal account. String api-user-1234
password Password for your API user account. String mypass1234
https://sandbox-manage.ziftpay.com/gates/onboarding?requestType=create&userName=api-user-1234
&password=mypass1234&profileType={}&resellerId=25&merchantId=&portfolioId=522
&feeTemplateCode=500010&isEmbedded=1&pageFormat=OBDA&notifyURL=https://ziftpay.com/cbtest/notify.php
&cancelURL=&returnURL=https://myreturnrul.com/&returnURLPolicy=redirect
Provisioning Setup
profileType Zift Processing Profile ‘blank’

String

ID provided
resellerId Parent organization for prospective merchant ‘blank’

String

25
merchantId Parent merchant of prospective merchant ‘blank’

String

portfolioId Parent organization of reseller ‘blank’

String

522
feeTemplateId Fee setup template to be used with prospective merchant ‘blank’

String

50010
https://sandbox-manage.ziftpay.com/gates/onboarding?requestType=create&userName=api-user-1234
&password=mypass1234&profileType={}&resellerId=25&merchantId=&portfolioId=522
&feeTemplateCode=500010&isEmbedded=1&pageFormat=OBDA&notifyURL=https://ziftpay.com/cbtest/notify.php
&cancelURL=&returnURL=https://myreturnrul.com/&returnURLPolicy=redirect
Form Appearance and Control
isEmbeded Controls display of the provisioning form header and footer 0

1

1
pageFormat Controls the display of individual provisioning form pages and the progress header.  See next section for details on how to use this parameter. String OBDA
notifyURL URL to be called with the onboarding results String https://mynotifyurl.com/
cancelURL URL the prospective merchant is taken to if they click cancel.  If blank the cancel button will not appear. String
returnURL URL the prospective merchant is taken to if they click cancel.  If blank the cancel button will not appear. String  https://myreturnurl.com/
returnURLPolicy URL the prospective merchant is taken to after completing the merchant application. page

redirect

redirect
https://sandbox-manage.ziftpay.com/gates/onboarding?requestType=create&userName=api-user-1234
&password=mypass1234&profileType={}&resellerId=25&merchantId=&portfolioId=522
&feeTemplateCode=500010&isEmbedded=1&pageFormat=OBDA&notifyURL=https://ziftpay.com/cbtest/notify.php
&cancelURL=&returnURL=https://myreturnrul.com/&returnURLPolicy=redirect

Customizing Your Provisioning Page Flow

The provisioning process allows you to suppress specific pages in the merchant creation flow. You may want to suppress a page if you have already collected specific information from the merchant when they signed up to use your service or platform. You can pass us that information behind the scenes through the API. All pages except for the agreement (terms and conditions) page may be suppressed.

If a page is suppressed the form validation will not be used.  However, the API will validate all required data for type and format correctness.   Below are several example of how to use the pageFormat parameter to suppress specific pages in the provisioning process.

API Data Validation
If you suppress a specific page and the passed in data is invalid your perspecitve merchant will receive an API error. Your system will not be notified. Take care to make sure that all of your data is type and format correct when suppressing provisioning pages.

= First page  the prospective merchant will see.

Full Page Flow Sequence (pageFormat=OBDA)

Suppress Owner Information (pageFormat=BDA)

Suppress Owner and Business Information (pageFormat=DA)

Suppress Owner, Business and Deposit Information (pageFormat=A)

Suppress Business Information (pageFormat=BA)

Field Management

In addition to the ability to pre-populate field data in the Onboarding Application you can also change how individual fields behave.  You have the following field control options:

Read Only – To make a field read only add ‘@@’ to the beginning of the field value

Example: fieldName1=value1&fieldName2=@@value2

Hidden – To make a field hidden add ‘@!’ to the beginning of the field value

Example: fieldName1=value1&fieldName2=@!value2

Back Button Behavior
When a prospective merchant has entered invalid data they can use the back button to correct the data and then proceed. Back buttons will not give the prospective merchant access to suppressed pages to correct invalid data.