One-time Payments

iOS v6

• Current Braintree SDKs
• Android v5
• iOS v6
• JavaScript v3
• Previous Versions
• Android v4
• 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.

Invoking the One-time Payments flow

Use BTPayPalClient and BTPayPalCheckoutRequest to start the process. A transaction amount is required to invoke the one-time payment flow. An example integration might look similar to this:

import BraintreePayPal

    class MyViewController: UIViewController {
    var apiClient: BTAPIClient?
    var payPalClient: BTPayPalClient?

    override func viewDidLoad() {
        super.viewDidLoad()
        apiClient = BTAPIClient(authorization: "<#CLIENT_AUTHORIZATION#>")!
        payPalClient = BTPayPalClient(apiClient: apiClient)
    }

    func startCheckout() {
        // Specify the transaction amount here. "2.32" is used in this example.
        let request = BTPayPalCheckoutRequest(amount: "2.32")
        request.currencyCode = "USD" // Optional; see BTPayPalCheckoutRequest for more options
        payPalClient.tokenize(request) { (tokenizedPayPalAccount, error) in
            if let tokenizedPayPalAccount = tokenizedPayPalAccount {
                print("Got a nonce: \(tokenizedPayPalAccount.nonce)")
                // Access additional information
                let email = tokenizedPayPalAccount.email
                let firstName = tokenizedPayPalAccount.firstName
                let lastName = tokenizedPayPalAccount.lastName
                let phone = tokenizedPayPalAccount.phone
                // See BTPostalAddress for details
                let billingAddress = tokenizedPayPalAccount.billingAddress
                let shippingAddress = tokenizedPayPalAccount.shippingAddress
            } else if let error = error {
                // Handle error here...
            } else {
                // Buyer canceled payment approval
            }
        }
      }
    }

Customizing One-time Payments

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

• Contact Module
• Shipping Module
• Pass Buyer Identifier
• Pass Line-item Details
• Pay Now or Continue
• App Switch

Integrating Contact Module

The Contact Module helps buyers to view and update the email address and phone number shared with merchants for a specific order. This feature gives buyers more control and flexibility, especially useful for gift orders, where alternate contact details may be needed.

Buyer benefits

The Contact Module offers buyers a personalized and convenient experience by allowing them to customize contact details for each transaction without updating information outside the checkout process.

This feature is currently available in the US only.

Merchant benefits

The Contact Module offers buyers a personalized and convenient experience by allowing them to customize contact details for each transaction without updating information outside the checkout process.

• Hide contact info: This setting is enabled by default. Buyers do not see any contact information during checkout.
  • To hide contact information from buyers during checkout, a merchant can either set .noContactInformation or omit the request.contactPreference field.
• Display editable contact info: Buyers can see and edit their contact information.
  • To allow buyers to edit their contact information during checkout, the merchant can set .updateContactInformation.
  • When this option is enabled, buyers can update their email addresses and phone numbers in PayPal. Merchants will then receive the most current contact information and should use this updated data for all communications with buyers.
  • Buyers cannot set preferences for email and phone numbers individually; both can be edited at the same time when this option is activated.
• Display read only contact info: Buyers can see their contact information but can't edit it.
  • To display contact information to buyers without allowing edits, the merchant should use the .retainContactInformation setting.
  • If only one contact field—either email or phone—is provided, PayPal will display just that field and assume it's the primary method of communication.
  • If .retainContactInformation is set without contact details, PayPal defaults to .updateContactInformation and hides all contact information from the buyer.

To integrate the Contact Module, use the code provided below

let request = BTPayPalCheckoutRequest()
            request.contactInformation = BTContactInformation(
            recipientEmail: "some@email.com",
            recipientPhoneNumber: .init(countryCode: "52", nationalNumber: "123456789")
request.contactPreference = .retainContactInformation

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 = URL(string: "www.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:

• On the PayPal review page during the Pay with PayPal flow.
• In the post-purchase email sent to the buyer about their payment transaction.
• In the buyer's PayPal account Activity > Transactions > All transactions section.

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

let request = BTPayPalCheckoutRequest(amount: "2.32")
  request.currencyCode = "USD" // Optional; see BTPayPalCheckoutRequest for more options

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 BTPayPalRequest.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.

// Buyer identifiers
  request.userAuthenticationEmail = "user@example.com"
  request.userPhoneNumber = BTPayPalPhoneNumber(countryCode: "1", nationalNumber: "4087463271")
  // Line item details
  request.lineItems = [BTPayPalLineItem(quantity: "1", unitAmount: "10", name: "item-name", kind: .debit)]

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: The payer will complete the transaction on the PayPal review page.
• Continue: The payer will return to the merchant site to complete the transaction.

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 = .payNow

Integrating App Switch

App Switch enables PayPal users who have a PayPal app installed on their phone to complete payment on the app when it is available.

In this experience the SDK will attempt to switch to the PayPal App after calling tokenize 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 ASWebAuthenticationSession experience.

To integrate App Switch, follow these seps:

Get the SDK

The PayPal App Switch is part of the BraintreePayPal module in the Braintree SDK. This module can be pulled into your app via all of the currently supported package managers.

Cocoapods

In your Podfile, add the dependency for the PayPal Mobile Checkout module:

pod 'Braintree/PayPal'

Swift Package Manager

Include the BraintreeCore, BraintreePayPal, and PayPalDataCollector frameworks.

Carthage

Include the BraintreeCore, BraintreePayPal and PayPalDataCollector frameworks.

Allowlist PayPal URL Scheme

You must add the following to the queries schemes allowlist in your app's info.plist:

<key>LSApplicationQueriesSchemes</key>
<array>
  <string>paypal-app-switch-checkout</string>
</array>

Set Up Universal Links

In order to use the PayPal App Switch flow your application must be set up for Universal Links. You will need to use a custom path dedicated to Braintree app switch returns. This URL must also be added to your app association file with wildcards allowed to ensure we receive the expected data on return.

{
  "applinks": {
    "details": [
      {
        "appID": "com.your-app-id",
        "paths": [
          "/braintree-payments/*"
        ]
      }
    ]
  }
}

let apiClient = BTAPIClient(authorization: <#CLIENT_AUTHORIZATION#>)
let payPalClient = BTPayPalClient(
  apiClient: apiClient, // required
  universalLink: URL(string: "https://my-universal-link.com/braintree-payments")! // required
)

.onOpenURL { url in
  BTAppContextSwitcher.sharedInstance.handleOpen(url)
}

func scene(_ scene: UIScene, continue userActivity: NSUserActivity) {
  if let returnURL = userActivity.webpageURL, returnURL.path.contains("/my-dedicated-braintree-path") {
    BTAppContextSwitcher.sharedInstance.handleOpen(returnURL)
  }
}

func application(_ application: UIApplication, continue userActivity: NSUserActivity, restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void) -> Bool {
  if let returnURL = userActivity.webpageURL, returnURL.path.contains("/my-dedicated-braintree-path") {
    BTAppContextSwitcher.sharedInstance.handleOpen(returnURL)
  }
}

import UIKit
import BraintreePayPal

class MyViewController: UIViewController {
  var apiClient: BTAPIClient!
  var payPalClient: BTPayPalClient!
  let payPalButton = UIButton(type: .system)

  override func viewDidLoad() {
    super.viewDidLoad()
    apiClient = BTAPIClient(authorization: <#CLIENT_AUTHORIZATION#>)
    payPalClient = BTPayPalClient(
      apiClient: apiClient, 
      universalLink: universalLink: URL(string: "https://my-universal-link.com/braintree-payments")! // required for this flow
    )
    setUpButton()
  }

   private func setUpButton() {
    payPalButton.translatesAutoresizingMaskIntoConstraints = false
    payPalButton.setTitle("PayPal Checkout", for: .normal)
    payPalButton.setTitleColor(.blue, for: .normal)
    payPalButton.addTarget(self, action: #selector(payPalButtonTapped), for: .touchUpInside)
    view.addSubview(payPalButton)
  }

  @objc func payPalButtonTapped(_ sender: UIButton) {
    sender.isEnabled = false

    // one time checkout flows
    let request = BTPayPalCheckoutRequest(
      amount: amount
      userAuthenticationEmail: "sally@gmail.com",
      enablePayPalAppSwitch: true
    )
    
    // userAuthenticationEmail and enablePayPalAppSwitch are required for this flow
    // Configure other values on 'request' as needed.

    payPalClient.tokenize(request) { payPalNonce, error in
      sender.isEnabled = true
      if let payPalNonce { 
        // send payPalNonce.nonce to server 
      } else { 
        // handle error
      }
    }
  }
}

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.