PayPal

One-time Paymentsanchor

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.

Unlike Vaulted Payments, One-time payments do not provide the ability to store a customer's PayPal account in the Vault. If you want to store a customer's PayPal account within a Vault during One-time payments, view the Checkout with Vault integration guide.

PayPal's One-time Payments support:

  • Selecting or adding shipping addresses in the PayPal account
  • Selecting or adding funding instruments to the PayPal account
  • Two-factor authentication support (currently only for US, UK, CA, DE, AT, and AU)

Typical use cases for the One-time payments flow:

  • Checkout from Cart or Product pages
  • Checkout page replacement

Invoking the One-time Payments flowanchor

note

The examples here require version 3.90.0 or higher of the Braintree JavaScript SDK.

If you use the Braintree JavaScript SDK with the deprecated PayPal checkout.js library, review this migration guide to upgrade your integration.

To request a one-time payment, set flow to checkout and include amount and currency options in your createPayment call. The value of currency must match the value passed into loadPayPalSDK.

If intent is used, the value must match in both loadPayPalSDK and createPayment.

Use a createOrder function to create the payment resource:

  1. CallBack
  2. Promise
// Create a PayPal Checkout component.
  braintree.paypalCheckout.create({
    client: clientInstance
  }, function (paypalCheckoutErr, paypalCheckoutInstance) {
    // Base PayPal SDK script options
    var loadPayPalSDKOptions = {
      currency: 'USD',  // Must match the currency passed in with createPayment
      intent: 'capture' // Must match the intent passed in with createPayment
    }

    paypalCheckoutInstance.loadPayPalSDK(loadPayPalSDKOptions, function () {
      paypal.Buttons({
        fundingSource: paypal.FUNDING.PAYPAL,

        createOrder: function () {
          // Base payment request options for one-time payments
          var createPaymentRequestOptions = {
            flow: 'checkout', // Required
            amount: 10.00, // Required
            currency: 'USD', // Required, must match the currency passed in with loadPayPalSDK

            intent: 'capture', // Must match the intent passed in with loadPayPalSDK
          };

          return paypalCheckoutInstance.createPayment(createPaymentRequestOptions);
        },

        onApprove: function (data, actions) {
          return paypalCheckoutInstance.tokenizePayment(data, function (err, payload) {
            // Submit 'payload.nonce' to your server
          });
        },

        onCancel: function (data) {
          console.log('PayPal payment cancelled', JSON.stringify(data, 0, 2));
        },

        onError: function (err) {
          console.error('PayPal error', err);
        }
      }).render('#paypal-button').then(function () {
        // The PayPal button will be rendered in an html element with the ID
        // 'paypal-button'. This function will be called when the PayPal button
        // is set up and ready to be used
      });
    });
  });
});

Use the paypalCheckoutInstance in the onApprove function of the JavaScript SDKsetup method to tokenize the PayPal account. After the customer completes the consent flow and the PayPal pop-up closes, successful tokenization will return a payment method nonce.

Send the nonce to your server and use a Braintree server SDK to call Transaction.sale to create a transaction.

See our JavaScript PayPal client reference for more information on the options available in the Checkout with PayPal flow.

Customizing One-time Paymentsanchor

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 Moduleanchor

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). When you create the v2 order on the client side, specify the recipient email and phone number and pass it through createPayment(), a write-only field. This has to be specified in the client SDK when a merchant creates the v2 order, and Braintree Gateway updates create_payment_resource in the Gateway API to support these fields and send recipient information to PayPal Rest Orders v2 API on order creation.

To integrate the Contact Module, use the code provided below

  1. javascript
// Add recipientEmail and internationalPhone to the createPayment() request options
// inside the shippingAddressOverride
createPaymentRequestOptions.shippingAddressOverride = {
  recipientEmail: "example@email.com",
  internationalPhone: {
    countryCode: "1",
    nationalNumber: "2345678910",
  }
};

Integrating Shipping Moduleanchor

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.

  1. javascript
// Add shippingCallbackUrl createPayment() request options
createPaymentRequestOptions.shippingCallbackUrl = "https://www.example.com/"

Domain registrationanchor

In order to use server-side shipping callbacks with PayPal, you'll need to register any domains you plan to use as the shippingCallbackUrl. You can do this through the Braintree control panel using the instructions below. You will have to do this in both your sandbox and production environments.

Rules for domain namesanchor

A domain name:

  • Must not start with a scheme (e.g. "https://").

  • Must be between 4 and 255 characters.

  • Cannot contain spaces or wildcards (*).

  • Can consist of a top-level domain, a second-level domain, and 0 or more subdomains etc. a.b.example.com where example is the top-level domain, com is the second-level domain, and a and b are subdomains.

  • The top-level domain must consist of 2 to 63 letters.

  • Each subdomain and the second-level domain must consist of 1 to 63 alphanumeric characters and or hyphens.

  • Each subdomain and the second-level domain can not start or end with a hyphen.

  • The top-level domain, second-level domain, and the subdomains must be separated by a dot(.).

  • Can end with a trailing dot.

Sandbox environmentanchor

Register your sandbox domain name in the Braintree Control Panel:

  1. Log into your sandbox Control Panel

  2. Click on the gear icon in the top right corner

  3. Click Account Settings from the drop-down menu

  4. Scroll to the Payment Methods section

  5. Next to PayPal, click the Options link

  6. Client the View Domain Names button

  7. Enter the domain of your return page in the Specify Your Domain Names section.

  8. Click Add Domain Names button

Production environmentanchor

Register your production domain name in the Braintree Control Panel:

  1. Log into your production Control Panel

  2. Click on the gear icon in the top right corner

  3. Click Account Settings from the drop-down menu

  4. Scroll to the Payment Methods section

  5. Next to PayPal, click the Options link

  6. Client the View Domain Names button

  7. Enter the domain of your return page in the Specify Your Domain Names section.

  8. Click Add Domain Names button

Integrating Pass Line-item Detailsanchor

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

  1. javascript
// Add lineItems to createPayment() request options
createPaymentRequestOptions.lineItems = [
  {
    name: "Example item", // Item name. Maximum 127 characters.
    quantity: "1", // Number of units of the item purchased. This value must be a whole number and can't be negative or zero.
    unitAmount: "21.00", // Per-unit price of the item. Can include up to 2 decimal places. This value can't be negative or zero.
    kind: "debit", // Indicates whether the line item is a debit (sale) or credit (refund) to the customer. Accepted values: `debit` and `credit`.
    unitTaxAmount: "7.00", //Per-unit tax price of the item. Can include up to 2 decimal places. This value can't be negative or zero.
    description: "Example description", // Item description.Maximum 127 characters.
    productCode: "Example product code", // Product or UPC code for the item. Maximum 127 characters.
  }
]

Integrating Pass Buyer Identifieranchor

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

  1. javascript
// Add userAuthenticationEmail to createPayment() request options
createPaymentRequestOptions.userAuthenticationEmail = "email@example.com"

Integrating Pay Now or Continueanchor

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.

  1. javascript:v3
// Add commit to loadPayPalSDK options
loadPayPalSDKOptions.commit = false

Integrating App Switchanchor

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

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

  1. javascript
// Add return and cancel URLs to createPayment() request options
createPaymentRequestOptions.returnUrl = 'example.com/return'
createPaymentRequestOptions.cancelUrl = 'example.com/cancel'

const button = paypal
  .Buttons({
    fundingSource: paypal.FUNDING.PAYPAL,

    // Sets up the transaction when a payment button is clicked
    appSwitchWhenAvailable: true, // Indicator to trigger app switch

    createOrder: createOrderCallback, // Set up in main the one-time payments example
    onApprove: onApproveCallback, // Set up in main the one-time payments example
    onError: onErrorCallback, // Set up in main the one-time payments example
  });

// If you support app switch, depending on the browser the buyer may end up in a new tab
// To trigger completion of the flow, execute the code below after re-instantiating buttons
if (button.hasReturned()) {
  button.resume();
} else {
  button.render("#paypal-button-container");
}

Shipping addressanchor

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 supportanchor

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

Currency presentmentanchor

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.


Next Page: Recurring Payments →