Passbook FAQ

Marin Todorov

This post is also available in: Russian

Answers to frequently asked questions about Passbook!

Answers to frequently asked questions about Passbook!

This is a blog post by iOS Tutorial Team member Marin Todorov, a software developer with 12+ years of experience, an independent iOS developer and the creator of Touch Code Magazine.

Passbook is one of the coolest new technologies in iOS 6. You can use it to create store cards, event tickets, coupons, and more!

To help you learn about Passbook, I wrote two massive chapters about it in iOS 6 by Tutorials. I also published an abbreviated version of the first of these chapters for free here.

Since the book has been released, there have been a lot of questions about Passbook. This is because Passbook is a bit more complicated than other Apple APIs – you have to do a lot of server side, command line, and certificate work, and it’s easy to make a mistake somewhere along the way.

So I thought it would be helpful to gather together the common questions people are asking on the forums and via email and put them together into this handy FAQ. We’ll include this in the next version of the book as a free update too! :]

I hope this helps, and I hope to see you make some amazing things with Passbook!

Q: When link to my pass is tapped on the iPhone, Safari tells me it cannot download this type of file. What gives?

A: That usually means Safari was not told by your web server that the content type of the file is “application/vnd.apple.pkpass”. Even if your web page is very simple and does not need any server programming I still recommend you to use PHP to dump the pass to the browser – that’ll give you the finest control over the process and minimize the errors you’ll need to handle.

Just dump the pass contents to the browser and set the content type of the file to “application/vnd.apple.pkpass” as described in the “Building the pass distribution website” section in “Intermediate Passbook”.

Q: When/Why do I need a server?

A: If you only need to send passes to your customers and not follow up on that you don’t really need a web server. You can send the passes via email to your most loyal customers or send the files over via chat, etc.

You DO need a web server if you want to keep a database of the generated passes, if you need to associate passes to a given customer, or if you are implementing a PassKit web service with push notifications and all the bells and whistles as described in “Intermediate Passbook”.

Q: My passes show up fine, but cannot be imported in Passbook!

A: This means your pass file is generally ok – it includes the required files in the proper format. Therefore Passbook can show a preview of the pass. However it means your pass does not pass validation when imported – this can be due different reasons. Watch carefully what happens when you try to import the pass – if it just disappears (vs sliding down) then definitely there was an error while validating the pass.

You should check the device console for error messages, they are usually very informative and you can find where your problem is. To learn how to check the console, check out the “What is wrong with my passes?” section in “Intermediate Passbook”.

Q: How can I preview my passes?

A: You can preview your passes either on your device (with the simple app you build in “Beginning Passbook”) or by double clicking the .pkpass file in Finder on your mac.

But be careful! The OSX Passbook preview is close to what will show up on the device, but not 100% identical. You can fast preview your progress on your Mac, but only the device preview gives you the most accurate rendering.

Q: My passes show up and import to Passbook, but I don’t get updates from my Passkit web service. Why not?

A: This most probably means the device cannot connect to your web service.

  • First check in your pass.json file – is the web service URL correct?
  • Then check the following – developer devices can connect over HTTP to your web service (if enabled in Settings\Developer\PassKit Testing), but all customer devices can connect to your web service ONLY via HTTPS.
  • Check again pass.json – is the URL starting with https?
  • Also, is your web hosting SSL (https) enabled?

If all of these are fine – fall back to reading through your device’s console, as described in “What is wrong with my passes?” section in “Intermediate Passbook”.

Q: What size should the images for my pass be?

A: The images are scaled down/up with their aspect ratio preserved. If the image does not adhere to the image slot aspect ratio, your images will be cropped after being resized to fill the spot.

Important! Note all the sizes below are in pixels for the retina images:

  • background@2x.png – 360px x 440px, the image is blurred and cropped a bit on all sides to fit visually inside passbook
  • icon@2x.png – 58px x 58px, a shine is automatically applied
  • logo@2x.png – 320px x 100px, usually you should not take up the whole width
  • strip@2x.png – 624px x 220px (sometimes varies a bit), a shine is applied, you can use suppressStripShine in your pass.json to disable the shine if you don’t want it
  • thumbnail@2x.png – 180px x 180px

Q: Can I change the font size/image size/layout of the pass?

A: Unfortunately you don’t have control over the layout. You’ll have to make the best with what Apple has decided for you. Inside “Beginning Passbook” you will find layout previews of the different types of passes, so you have a good idea what is more or less possible.

Q: Push notifications are not going through at all!

A: As noted in the book not every web host is OK to host a Passkit web service. Usually those all-in-one hosting packages won’t cut the cheeze for you.

Note that the PHP script that send push notifications connects to gateway.push.apple.com over SSL on port 2195. Many of the cheap hosting companies won’t allow outbound connections to custom port numbers. The best way to understand whether your hosting company allows that is to give them a friendly call and explain them what you need.

Q: I have trouble generating my pass certificate in the console following the instructions from “Beginning Passbook”.

A: If while working in terminal with the openssl command instead of the short cryptic success messages (like “MAC verified OK”) you see a lengthy output listing all the possible parameters to the openssl command that means the params to the command were somehow wrong.

This is due a hitch while copying the text from the PDF – sometimes the PDF viewer adds an extra space after “-” signs. Often we have readers having an extra space between “-” and the “passin” parameter. Double check your command to make sure there are no extra spaces.

Q: Where To Go From Here?

A: A month and a half after iOS 6 and Passbook’s launch I still believe the best resource on creating passes for Passbook anywhere is iOS 6 by Tutorials. It includes 200 pages guiding your through all kind of Passbook shenanigans and as a bonus you get access to the book readers’ forum, where other readers, forum moderators and I take time and try to help you if you get stuck.

I hope you enjoyed this FAQ and that it helps you out if you get stuck anywhere. If you have any questions or comments, please join the forum discussion below!

This is a blog post by iOS Tutorial Team member Marin Todorov, a software developer with 12+ years of experience, an independant iOS developer and the creator of Touch Code Magazine. You can also find me on

Marin Todorov

Marin Todorov is an independent iOS consultant and publisher with complimentary background in server and desktop development.

He started developing on an Apple ][ more than 20 years ago and keeps rocking till today. Meanwhile he has worked in great companies like Monster Technologies and Native Instruments, has lived in 4 different countries, and (more recently) is one the founding memebers of the raywenderlich.com tutorial team.

Besides crafting code, Marin also enjoys bloging, writing books, teaching and training others, and speaking at mobile conferences. He sometimes open sources his code. He walked the way to Santiago.

User Comments

6 Comments

  • Great list. Thanks for the information.
    neil2012
  • Great post
    marciokoko
  • Using the iOS tutorials and this post, I have just released PassMaker Pro for iPhone. Thanks for the posts Ray and the Team :)

    https://itunes.apple.com/au/app/passmaker-pro/id574194646?mt=8
    azza10
  • Just found it slightly confusing saying the image sizes are in pixels for retina devices. Want to clarify if you meant to say points ? i.e. regardless of retina or not, when you position a view, you specify those coordinates in points. OR pixels = points x scale.

    So, did you mean to say points or pixels?

    thanks!
    horseshoe7
  • @horseshoe7 - The sizes are in pixels - so you have to scale down by 50% to get the point sizes. I find it easier to understand this way when I explain to beginners :] So ... to answer your question - it's pixel sizes
    icanzilb
  • I'm creating a passbook library for Django for those who prefer to use Python over PHP. It allows for the creation and editing of passes as well as implementing the webservice.

    Contributors are welcome.

    https://github.com/stephenmuss/django-passbook
    el_toro

Other Items of Interest

Ray's Monthly Newsletter

Sign up to receive a monthly newsletter with my favorite dev links, and receive a free epic-length tutorial as a bonus!

Advertise with Us!

Vote for Our Next Tutorial!

Every week, we alternate between Gaming and Non-Gaming tutorial votes. This week: Non-Gaming!

    Loading ... Loading ...

Last week's winner: Best iOS Animations in 2014. [Read Now]!

Suggest a Tutorial - Past Results

Hang Out With Us!

Every month, we have a free live Tech Talk - come hang out with us!


Coming up in October: Xcode 6 Tips and Tricks!

Sign Up - October

Our Books

Our Team

Tutorial Team

... 49 total!

Update Team

... 15 total!

Editorial Team

... 22 total!

Code Team

  • Orta Therox

... 3 total!

Translation Team

  • Di Peng
  • David Hidalgo

... 32 total!

Subject Matter Experts

  • Richard Casey

... 4 total!