==============
Apple Passbook
==============

Overview
--------

The Apple Passbook app allows users to store loyalty or gift cards in a digital format. Paytronix has developed functionality to generate a pass that includes account information. This page describes how to generate a pass through the Paytronix system.

Steps to Develop an "Add to Passbook" Function in Your App
----------------------------------------------------------

In order to generate passes for your mobile app, you need to follow the following steps:

.. contents:: :local:


Step 1: Create pass package and deliver to Paytronix
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The integrator must create a new pass identifier in the Apple development portal. Paytronix requires that the fifth part of this identifier correspond to the unique Paytronix merchant id. For example: ``pass.com.paytronix.merchant.30``. 

The integrator must provide Paytronix with the ``package.p12`` package and the associated password. The formatting of the package must meet the following requirements: A PKCS12 bundle containing the private key used to sign the certificate generated by Apple, followed by a certificate chain of X509 certificates in the following order: 
	
		#. The certificate generated by Apple and signed with the attached private key
		#. The intermediate certificate: :term:`Apple WWDR Certificate`

	This bundle must be protected with a password of non-zero length

.. tip:: `We have made the steps that Paytronix uses to create p12 files available here <./p12.html>`_

Step 2: Call the Passbook service to obtain the URL for the pass
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Please refer to the flow section below 

Step 3: Pull pass from URL and install pass on device
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The integrator should `consult Apple's documentation in order to accomplish this step. <https://developer.apple.com/library/ios/documentation/UserExperience/Conceptual/PassKit_PG/Chapters/Introduction.html>`_ 

Authentication
--------------

This flow supports the following authentication types: OAuth, B2B. Depending on the authentication type, more fields may be required. See this page for details: `API Authentication Styles <.././pxs_api_reference/authentication_types.html>`_


Flow
----

.. image:: passbook.png


1. Integration gathers information from the user. The information necessary depends on the authentication type
2. Integration sends passbookUrl call
3. The Paytronix System returns a success or failure

	a. If the result is success, then the integration should use the server response to obtain the user's pass
	b. If the result is failure then the integration should inform the guest of the failure. We suggest that the integration uses the error code and error message returned by the system to inform the guest of the problem, though the merchant should have final approval on the message’s wording.


Example
-------

Request Body

.. code:: javascript

	{
	  "authentication": "oauth",
	  "access_token": "bMHtVTxV5thisisnotarealtokenvZ_qbbrqrVusL",
	  "printedCardNumber": "600010109808929",
	  "merchantId": 777777
	}

Response 

.. code:: javascript

	{
	  "result": "success",
	  "url": "https://www.thisisnotarealurl.com/heresthepass"
	}

API Reference
-------------

Paytronix
~~~~~~~~~

Please see the following API reference page for more technical details: `Passbook Service <.././pxs_api_reference/apple_passbook.html>`_

Push service terminology is defined here: `Glossary <.././glossary.html#passbook-services-terms>`_

Apple
~~~~~

See the `Apple documentation <https://developer.apple.com/library/ios/documentation/UserExperience/Conceptual/PassKit_PG/Chapters/Introduction.html>`_