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)
Step 2: Add code to your application to get the push identifier for a device
Step 3: When the user adds a card (signs in/registers) send the push identifier to Paytronix as an external account

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 .p8 file and the associated Apple Developer Team ID and Token Key ID.

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: B2B, 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¶

Gather the necessary information to register the guest (This flow is documented here)
Send the external account in the call to register the guest. The external account should follow this format: Format of External Account Object
Handle the server response as you normally would when registering guests

For guests logging into the app¶

The guest logs into the app (This flow is documented at this link)
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",
  "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"
}

editExternalAccounts¶

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,
  "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.