PayPal (with Braintree) is a payment provider allowing customers to pay using payment methods saved to their PayPal account. This section is intended to help you implement PayPal (with Braintree) based on your preferred integration workflow.

📘

Note

PayPal (with Braintree) is different from PayPal in the following ways:

• PayPal (with Braintree) allows for customer-not-present (also known as "merchant-initiated") transactions via a saved token, whereas standard PayPal only supports customer-present transactions.
• PayPal (with Braintree) only supports the individual iframe integration method and PayPal supports the multi-iframe, individual iframe, and custom redirect integration methods.
• PayPal (with Braintree supports the "Continue button" and "Checkout page" payment flows while PayPal only supports a "Checkout page" flow.
• PayPal (with Braintree) only supports the AUD, CAD, EUR, GBP, and USD currencies; PayPal supports the AUD, BRL, CAD, CHF, CZK, DKK, EUR, GBP, HKD, HUF, ILS, INR, JPY, MXN, MYR, NOK, NZD, PLN, RUB, SEK, SGD, THB, TWD, and USD currencies.
• For a checkout page flow, the required fields for the two payment methods are the same. However, PayPal (with Braintree) requires additional parameters for either the "Continue button" payment flow or the merchant-initiated transactions.

Services and compatibility

Configuration

In order to use PayPal (with Braintree) with your merchant account, you must first work with integrations to add it to your account.

In order to configure your account for use with PayPal (with Braintree), you will need the following:

• A login for the PayPal developer site.
• A Braintree account.
• Have PayPal accounts ready for your different markets.

After you have the above and have worked with Integrations Support to get your PayPal ClientID, you are ready to follow the configuration steps.

Prerequisites

In order to configure your account for use with PayPal (with Braintree), you need the following:

• PayPal Developer Account
• Braintree Account

Configuration Steps

To configure PayPal (with Braintree), you must complete the following set of steps:

• Link PayPal account to Braintree environment

Link PayPal account to Braintree environment

Integration support helps you complete this step for the Sandbox environment. However, you must do the configuration for your production environment.

Follow these steps to link your PayPal account:

1. Navigate to the Braintree Environment

   Go to the Braintree Environment and log in.

2. Get the API keys

   Go to Settings > API.

   The system displays all the keys.

3. Locate the Merchant ID

   The Merchant ID displays at the bottom of the Keys page.

   Make note of this ID because you will use this value in Step 7.

4. Navigate to Processing Options

   Go back to the home screen.

   Go to Settings > Processing > Processing Options.

5. Configure Options

   In the PayPal area, click Options.

   You are prompted to log in with your PayPal account credentials.

   After successfully logging in, the PayPal Accounts page displays. Braintree retrieves the necessary clientID, PayPal email, and Client Secret.

6. Link One or More PayPal Accounts

   Merchant account IDs are created and added to the merchant account by PayPal after the merchant has signed all the necessary PayPal documentation. Contact PayPal and the merchant to arrange the creation of merchant account IDs. Follow this same process when you need to add new payment methods to the merchant account.

   a. Click the +Link New PayPal Account button.

   b. Provide PayPal account details and URLs for Privacy Policy and Terms and Conditions.

   c. In the new account row (the one that does not show any merchant accounts), click Edit.

   d. Start typing the merchant account name so that the selector displays a list of all potential matches.

   e. If you want to enable PayPal Disputes for this account, select Manage PayPal Disputes in the Braintree Control Panel.

   📘

   Note

   If you link a merchant account here, any previous links made to that merchant account are removed.

7. Add Merchant Account IDs for Each Currency to Support

   To support multiple currencies, you must have a different merchant account ID for each currency. Work with your PayPal account representative to arrange this.

Token migration

It is possible to migrate your existing APM tokens to Nexio for recurring transactions.

Migration from PayPal

If you do not have an existing Braintree account, and you want to take advantage of recurring transactions with PayPal (with Braintree), you must migrate your PayPal tokens.

1. Contact PayPal.
2. Request a download of your existing PayPal subscription agreement IDs.
3. Contact Braintree and provide the downloaded file for importing the tokens.
4. If migrating the tokens to the Nexio vault, continue with the next set of steps.

Migration from PayPal (with Braintree)

If you have migrated your tokens from PayPal (or have Braintree tokens) to Braintree and you want to migrate those tokens to the Nexio vault for recurring transactions, complete the following steps:

1. Contact Braintree.
2. Request a download of your existing PayPal (with Braintree) Braintree IDs.
   The following fields can be included in the file as needed. Nexio recommends that you include as much information as possible:
   apmToken, customerRef, email, shopperReference, currencyCode, firstName, lastName, orderNumber, shipToAddressOne, shipToAddressTwo, shipToCity, shipToCountry, shipToPostal, shipToState, billToAddressOne, billToAddressTwo, billToCity, billToCountry, billToPostal, billToState, merchantId, originalRefNumber
3. Contact Integrations Support to let them know that you are ready to migrate your tokens from PayPal (with Braintree). They provide you with information about the next steps to take for sending the file.

Required fields

The following table shows the required and optional fields for PayPal (with Braintree) transactions in the Create APM one-time-use token request.

Example requests

The following are example one-time-use token requests for PayPal (with Braintree).

curl -X POST https://api.nexiopaysandbox.com/apm/v3/token \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic [Base64_encoded_login]'
  -d '{
  "data": {
    "amount": 4.00,
    "currency": "USD",
    "paymentMethod": "braintreePayPal",
    "customer": {
      "orderNumber": "12345678",
      "firstName": "John",
      "lastName": "Doe",
      "email": "[email protected]"
    }
  }
}'

curl -X POST https://api.nexiopaysandbox.com/apm/v3/token \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic [Base64_encoded_login]'
  -d '{
  "data": {
    "amount": 4.00,
    "currency": "USD",
    "paymentMethod": "braintreePayPal",
    "customer": {
      "orderNumber": "12345678"
    }
  },
  "processingOptions": {
    "doNotProcessPayment": true
  }
}'

curl -X POST https://api.nexiopaysandbox.com/apm/v3/token \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic [Base64_encoded_login]'
  -d '{
  "data": {
    "amount": 4.00,
    "currency": "USD",
    "paymentMethod": "braintreePayPal",
    "customer": {
      "orderNumber": "12345678",
      "customerRef": "RP006",
      "firstName": "John",
      "lastName": "Doe",
      "email": "[email protected]"
    }
  },
  "processingOptions": {
    "saveRecurringToken": true
  }
}'

{
  "expiration": "2018-09-18T15:43:05.664Z",
  "token": "830d36f6-a5e3-4455-9600-3a55b63e2fc2",
  "asyncTraceId": "830d36f6-a5e3-4455-9600-3a55b63e2fc2",
  "expressIFrameUrl": "https://www.api.nexiopaysandbox.com/v3?token=830d36f6-a5e3-4455-9600-3a55b63e2fc2",
  "redirectUrls": [],
  "buttonIFrameUrls": [
    {
      "paymentMethod": "braintreePayPal",
      "url": "https://api.nexiopaysandbox.com/apm/v3?token=830d36f6-a5e3-4455-9600-3a55b63e2fc2&paymentMethod=braintreePayPal"
    },
    {
      "paymentMethod": "applePayCyberSource",
      "url": "https://api.nexiopaysandbox.com/apm/v3?token=830d36f6-a5e3-4455-9600-3a55b63e2fc2&paymentMethod=applePayCyberSource"
    },
    {
      "paymentMethod": "nihaoPayWechatPay",
      "url": "https://api.nexiopaysandbox.com/apm/v3?token=830d36f6-a5e3-4455-9600-3a55b63e2fc2&paymentMethod=nihaoPayWechatPay"
    }
  ]
}

For the individual iframe option: You use the buttonIFrameUrls.url of the braintreePayPal APM for the transaction.

For the multi iframe integration method: Not supported for this payment method.

For the custom redirect option: Not supported for this payment method.

Transaction types and integration methods

Regardless of the integration method workflow you implement, consumers are redirected to PayPal (with Braintree) to complete their transactions.

Nexio supports the following transaction types for PayPal (with Braintree):

• Auth Only
• Merchant-initiated (recurring)
• Sale
  • In an individual iframe
    
• Void
• Capture
• Refund

PayPal (with Braintree) also supports Pay Later messaging. For details, see the Pay Later messaging topic.

PayPal (with Braintree) payment flow

The following show the general flows for a customer accessing a merchant site through payment using PayPal with Braintree, either from the cart (Continue button flow) or the checkout page (Checkout page flow).

Continue button flow

The "Continue button" flow provides a way for merchants to increase checkout conversion by moving the payment step to the shopping cart instead of just at checkout.

Customer adds item to shopping cart and clicks PayPal button to pay

1. The customer adds one or more items to a shopping cart.

2. The customer goes to that cart and the order amount displays, along with a Pay with PayPal button.

3. If the customer clicks that button, they are asked to log in to PayPal and to select their payment options and address information.

4. After making those selections, the customer clicks an Agree & Continue button.

5. The customer is redirected to a Confirm/Place Order page. Based on the address selected, they see tax and shipping costs for this order and are asked to confirm payment.

6. The customer is redirected to a Receipt page.

Customer adds item to cart and clicks Checkout button

1. The customer adds one or more items to a shopping cart.

2. The customer goes to that cart and the order amount displays, along with a Pay with PayPal button.

3. Customer instead clicks the Checkout button and is redirected to a Checkout page with all available payment options (potentially including PayPal). Customer address information is collected (or retrieved) and is used to generate tax and shipping costs.

4. If the customer clicks the PayPal button here, they are asked to log in to PayPal and to select their payment options.

   If the customer clicks a different APM button, the process for that specific APM continues through to confirming the payment options.

   If the customer submits payment for card or ACH, the process continues based on the entered payment options.

5. The customer is redirected to a Receipt page.

Checkout page flow

The "Checkout page" flow is the traditional payment flow for payment methods, where the options for payment are all presented on the Checkout page for the customer to choose from.

Customer adds item to cart and clicks Checkout button

1. The customer adds one or more items to a shopping cart.

2. The customer goes to that cart, the order amount displays, along with a Checkout button.

3. Customer clicks the Checkout button and is redirected to a Checkout page with all available payment options (potentially including PayPal (with Braintree)). Customer address information is collected (or retrieved) and is used to generate tax and shipping costs.

4. If the customer clicks the PayPal (with Braintree) button, they are asked to log in to PayPal and to select their payment options.

   If the customer clicks a different APM button, the process for that specific APM continues through to confirming the payment options.

   If the customer submits payment for card or ACH, the process continues based on the entered payment options.

5. The customer is redirected to a Receipt page.

Merchant-initiated transactions for PayPal (with Braintree)

You may want to support merchant-initiated transactions through PayPal (with Braintree) for your customers, such as for recurring transactions.

For a tutorial about how to implement this, see the Run a merchant-initiated recurring transaction topic.

Testing data

For testing information and data, see Testing in the PayPal Braintree Developer Documentation.

Response handling

In the one-time-use token request, PayPal (with Braintree) gets returned in the paymentMethod parameter as braintreePayPal.

When implementing merchant-initiated recurring transactions, you need to save the apm.token parameter from the response. For more information, see Run a merchant-initiated recurring transaction.

Nexio responds with transaction results in event messages. In addition, if your merchant account is configured to receive webhooks, Nexio provides responses to the webhook URLs that have been registered. For further explanation of the webhook event types, see the webhook Event types table.

For PayPal (with Braintree), these are the possible webhook event types:

• TRANSACTION_AUTHORIZED
• TRANSACTION_CAPTURED
• TRANSACTION_REFUNDED
• TRANSACTION_SETTLED
• TRANSACTION_VOIDED

For information about how to run each of the integration workflows, see Transaction types and integration methods above.

Status workflows

The status of a successful transaction with PayPal (with Braintree) varies, depending on the options you choose.

* Pending status displays as "authorized" or "AUTHORIZED" in the Nexio Dashboard; it displays as 10, meaning "authorized", in the response when querying transactions (for more information about transactionStatus, see the table).

Next steps

Now, you are ready to get started with running transactions:

• Run a sale transaction
• Run a merchant-initiated recurring transaction

If you have any additional questions or feedback, see Contact us.