Sign in with Apple¶

Overview¶

For iOS Apps, Apple requires that any app that supports Login with Facebook must also support Sign in with Apple. This document gives an overview of the steps necessary to set up Sign in with Apple for integrators including:

Configuring Sign in with Apple key for Paytronix
Understanding Sign in with Apple Flow with Paytronix

Configuring Sign in with Apple Key¶

The first step to integrating with Paytronix Sign in with Apple Flow is to create and register a Sign in with Apple key.

Log into your Apple Developers Account
Choose “Identifiers” on the left navigation
Then choose “Key” and select the blue plus icon to add a new key
Name the Key and make sure to check “Sign in with Apple”
Choose “Configure” and select the primary App ID associated with the app you are developing for

Note

There might be multiple Bundle IDs associated with this merchant. Ensure that the primary app ID is the same as the Bundle ID associated with the merchant you want to enable Apple Sign in for.
Make sure to “Register” the key on the next page, this will generate the key
You have created a Sign in the Apple Key for your app! Make note of the Key ID and download the .p8 to upload to Paytronix next

Warning

The .p8 is only available for download ONCE! Do not download if you’re not sure what you’re doing!

Once you have successfully created a key, contact Paytronix for assistance sharing your key information securely with our team. Once our team configures your integration for Sign in with Apple, you will be able to make calls to the Paytronix API.

Introduction to Apple’s Sign-In Flow¶

This section will explain how to call Paytronix API and get the information needed to successfully sign in a guest with Paytronix via a Sign in with Apple external account. This diagram outlines the flow that Paytronix uses:

The Sign in with Apple process begins with the guest triggering a call to Apple’s API via the mobile app’s “Sign in with Apple” button which generates a secure 2-Factor Authentication session with Apple on behalf of the guest. For more information about configuring the Sign in with Apple button see this link to Apple’s Documentation

Once the guest successfully logs in, Apple will return an “Authentication Response” to the mobile app that hosts the Sign in with Apple button. The most relevant contents of Apple’s Authentication Response include

id_token: identity token as a JSON Web Token (JWT) containing a sub
- sub: a unique, static string identifying the user, this page will refer to the sub as the “appleIdentityToken”
code : authorization code, this page will refer to “appleAuthorizationCode”

The response also includes other information that, while still important, is not used in the Paytronix flow.

Flow #1: Guest has a Paytronix account that is already associated with their Apple account¶

Make a POST request to Paytronix POST oauth/requestGuestToken.json endpoint using “Grant by User Fields” to get PX tokens See example:

{
  "authentication": "b2b",
  "client_id": "N76exhhWvbk1zUTkuNMkum7hvXzD0f5HO2l78MqLxx",
  "client_secret": "testSecret",
  "grant_type": "http://paytronix.com/oauth/fieldset",
  "merchantId": 10101010,
  "scope": "user_read account_read",
  "fields": {
    "externalIdentifier": "paytronixSpecificAppleIntegrationIdentifier",
    "externalAccessToken": "appleAuthorizationCode",
    "externalAccountCode": "appleIdentityToken"
    }
}

In the above example, externalIdentifier is Paytronix’s “Sign in with Apple” specific integration code. Contact the Paytronix team to get this identifier value

Paytronix will attempt to find guest’s external account. If the guest’s matching external account cannot be located, Paytronix returns an authentication.no_matching_guest error code to the mobile app
If the guest’s external account can be located, Paytronix will attempt to verify the guest with Apple’s API. If Apple’s API returns a failure Paytronix returns an authentication error code to the mobile app
Otherwise, the login flow was successful and Paytronix returns SuccessTokenResponse to the mobile app which includes tokens for login

Flow #2: Guest does not have an existing Paytronix account or account is not associated with their Apple account¶

If Paytronix is unable to locate the guest’s matching external account, the mobile app should initiate Flow #2

Make a POST request to Paytronix POST enrollment/createAndRegister.json endpoint. See example:

{
    "authentication": "b2b",
    "client_id": "f_sdkjyhhWvbk1zUTsppasfaf5HO2l78MqLxx",
    "client_secret": "secret",
    "merchantId": 10101010,
    "cardTemplateCode": 0,
    "activationStoreCode": "pxweb",
    "enforceUniqueFields": [],
    "setUserFields": {
        "style": "typed",
        "username": "testUsername",
        "password": "testPassword"
    },
    "setAccountFields": {
        "style": "typed",
        "externalAccounts": [{
          "accountCode":"appleIdentityToken", //JWT identity token
          "integration":"appleIntegrationIdentifier",
          "accessToken": "appleAuthorizationCode"
        }]
    }
}

Paytronix attempts to create a new account and return a PX token pair to the mobile app