One-time Payments

Android v5

• Current Braintree SDKs
• Android v5
• iOS v6
• JavaScript v3
• Previous Versions
• Android v4
• iOS v5
• JavaScript v2

Pay with PayPal's One-time Payments is a one-click solution that accelerates your buyer's checkout experience by skipping manual data entry. Buyers can use PayPal to check out anywhere in their shopping journey. Placing payment buttons on the cart, product details page, or another page as a checkout shortcut can reduce steps to pay.

Setup

Get the SDK

Add the following in your app-level build.gradle:

dependencies {
    implementation("com.braintreepayments.api:paypal:5.8.0")
}

Invoking the One-time Payments flow

Initialization

Create a PayPalLauncher inside of your Activity's onCreate(). Then, create a PayPalClient with a Tokenization Key or Client Token and an appLinkReturnUrl that is used to return to your app from the PayPal payment flows.

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)

    // PayPalLauncher must be initialized in onCreate
    payPalLauncher = PayPalLauncher()

    // can initialize the PayPalClient outside of onCreate if desired
    payPalClient = PayPalClient(
        context = this,
        authorization = "[TOKENIZATION_KEY or CLIENT_TOKEN]",
        appLinkReturnUrl = Uri.parse("https://merchant-app.com"), // Merchant App Link
        "com.merchant.app.deeplink.braintree" // Fallback deep link return url scheme
    )

Request a payment

After the user clicks the PayPal button, create a PayPalCheckoutRequest and call PayPalClient.createPaymentAuthRequest() and handle its result. If the result is Failure, handle the error. If the result is ReadyToLaunch, invoke PayPalLauncher.launch() and check the returned PayPalPendingRequest.

If Started is returned, the PayPal flow was launched and the Started.pendingRequestString needs to be persisted. If Failure was returned, handle the error.

private fun onPayPalButtonClick() {
    val request = PayPalCheckoutRequest(
        amount = "12.34",
        hasUserLocationConsent = true
    )
    payPalClient.createPaymentAuthRequest(this, request) { paymentAuthRequest ->
        when (paymentAuthRequest) {
            is PayPalPaymentAuthRequest.ReadyToLaunch -> {
                val pendingRequest = payPalLauncher.launch(this, paymentAuthRequest)
                when (pendingRequest) {
                    is PayPalPendingRequest.Started -> {/* store pending request */ }
                    is PayPalPendingRequest.Failure -> { /* handle error */ }
                }
            }
            is PayPalPaymentAuthRequest.Failure -> { /* handle paymentAuthRequest.error */ }
        }
    }
}

Handle the payment result

Once the user completes or cancels the PayPal Checkout flow the Intent needs to be handled. If your Activity's launch mode is SINGLE_TOP, the Intent needs to be handled in onNewIntent(). For all other launch modes, handle the Intent in onResume().

Call PayPalLauncher.handleReturnToApp() and pass in the persisted pendingRequestString and Intent. Handle the returned PayPalPaymentAuthResult.

If NoResult is returned, the user has canceled the payment flow or returned to the app without completing the payPal flow. If Failure is returned, handle the error. If Success is returned, pass the Success object to PayPalClient.tokenize().

The PayPalClient.tokenize() function takes a PayPalTokenizeCallback which returns a PayPalResult. When the result is Cancel, the user canceled the flow. When the result is Failure, handle the error. When the result is Success, a single-use token value is returned inside of PayPalAccountNonce.

You can query the PayPalAccountNonce result for specific customer information if needed.

// ONLY REQUIRED IF YOUR ACTIVITY LAUNCH MODE IS SINGLE_TOP
override fun onNewIntent(intent: Intent) {
    super.onNewIntent(intent)
    handleReturnToApp(intent)
}

// ALL OTHER ACTIVITY LAUNCH MODES
override fun onResume() {
    super.onResume()
    handleReturnToApp(intent)
}

private fun handleReturnToApp(intent: Intent) {
    // fetch stored PayPalPendingRequest.Success
    val pendingRequest: String = fetchPendingRequestFromPersistantStore()
    when (val paymentAuthResult = payPalLauncher.handleReturnToApp(
        pendingRequest = PayPalPendingRequest.Started(pendingRequest),
        intent = intent
    )) {
        is PayPalPaymentAuthResult.Success -> {
            completePayPalFlow(paymentAuthResult)
            // clear stored PayPalPendingRequest.Success
        }

        is PayPalPaymentAuthResult.NoResult -> {
            // user returned to app without completing PayPal flow, handle accordingly
        }

        is PayPalPaymentAuthResult.Failure -> {
            // handle error case
        }
    }
}

private fun completePayPalFlow(paymentAuthResult: PayPalPaymentAuthResult.Success) {
    payPalClient.tokenize(paymentAuthResult) { result ->
        when (result) {
            is PayPalResult.Success -> { /* handle result.nonce */ }
            is PayPalResult.Failure -> { /* handle result.error */ }
            is PayPalResult.Cancel -> { /* handle user canceled */ }
        }
    }
}

Complete integration

class MyActivity : AppCompatActivity() {

    private lateinit var payPalLauncher: PayPalLauncher
    private lateinit var payPalClient: PayPalClient

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        // PayPalLauncher must be initialized in onCreate
        payPalLauncher = PayPalLauncher()

        // can initialize the PayPalClient outside of onCreate if desired
        payPalClient = PayPalClient(
        context = this,
        authorization = "[TOKENIZATION_KEY or CLIENT_TOKEN]",
        appLinkReturnUrl = Uri.parse("https://merchant-app.com"), // Merchant App Link
        "com.merchant.app.deeplink.braintree" // Fallback deep link return url scheme
    )
    }

    // ONLY REQUIRED IF YOUR ACTIVITY LAUNCH MODE IS SINGLE_TOP
    override fun onNewIntent(intent: Intent) {
        super.onNewIntent(intent)
        handleReturnToApp(intent)
    }

    // ALL OTHER ACTIVITY LAUNCH MODES
    override fun onResume() {
        super.onResume()
        handleReturnToApp(intent)
    }

    private fun handleReturnToApp(intent: Intent) {
        // fetch stored PayPalPendingRequest.Success
        val pendingRequest: String = fetchPendingRequestFromPersistantStore()
        when (val paymentAuthResult = payPalLauncher.handleReturnToApp(
            pendingRequest = PayPalPendingRequest.Started(pendingRequest),
            intent = intent
        )) {
            is PayPalPaymentAuthResult.Success -> {
                completePayPalFlow(paymentAuthResult)
                // clear stored PayPalPendingRequest.Success
            }

            is PayPalPaymentAuthResult.NoResult -> {
                // user returned to app without completing PayPal flow, handle accordingly
            }

            is PayPalPaymentAuthResult.Failure -> {
                // handle error case
            }
        }
    }

    private fun completePayPalFlow(paymentAuthResult: PayPalPaymentAuthResult.Success) {
        payPalClient.tokenize(paymentAuthResult) { result ->
            when (result) {
                is PayPalResult.Success -> { /* handle result.nonce */ }
                is PayPalResult.Failure -> { /* handle result.error */ }
                is PayPalResult.Cancel -> { /* handle user canceled */ }
            }
        }
    }

    private fun onPayPalButtonClick() {
        val request = PayPalCheckoutRequest(
            amount = "12.34",
            hasUserLocationConsent = true
        )
        payPalClient.createPaymentAuthRequest(this, request) { paymentAuthRequest ->
            when (paymentAuthRequest) {
                is PayPalPaymentAuthRequest.ReadyToLaunch -> {
                    val pendingRequest = payPalLauncher.launch(this, paymentAuthRequest)
                    when (pendingRequest) {
                        is PayPalPendingRequest.Started -> {/* store pending request */ }
                        is PayPalPendingRequest.Failure -> { /* handle error */ }
                    }
                }
                is PayPalPaymentAuthRequest.Failure -> { /* handle paymentAuthRequest.error */ }
            }
        }
    }
}

Customizing One-time Payments

We can customize One-time Payments with the following features:

Integrating Contact Module

When customers purchase digital goods (such as gift cards, movies, and software) and check out with PayPal, merchants can ask the customers to input the digital good recipient's information (email and phone).

To integrate the Contact Module, use the code provided below

val request = PayPalCheckoutRequest()
        request.contactInformation = PayPalContactInformation("some@email.com", PayPalPhoneNumber("1", "1234567890"))

Integrating Shipping Module

The PayPal shipping module presents shipping details to a buyer during the PayPal flow. The merchant has several ways to determine how shipping addresses and shipping options are handled. The server-side shipping callbacks allow you to update the shipping and order amount information as buyers make changes on the PayPal review page.

Buyers can use the shipping module to specify the shipping address and shipping options on the PayPal paysheet. PayPal sends a callback to the merchant's URL with the updated shipping information (buyer’s address, state, city, country code, and zip code) using the server-side shipping callbacks. In response, the merchant can send PayPal the shipping options and updated order cost amounts.

To include Shipping Module in your integration, set the server side shipping callback URL as shown below. For more information, see the Integration code samples section, below.

request.shippingCallbackUrl = Uri.parse("merchant-url.com")

Integrating Pass Line-item Details

The items a buyer purchases can be passed to PayPal through a request.lineItems request. When a buyer checks out their purchase, PayPal displays these invoice-line-item details (item name, quantity, detailed description, price, etc.) for buyer verification. The details passed to PayPal are presented to the buyer:

To integrate Pass Line-item Details, set the code as shown below, and for more information, see the Integration code samples section

request.lineItems = listOf(PayPalLineItem(PayPalLineItemKind.CREDIT, "item name", "1", "1.99"))

Integrating Pass Buyer Identifier

A buyer's email address can be passed as the buyer identifier to PayPal through a PayPal request. During one-time checkout, PayPal uses this email address to prefill the buyer's PayPal login page. This streamlines and quickens the buyer authentication process for an effortless login. When you run PayPal in your app, as part of the request body, send the buyer's email address in the PayPalRequest.userAuthenticationEmail field. After a successful request, the passed email address is used to pre-populate the PayPal login page when the buyer pays with PayPal.

To include Pass Buyer Identifier in your integration, set the code as shown below. For more information, see the Integration code samples section below.

request.userAuthenticationEmail = "user@example.com"
        request.userPhoneNumber = PayPalPhoneNumber("1", "1234567890")

Integrating Pay Now or Continue

You can set User Action to control the message on the PayPal button at the bottom of the PayPal review page. There are two messaging options:

Pay Now

Use Pay Now for most PayPal flows. Pay Now streamlines checkout by using the payer's PayPal account information. For upstream placements (the button appears on the product or cart page), use the Pay Now User Action with the Shipping and Contact Modules to help the payer select shipping and payment details on the PayPal review page. For checkout presentment (button appears at checkout), payers can use PayPal to skip entering payment information. When a payer completes a Pay Now flow, they are returned to the merchant site. There, they will see a confirmation page with details about the transaction.

Continue

The Continue setting indicates that the payer will return to the merchant site to complete a transaction. Use this flow if the final amount will change after the payer returns to the merchant site. When the payer returns to the merchant site, they are presented with no more than one additional page to complete the transaction. When they complete a transaction, they see a confirmation page.

To integrate Pay Now or Continue, see the Integration code samples section below.

request.userAction = PayPalPaymentUserAction.USER_ACTION_COMMIT

Integrating App Switch

The App Switch initiative will enable PayPal users who have a PayPal installed on their phone to complete payments on the PayPal app when it is available.

In this experience the SDK will attempt to switch to the PayPal App after calling PayPalLauncher().launch if the PayPal App is installed and the user meets eligibility requirements. If the switch into the PayPal App cannot be completed, we will fall back to the default browser experience.

To integrate App Switch, see the Integration code samples section and follow the steps:

Get the SDK

Add the following in your app-level build.gradle:

dependencies {
    implementation 'com.braintreepayments.api:paypal:5.8.0'
}

Set Up App Links

In order to use the PayPal App Switch flow your application must be set up for App Links.

Set Fallback Deep Link Return URL

A buyer may uncheck the "Open supported links" setting on their Android device, preventing return to your app from the PayPal app via app links. You can provide a fallback deep link return URL scheme that will be used to return to your app from the PayPal app when app links are unavailable on the user's device. Follow these steps to configure the deep link return URL scheme in your AndroidManifest.xml and pass the deep link return URL in your PayPalClient constructor.

payPalClient = PayPalClient(
        context = this,
        authorization = "[TOKENIZATION_KEY or CLIENT_TOKEN]",
        appLinkReturnUrl = Uri.parse("https://merchant-app.com"), // Merchant App Link
        "com.merchant.app.deeplink.braintree" // Fallback deep link return url scheme
    )

Register App Link in Control Panel

Before using this feature, you must register your App Link domain in the Braintree Control Panel:

1. Log into your Control Panel (e.g. Sandbox, or Production).
2. Click on the gear icon in the top right corner. A drop-down menu will open.
3. Click Account Settings from the drop-down menu.
4. Scroll to the Payment Methods section.
5. Next to PayPal, click the Options link. This will take you to your linked PayPal Account(s) page.
6. Click the View Domain Names button. This will take you to the PayPal Domain Names page.
   • Note: If you have a single PayPal account, it will be at the bottom of the page. If you have multiple PayPal accounts, it will be at the top right of the page.
7. Click the + Add link on the top right of the page or scroll to the Specify Your Domain Names section.
8. In the text box enter your list of domain names separated by commas.
   • Note: The value you enter must match your fully qualified domain name exactly – including the "www." if applicable.
9. Click the Add Domain Names button.
10. If the domain registration was successful for all the domain names listed in the text box, a banner will display the text "Successfully added domains". The registered domain names will be displayed in alphabetical order under the + Add button.
11. If the registration was not successful for any of the domain names listed in the text box, a banner will display a list of domain names that failed qualified domain name validation along with their reasons for rejection. Any domain names that were successfully registered will be displayed in alphabetical order under the + Add button.
    • Note: You can re-enter the rejected domain names in the text area with the corrections applied.

Set App Link in SDK

You will need to use the following PayPalClient constructor to set your App Link:

val payPalClient =  PayPalClient(
  this, 
  "<#CLIENT_AUTHORIZATION#>",
  Uri.parse("https://demo-app.com/braintree-payments") // Merchant App Link
)

Invoking the PayPal App Switch flow

Opt in to the App Switch flow

Construct a PayPalVaultRequest or a PayPalCheckoutRequest with enablePayPalAppSwitch set to true and a userAuthenticationEmail included.

An example integration might look like this:

override fun onCreate(savedInstanceState: Bundle?) {
    payPalLauncher = PayPalLauncher()
}

// ONLY REQUIRED IF YOUR ACTIVITY LAUNCH MODE IS SINGLE_TOP
override fun onNewIntent(intent: Intent) {
    handleReturnToAppFromBrowser(intent)
}
    
// ALL OTHER ACTIVITY LAUNCH MODES 
override fun onResume() {
    handleReturnToAppFromBrowser(requireActivity().intent)
}


// one time checkout flows
val request = PayPalCheckoutRequest(amount, hasUserLocationConsent) 

request.userAuthenticationEmail = "sally@gmail.com"
request.enablePayPalAppSwitch = true

fun onPayPalButtonClick() {
    payPalClient.createPaymentAuthRequest(this, request) { paymentAuthRequest ->
        when(paymentAuthRequest) {
            is PayPalPaymentAuthRequest.ReadyToLaunch -> {
                val pendingRequest = payPalLauncher.launch(this@MyActivity, paymentAuthRequest)
                when(pendingRequest) {
                    is (PayPalPendingRequest.Started) { /* store pending request */ }
                    is (PayPalPendingRequest.Failure) { /* handle error */ }
                }
            }
            is PayPalPaymentAuthRequest.Failure -> { /* handle paymentAuthRequest.error */ }
        }
    }
}

fun handleReturnToAppFromBrowser(intent: Intent) {
    // fetch stored PayPalPendingRequest.Started 
    fetchPendingRequestFromPersistentStorage()?.let {
        when (val paymentAuthResult = payPalLauncher.handleReturnToAppFromBrowser(it, intent)) {               
            is PayPalPaymentAuthResult.Success -> {
                completePayPalFlow(paymentAuthResult)
                // clear stored PayPalPendingRequest.Started
            }
            is PayPalPaymentAuthResult.NoResult -> // user returned to app without completing PayPal flow, handle accordingly
        }
    }   
}
    
fun completePayPalFlow(paymentAuthResult: PayPalPaymentAuthResult) {
    payPalClient.tokenize(paymentAuthResult) { result ->
        when(result) {
            is PayPalResult.Success -> { /* handle result.nonce */ }
            is PayPalResult.Failure -> { /* handle result.error */ }
            is PayPalResult.Cancel -> { /* handle user canceled */ }
        }          
    }
}

Shipping address

Shipping addresses may or may not be collected during the Checkout with PayPal flow. However, if you choose to collect shipping addresses yourself, they can be passed along with the your server side Transaction.Sale call. Look at the Server-side page for more information.

Country support

PayPal is available to merchants in all countries that we support and to customers in 140+ countries.

Currency presentment

The currency of the transaction is presented to the customer in the Checkout with PayPal flow. We support all currencies that PayPal REST APIs support.

See the server-side section for details on charging a transaction in a specific currency.