Getting Started

You must complete these tasks before you can work with the SDK.

Prerequisites

Before starting to use the PayPal Here API, you must have the following:

  • A PayPal log in ID
  • A secret
  • Access to a server

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

  • An Android OS Gingerbread or higher (Android SDK version 10 or later) device, such as an Android phone or tablet.
  • An integrated development environment (IDE) that supports development for the Android environment.
  • 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 in to an Android audio jack.
    • PayPal EMV card reader is available for purchase.

To develop your own apps you'll need the resources listed above, plus:

  • A Log In with PayPal (PayPal Access) app, and PayPal Here capability. The Log In with PayPal capabilities needs at a minimum 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 the GitHub repository to obtain the software. Confirm that you have an SSH key set up with the GitHub server.

Review the SDK's Readme file in the GitHub repository, and try building the SDK. Then review Functionality of PayPalHereSampleApp.

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 PayPal Developer site My Apps & Credentials page and create a PayPal application to obtain OAuth credentials. When you create the application, specify the capability Log In with PayPal.

  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, not in the app itself.

  3. When a merchant begins using your app, your mid-tier server should direct them to the PayPal endpoint URL. Also, the server provides a return URL that PayPal can use to return control to your app. The return URL should refer to an endpoint on your mid-tier server that PayPal can use to direct the merchant device back to your app.

    An app should require a merchant to log in each time it is opened. Once a merchant has logged in, their credentials typically are considered good until the merchant logs out or the app is opened again.

  4. The Identity service prompts the merchant to grant your app permission to execute PayPal Here transactions on their behalf. The merchant grants permission by entering their PayPal account's 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 execute transactions, the redirect includes an authentication code which 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 and The sample 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. This step must be repeated 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.

  8. To handle token expiration and obtain a new token, implement the AuthenticationListener interface and define the onInvalidToken method. Typically the onInvalidToken method invokes the previously-obtained refresh URL to retrieve a new access token, refresh URL, and token expiration value. For additional information, see The sample app.

    Note: The sample server and app delivered with the SDK include a test client ID and secret, along with a predefined test merchant. However, when you are ready to get your own client ID, you must contact your relationship manager to have your app client ID assigned a scope that includes PayPal Here.

    You must pass PayPal Here's scope identifier with each request for an access token. Note that the scope identifiers are URIs, which are identifiers, 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 The sample server, and the sample server's source code.

How to provide OAuth credentials to the SDK

Construct an OauthCredentials object, providing the access token to the constructor. Store the new object in a Credentials variable. Give the credentials to the SDK by calling PayPalHereSDK.setCredentials():

String accessToken = . . .;
Credentials credentials = new OAuthCredentials(accessToken);

PayPalHereSDK.setCredentials(credentials,
  new DefaultResponseHandler<merchant, PPErrorMerchantManager.merchantErrors>;() {
    @Override
    public void onSuccess(Merchant merchant) {
      // Perform any necessary setup; for example, register an authentication listener.
      . . .
    }
    @Override
    public void onError(PPErrorMerchantManager.merchantErrors errors) {
      // Handle an error.
      . . .
    }
  }
);

How to refresh the access token

Because the access token is short-lived, your app needs to provide for refreshing it when it expires.

Implement the AuthenticationListener interface and define the onInvalidToken method to call the refresh URL. The refresh URL returns a new access token, refresh URL, and token expiration value. You need not save the new access token; the SDK does that internally.

import com.paypal.merchant.sdk.AuthenticationListener;
. . .
protected AuthenticationListener authListener = new AuthenticationListener() {
  @Override
  public void onInvalidToken() {
    String refreshUrl = . . .;
    RefreshTokenTask refreshAccessTokenTask = new RefreshTokenTask();
    refreshAccessTokenTask.execute(refreshUrl);
  }
};

Register the listener with the SDK:

PayPalHereSDK.registerauthenticationListener(authListener);

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.

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.

Because the mid-tier server functions are simple, the sample server distributed with the SDK is a suitable (and recommended) starting point for developing your own. See The sample server for information about this 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.