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:

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

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.

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

Flow

For guests registering through the app

../_images/iOS_push_register.png
  1. Gather the necessary information to register the guest (This flow is documented here)
  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

../_images/iOS_push_login.png
  1. The guest logs into the app (This flow is documented at this link)

  2. Integration sends accountInformation call to check whether the external account has already been set

    1. If the external account has already been set, do nothing further

    2. 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 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:

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

{
  "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

{
  "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

{
  "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

{
  "result": "success"
}

API Reference

Paytronix

Please see the following API reference page for more technical details: Enrollment Service

Push service terms have been defined here: Glossary

Apple

See the Apple documentation for a full explanation of Apple’s push messaging service.