future_payments_mobile.md

Future Payments Mobile Integration

This section will show how to obtain a user's authorized consent for future payments using their PayPal account.

If you haven't already, see the README for an initial overview and instructions for adding the SDK to your project.

Overview

Your app will use the mobile SDK to obtain two pieces of information at different times.

First, you must obtain customer consent to take payments from their PayPal account. How this works:

• The PayPal Android SDK...
  1. Presents UI for your user to authenticate using their PayPal account.
  2. Asks your user to consent to OAuth access token scope to use PayPal for future payments.
  3. Returns an OAuth2 authorization code to your app.
• Your app...
  1. Receives an OAuth2 authorization code from the SDK.
  2. Sends the authorization code to your server, which then exchanges the code for OAuth2 access and refresh tokens.

Later, when initiating a pre-consented payment, you must obtain a Client Metadata ID. How this works:

• The PayPal Android SDK...
  • Provides a Cient Metadata ID.
• Your app...
  • Sends the client metadata ID and transaction information to your server.
  • Your server then uses its OAuth2 tokens, Client Metadata ID, and transaction info to create a payment.

Obtain Customer Consent

The sample app provides a more complete example. However, at minimum, you must:

1. Add PayPal Android SDK dependency to your build.gradle file as shown in README.md

2. Create a PayPalConfiguration object. This object allows you to configure various aspects of the SDK.

   private static PayPalConfiguration config = new PayPalConfiguration()
   
   		// Start with mock environment.  When ready, switch to sandbox (ENVIRONMENT_SANDBOX)
   		// or live (ENVIRONMENT_PRODUCTION)
           .environment(PayPalConfiguration.ENVIRONMENT_NO_NETWORK)
   
           .clientId("<YOUR_CLIENT_ID>")
           
           // Minimally, you will need to set three merchant information properties.
   		// These should be the same values that you provided to PayPal when you registered your app.
           .merchantName("Example Store")
           .merchantPrivacyPolicyUri(Uri.parse("https://www.example.com/privacy"))
           .merchantUserAgreementUri(Uri.parse("https://www.example.com/legal"));

3. Start PayPalService when your activity is created and stop it upon destruction:

   @Override
   protected void onCreate(Bundle savedInstanceState) {
       super.onCreate(savedInstanceState);
       setContentView(R.layout.activity_main);
   
       Intent intent = new Intent(this, PayPalService.class);
   
       intent.putExtra(PayPalService.EXTRA_PAYPAL_CONFIGURATION, config);
   
       startService(intent);
   }
   
   @Override
   public void onDestroy() {
       stopService(new Intent(this, PayPalService.class));
       super.onDestroy();
   }

4. Launch the PayPal Future Payment activity, for example, when a button is pressed:

   public void onFuturePaymentPressed(View pressed) {
       Intent intent = new Intent(SampleActivity.this, PayPalFuturePaymentActivity.class);
   
       // send the same configuration for restart resiliency
       intent.putExtra(PayPalService.EXTRA_PAYPAL_CONFIGURATION, config);
       
       startActivityForResult(intent, REQUEST_CODE_FUTURE_PAYMENT);
   }

5. Implement onActivityResult():

   @Override
   protected void onActivityResult (int requestCode, int resultCode, Intent data) {
       if (resultCode == Activity.RESULT_OK) {
           PayPalAuthorization auth = data
                   .getParcelableExtra(PayPalFuturePaymentActivity.EXTRA_RESULT_AUTHORIZATION);
           if (auth != null) {
               try {
                   String authorization_code = auth.getAuthorizationCode();
   
                   sendAuthorizationToServer(auth);
   
               } catch (JSONException e) {
                   Log.e("FuturePaymentExample", "an extremely unlikely failure occurred: ", e);
               }
           }
       } else if (resultCode == Activity.RESULT_CANCELED) {
           Log.i("FuturePaymentExample", "The user canceled.");
       } else if (resultCode == PayPalFuturePaymentActivity.RESULT_EXTRAS_INVALID) {
           Log.i("FuturePaymentExample",
                   "Probably the attempt to previously start the PayPalService had an invalid PayPalConfiguration. Please see the docs.");
       }
   }

6. Send the authorization response to your server in order to complete the process.

   private void sendAuthorizationToServer(PayPalAuthorization authorization) {
       
       // TODO:
       // Send the authorization response to your server, where it can exchange the authorization code
       // for OAuth access and refresh tokens.
       //
       // Your server must then store these tokens, so that your server code can execute payments
       // for this user in the future.
       
   }

Obtain a Client Metadata ID

When initiating a pre-consented payment (a "future payment") from a mobile device, your mobile application must obtain a Client Metadata Id from the Mobile SDK to pass to your server. Your server must include this Client Metadata ID in its payment request sent to PayPal.

PayPal uses this Client Metadata ID to verify that the payment is originating from a valid, user-consented device+application. This helps reduce fraud and decrease declines. PayPal does not provide any loss protection for transactions that do not correctly supply a Client Metadata ID.

Do not cache or store this value.

Example:

public void onFuturePaymentPurchasePressed(View pressed) {
// Get the Client Metadata ID from the SDK
String metadataId = PayPalConfiguration.getClientMetadataId(this);
        
// TODO: Send metadataId and transaction details to your server for processing with
// PayPal...
}

When your server makes its payment request to PayPal, it must include a PayPal-Client-Metadata-Id HTTP header with this Client Metadata ID value obtained from the SDK.

Next Steps

Read Future Payments Server-Side Integration to exchange the authorization code for OAuth2 tokens and create payments with an access token and a Metadata ID.