iOS Push Messaging Services =========================== Overview -------- An important component of building guest engagement with your app is communicating with push messages. In order to allow your mobile app to receive notifications sent by the Paytronix system, you must follow the steps on this page. Steps to Receive Push Messages from the Paytronix System -------------------------------------------------------- In order for your app to register the guest's device to receive push notifications, you need to follow the following steps: .. contents:: :local: Step 1: Configure your app to register with the Apple Push Notification Service (APNS) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The integrator must create a new app identifier in the Apple development portal. This identifier will be sent to Paytronix in Step 3. The integrator must provide Paytronix with a ``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 a single X509 certificate. This certificate is the one generated by Apple for your specific app and signed with the attached private key. 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 <./push_p12.html>`_ This package will need to be sent once for the development environment, and again for the production environment once the app is certified. Step 2: Add code to your application to get the push identifier for a device ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The integrator should consult Apple's documentation in order to accomplish this step. Step 3: When the user adds a card (signs in/registers) send the push identifier to Paytronix as an external account ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Please refer to the `flow`_ section below Authentication -------------- This flow supports the following authentication types: guest, card, and OAuth. 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 ---- For guests registering through the app ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. image:: iOS_push_register.png 1. Gather the necessary information to register the guest (`This flow is documented here <.././mobile_application/registration.html>`_) 2. Send the external account in the call to register the guest. The external account should follow this format: `Format of External Account Object`_ 3. Handle the server response as you normally would when registering guests For guests logging into the app ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. image:: iOS_push_login.png 1. The guest logs into the app (`This flow is documented at this link <.././mobile_application/login.html>`_) 2. Integration sends accountInformation call to check whether the external account has already been set a. If the external account has already been set, do nothing further b. If the external account hasn't been set, then send an editExternalAccount call to Paytronix with the external account formatted according to this specification: `Format of External Account Object`_. The Paytronix server will return either a failure or success message. \i. If the server response is success, then the flow is complete \ii. If the server response is a failure, then it is up to the merchant on how to handle the situation. It is suggested that the integration uses the error code and error message returned by the system to determine the next action. Format of External Account Object ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ See :http:jsonentity:`SetExternalAccount` for the full definition of an external account. When formatting an external account, please include the following fields: ``accountCode`` This is the device token encoded in hexadecimal. ``integration`` This is the client_id you were provided when you registered your integration with Paytronix. It should be specific to your iOS application. If you implement both an iOS and Android application they should have different integration identifiers. ``integrationDetail`` This is information about the device the app is being run on. Paytronix uses the following lines to generate this information: .. code:: objc UIDevice* device = [UIDevice currentDevice]; NSString* detail = [NSString stringWithFormat:@"os=%@|osversion=%@|device=%@|merchantId=%lu|integrator=Paytronix|version=12.0", [device systemName], [device systemVersion], [device model], (unsigned long)[self merchantID]]; ``appIdentifier`` This indicates the app which we will push to. This should be your bundle identifier. Examples -------- createAndRegister ~~~~~~~~~~~~~~~~~ This is an example `for guests registering through the app`_ Request Body .. code:: javascript { "authentication": "anonymous", "client_id": "3FTmkQuXBnotarealcklientIDFCO9PREEnj_WHaK", "client_secret": "654secretnx4", "merchantId": 777777, "cardTemplateCode": 0, "enforceUniqueFields": [ "mobilePhone" ], "setUserFields": { "style": "typed", "username": [ "john.doe" ], "password": [ "open123" ], "mobilePhone": [ "7894563210" ] }, "setAccountFields": { "style": "typed", "favoriteStore": [ { "code": "123" } ], "externalAccounts": [ { "appIdentifier": "com.examplecompany.appname", "accountCode": "98d0f8677777dc227777770609f9131583d7777771e24d330068777777ef6cc5345", "integrationDetail": "os=iPhone OS|osversion=8.3|device=iPhone|merchantId=777777|integrator=examplecompany|version=12.0", "integration": "3FTmkQuXBnotarealcklientIDFCO9PREEnj_WHaK" } ] } } Response .. code:: javascript { "result": "cardCreatedSuccess", "generatedRegistrationCode": "123456", "oauthTokens": { "access_token": "rIe7dgL5pthisisnotarealtokenqrFbA268pw5GP", "expires_in": 1800, "printedCardNumber": "9990000003239", "refresh_token": "PvOuthisisnotarealrefreshtokenN45TV4kGq", "scope": "account_read account_write user_read user_write", "token_type": "bearer", "username": "john.doe" }, "printedCardNumber": "9990000012345" } editExternalAccount ~~~~~~~~~~~~~~~~~~~ This is an example `for guests logging into the app`_. Request .. code:: javascript { "operation": "add", "externalAccounts": [ { "appIdentifier": "com.examplecompany.appname", "accountCode": "98d0f8677777dc227777770609f9131583d7777771e24d330068777777ef6cc5345", "integrationDetail": "os=iPhone OS|osversion=8.3|device=iPhone|merchantId=777777|integrator=examplecompany|version=12.0", "integration": "3FTmkQuXBnotarealcklientIDFCO9PREEnj_WHaK" } ], "merchantId": 777777, "client_id": "3FTmkQuXBnotarealcklientIDFCO9PREEnj_WHaK", "client_secret": "654secretnx4", "access_token": "rIe7dgL5pthisisnotarealtokenqrFbA268pw5GP", "authentication": "oauth", "printedCardNumber": "600030100041234455" } Response .. code:: javascript { "result": "success" } API Reference ------------- Paytronix ~~~~~~~~~ Please see the following API reference page for more technical details: `Enrollment Service <.././pxs_api_reference/enrollment.html>`_ Push service terms have been defined here: `Glossary <.././glossary.html#push-services-terms>`_ Apple ~~~~~ See the `Apple documentation `_ for a full explanation of Apple's push messaging service.