Make future payments

When you integrate your mobile app with the PayPal Mobile SDK 2.0, your customers can give permission to be billed multiple times in the future without logging into their PayPal account. PayPal payments (not direct credit card payments) are supported.

The basic steps for authorizing and making future payments are the following:

  1. Get an auth code for future payments, using the PayPal Mobile SDK.
  2. Exchange the auth code for refresh and access tokens, using your back-end server.
  3. Call the Payments API, using your back-end server.

Notes:

  • Before building your app, please read the required best practices.

  • To accept future payments in the live environment, enable your PayPal account; see Dashboard > My Account.

Future payments can be ideal for use cases in which customers give permission to be charged variable or fixed amounts in the future, as described below.

See PayPal Mobile SDKs for an overview of the Mobile SDKs and links to downloads and documentation on GitHub.

Get an auth code

Confirm that the settings for your REST app on the Developer site includes the Future Payments option.

  • Navigate to the My Apps & Credentials page, and click on your app to edit its settings.
  • In the App Settings section, make sure that Accept Payments is checked. Then, click Advanced options.
  • Check the Future Payments checkbox.

For more information about the settings of your REST app on the Developer site, see Manage your applications.

To set up user authentication (consent), integrate your mobile app with a PayPal Mobile SDK.

After your customer uses your mobile app to consent to future payments, the PayPal Mobile SDK provides your app with an OAuth2 authorization code (auth code). Your mobile app sends that auth code to your back-end server. See the documentation delivered with the PayPal Mobile SDKs.

Exchange the auth code for refresh and access tokens

Your back-end server immediately uses the short-lived OAuth2 authorization code, along with your app's client ID and client secret, to get an OAuth2 access token and refresh token. The interaction between your server and the PayPal APIs is a standard OAuth2 request as described in the OAuth 2.0 Authorization Framework.

Depending on your payment system, the short-lived access token can be used immediately for a payment or an authorization/capture. The refresh token is long-lived (currently 10 years), and must be stored securely.

For any future payment or authorization/capture, since the access token will have expired, use the refresh token to get a new access token for calling the Payments API.

Documentation and sample code are delivered with the PayPal Mobile SDKs. The returned auth code and the returned tokens should be considered variable in length (and the length may increase in the future).

Call the Payments API

When a user initiates a payment with your mobile app, your mobile app must get a metadata ID (a PayPal-Client-Metadata-Id header) from the PayPal Mobile SDK. When your mobile app sends that ID to your back-end server, your back-end server does the following:

  1. Receives the metadata ID, which is described in the required best practices section, from your mobile app.
  2. Uses a refresh token, from the section above, to get a new access token.
  3. Includes the metadata ID and access token in a standard Payments API call (direct sale or authorization/capture).

See the documentation and sample code for all of the above steps in the PayPal Mobile SDKs on GitHub. For links to the Payments API documentation, see the Payments API overview.

Required best practices for future payments

The following best practices are required for apps that support future payments.

Using a PayPal metadata ID

To decrease payment declines, you must specify a metadata ID header (PayPal-Client-Metadata-Id) in the payment call.

Your mobile app gets a metadata ID from the PayPal Mobile SDK and sends the metadata ID to your back-end server. Your back-end server includes the metadata ID in the Payments API call. For sample code, see the documentation delivered with the PayPal mobile SDK.

Do not cache or store the metadata ID. PayPal provides no loss protection if a metadata ID was not correctly specified. To help reduce fraud and decrease declines, PayPal uses the metadata ID to help verify that a payment originated from a valid, user-consented device and app. Please do not rely only on the metadata ID; when you charge your customer's bank account, you still need to show that you were entitled to make the charge, e.g. that your customer has actually requested your service.

To help reduce fraud and to provide the best transparency for users, your app must do the following:

  • Collect the customer's consent to the exact amount before requesting a payment, and
  • In order to fight unauthorized use of your customer's phone by third parties, provide appropriate identification steps. This helps keep your customers secure, prevents unnecessary refund claims, and helps create a great customer experience.

Just as your app will get user consent for future payments, your app must enable customers to delete consent for future payments.

The page with your frequently-asked questions (FAQs) for customers must include the following text:

To delete consent for PayPal future payments for an app, log into your PayPal account profile at https://www.paypal.com/, and access My settings. For the Log In with PayPal setting, click Change and remove the mobile app from the list.

Enabling payment choices

Your app must provide customers the option of changing their payment method before making a payment.