Getting Started

This section describes the tasks that you complete to start working with the SDK.

Prerequisites

To install the SDK and run the sample apps, you'll need:

  • An iOS device, such as an iPhone or iPad.
  • The Xcode 5.1+ integrated development environment.
  • An active Apple developer account to run the sample app on devices to use the credit card reader.
  • A PayPal Here card reader.
    • PayPal provides a mag stripe card reader on request for any user who opens a PayPal Business account. This card reader plugs into the iPhone's audio jack.
    • A PayPal EMV card reader is available for purchase.

To develop your own apps, you need the previous resources plus:

  • A Log In with PayPal (PayPal Access) app, and PayPal Here capability. The Log In with PayPal capabilities, at a minimum, need to specify name, email, and address.
  • An app ID (from developer.paypal.com) and secret; the app ID is also called a client ID. Be sure to enable the Log In with PayPal feature.
  • For authentication in production, a back-end server to store your secret.

If you're a third-party service provider, a merchant who uses your app must have:

  • A PayPal Business account.
  • An account with their own service ID.

Obtaining the SDK

To begin using the SDK, go to GitHub repository to get the software, review the README file, and try building the SDK. Confirm that you have an SSH key set up with the GitHub server.

Then, review the TakePayment Sample App.

Authenticating SDK operations

The PayPal Here SDK uses the OAuth 2.0 standard for authentication; that is, for confirming that an app requesting SDK services on behalf of a certain merchant is authorized to do so. Your app API calls must include a Log In with PayPal (PayPal Access) authentication token to indicate the merchant on whose behalf the calls are made.

The authentication process has several steps:

  1. Log in to the My Apps & Credentials page on the PayPal Developer site and create a PayPal application to obtain OAuth credentials. When you create the application, specify the Log In with PayPal capability.
  2. The developer site provides an OAuth client ID and a secret for your app to use. For security, you store the secret (and the client ID too, if you prefer) on your app mid-tier server and not in the app itself.
  3. The first time a merchant uses your app, your mid-tier server should direct them to the PayPal Identity service. In addition to the endpoint's URL, the server provides a return URL that PayPal can use to return control to your app. The return URL should point to an endpoint on your mid-tier server that will return the merchant's device to your app.
  4. The Identity service prompts the merchant to grant your app permission to run PayPal Here transactions on their behalf. The merchant grants permission by entering their PayPal account user name and password and possibly answering questions about the scope of permission they want to grant. PayPal then redirects your mid-tier server to the return URL, returning the merchant's device to your app. If the merchant granted permission to run transactions, the redirect includes an authentication code that represents the scope of the permission they granted.
  5. Your app submits its client ID and the authentication code to the Identity service through the mid-tier server, and obtains a long-lived refresh token. For security, the mid-tier server should encrypt the token. For more information see Developing a mid-tier server.
  6. Your app submits the refresh token to the Identity service, again through the mid-tier server, to obtain a short-lived access token. Repeat this step periodically when the access token expires.
  7. Your app must include the current access token in each call it makes to the PayPal Here SDK.

You must pass the PayPal Here scope identifier with each request for an access token, along with additional scopes as listed below. Note that the scope identifiers are URIs, which are identifiers and not links:

https://uri.paypal.com/services/paypalhere
email
address
https://uri.paypal.com/services/paypalattributes/business

For more information about the client ID, secret, and scope, see How PayPal uses OAuth 2.0 and Integrate Log In with PayPal.

For models of how to perform the authentication process (steps 2 through 5), see Developing a mid-tier server.

Best practices for security

Do not store your app secret in the app on a mobile device, as it could be jail-broken or otherwise compromised. (If your app secret is compromised, barriers are raised in your ability to provide updates to users.) Store your app secret on the mid-tier server.

In principle you can use Log In with PayPal as your sole means of authentication. You probably have an existing account system, though, so you should authenticate the merchant in your account system, then send them to PayPal, and then link their PayPal account to their account in your system when the authentication point redirects to your return URL.

Developing a mid-tier server

You must develop a mid-tier server to inter-operate with your app.

The essential function of the mid-tier server is to store your app secret in a secure place. The mid-tier server may perform additional functions at your discretion.

There are two basic approaches to designing a mid-tier server:

  • You proxy all calls to the PayPal Here SDK through the mid-tier server. The access token is stored on the server.
  • You only proxy the operations used to obtain access tokens through the mid-tier server. Your app makes other PayPal Here SDK calls directly, and the underlying services return results to it directly. The access token is stored in the app in encrypted form.

See our sample mid-tier server implementation and documentation on GitHub.