DOCUMENTATION


Getting Started with PassVerse


PassVerse makes it easy to add full Passbook support to your application. This page will guide you through the steps needed to install and configure PassVerse.

How PassVerse works


There are two services that make up PassVerse:

  • Management Server This is the API that your application uses, allowing it to generate, update, delete and track passes.
  • Registration Server The Registration server is accessed by the iPhones that your passes are installed on. It allows a pass to register itself and to check for udpates.
How PassVerse works

Deploying PassVerse


Installing PassVerse on your own servers is straightforward and takes between 5 and 10 minutes. You essentially host two web sites that will be used to manage your passes and installations.

Prerequisites

Your PassVerse server is going to need:

  • Windows Server 2008 or higher.
  • .Net Framework 4.5 installed
  • IIS with the ASP.Net Features enabled
  • MS SQL Server 2008 or higher to host the PassVerse database

Create a new database


Create a new database using SQL Server management studio. You can give it any name you wish.

The DataBase configured

Download and install the Management Server


Visit our downloads page and download the Management Server ZIP file. Extract the contents of this file to a suitable location e.g. C:\PassVerse\Management

Next, open your IIS Management Console and create a new WebSite called PassVerse Management. Ensure the physical path of the site is pointing to where you extraced the ZIP files to.

Adding the Management Server to IIS

The site should appear under IIS.

IIS with the management API configured

As these service use Certificates for signing the passes you generate, you must provide the Application Pool with additional settings to ensure they have the necessary Windows permissions to perform these actions.

Setting the Load User Profile permission to true

After you have created your Website, open the Application Pools seting and select the App Pool associated with the website. This usually has the same name as the website you created. Open the "Advanced Settings" from the context menu. Located the "Load User Profile" open under the "Process Model" section and ensure it's set to true.

Download and install the Registration Server


This time, download the Registration Server zip from our downloads page and extract the contents of this file to a suitable location e.g. C:\PassVerse\Registration

Add it to IIS in the same way you did before. You will need to use a different port, so I have selected 8080 in this example.

Both web sites setup in IIS

As you did with the Management Server, be sure to set the "Load User Profile" setting to true under the Application Pool settings for this site.

Setting the Load User Profile permission to true

Configuring the Management & Registration servers


The configuration needed for both servers is the same, but you have to update both seperately.

First, you need to specify the database that will be used by PassVerse. The database will be created automatically when you first run PassVerse. Open the web.config file and update the PassVerseContext connection string.

Correct database permissions You must ensure that whatever AppPool account you use has the necessary permissions for connecting to and updating the database.
<connectionstrings>
    <add name="PassVerseContext" connectionstring="Server=.;Initial Catalog=PassVerse;Integrated Security=SSPI;" providername="System.Data.SqlClient" />
</connecionstrings>

The other setting required is the URL for the Registration server. Open the web.config file and update the PassVerseContext connection string. As the Registration server needs to be publically visible on the internet, you can enter the appropriate domain and port here.

HTTPS is required - Apple's Passbook requires that the URL to the registration server is configured using HTTPS. During testing, you can configure your iPhone to use HTTP, but once you're in production, this will need to be HTTPS.

<appSettings>
    <add key="PassVerseRegistrationServer" value="https://myserver:8080" />
</appSettings>

Ensure you set both of these settings in the web.config for both the Management and Registration sites.

Create an Administrator account


Now that both the Management and Registration sites are up and running in IIS, you're now ready to continue. Open your browser and visit the Management site that you have just created. Since this is your first visit, you will be prompted to create an administrator account.

Setting up the adminstrator account

Add your Pass Type certificate


Every pass that you generate must be signed with your own Pass Type ID. These are generated from the Apple iOS Developer Portal. Apple have a good walkthrough on creating the Pass Type Identifier on the developer site. Once you have downloaded the certificate, you must upload it to PassVerse.

In the Management website, just navigate to Certificates and click the Add Certificate button.

Adding a certificate using the dashboard

After you've filled in the information, just click the Upload button. Your certificate is now available to use when generating passes.

Ensure values match the certificate - You must ensure the Pass Type Identifier and Team Identifier values you specify match the certificate exactly. If not, you will be unable to generate a valid Passbook file.

Your first template


To create your first template, you need to send a HTTP PUT request to the management server. For this example, we will create a simple loyalty card. Ensure that you replace the pass_type_identifier with the value contained in the certificate you added earlier. Each request to the Management API is authenticated using BASIC authentication. Just use the credentials for the Administrator account you created earlier.

PUT /api/v1/templates

Content-Type: application/json Authorization: Basic dGVzdEBwYXNzdmVyc2UuY29tOnRlc3Q=

Example

{
    "style":"StoreCard",
    "friendly_name":"My loyalty card",
    "description":"Tom's Coffee Shop Loyalty Card",
    "organization_name":"Tom's Coffee Shop",
    "pass_type_identifier": "pass_type_identifier",
    "header_fields":[{"key":"date","label":"Date", "type":"date"}],
    "primary_fields":[{"key":"balance", "label":"Balance", "type":"number"}],    
    "secondary_fields":[{"key":"name", "label":"Cardholder"}],    
    "background_color":"#F02E25",
    "text_color":"#FFFFFF",
    "label_color":"#FFFFFF",
    "icon_image_url":"http://www.passverse.com/sample/icon@2x.png",
    "barcode_type":"PKBarcodeFormatQR",
    "locations":[ {"latitude":51.500152, "longitude":-0.126236}]
}

You will get a HTTP 200 OK response and the body of the response will contain the location of the template and its template_id

Location: /api/v1/templates/111111-1111-1111-111111111111
{
    "template_id":"111111-1111-1111-111111111111"
}

Your first pass


To create your first pass, we'll just populate the fields in the template you just created.

PUT api/v1/pass/template_id

Content-Type: application/json Authorization: Basic dGVzdEBwYXNzdmVyc2UuY29tOnRlc3Q=
{
    "header_fields":[{"key":"date","value":"2013-07-30"}],
    "primary_fields":[{"key":"balance", "value":"0"}],    
    "secondary_fields":[{"key":"name", "value":"Malcolm Reynolds"}],    
    "barcode_value":"26352974623"
}

In response, you'll get a 200 OK and the serial_number of the new pass.

Location: /api/v1/pass/111111-1111-1111-111111111111/83466235423
{
    "serial_number": "1212121212",
}

Downloading the pass


Downloading the pass is performed by sending a GET request with the correct template_id and serial_number

GET api/v1/pass/111111-1111-1111-111111111111/1212121212

This will return you a fully packaged PKPASS file which you can open and install on an iPhone. By installing the pass, you will cause the pass to register itself using the Registration server.

Zero Balance

Sending an update


Now that we have a pass installed on our device, we can update the points balance to reflect a recent purhase. We will update the balance field to 50 by putting that value into the body of the POST.

POST api/pass/template_id/serial_number/field/balance

50

In response, you should receive a 200 OK. A push notification will be generated to your device and it should refresh it's pass.

Updated Balance

Next steps


You can read more about the API