PayPal (with Braintree) integration guide

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

Services and compatibility

Payment method gateway namePayPal
Supported transaction types
Supported integration methods
Supported processing currencies
  • AUD
  • CAD
  • EUR
  • GBP
  • USD
Webhook event types
  • TRANSACTION_AUTHORIZED
  • TRANSACTION_CAPTURED
  • TRANSACTION_REFUNDED
  • TRANSACTION_SETTLED
  • TRANSACTION_VOIDED

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:

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

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.

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 or the checkout page.

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.

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.

To allow for merchant-initiated transactions, follow the steps below.

  1. Configure Your Account

    Configure your Nexio account to use PayPal (with Braintree). If you need to have this done, contact Integration Support.

  2. Create Necessary Payment Flow Pages

    Complete step 2 in Button Iframe URLs to create any needed pages.

  3. Configure Pages

    Complete step 3 in Button Iframe URLs to create a Shopping Cart page. Include the URL from the "braintreePayPal" paymentMethod to add that payment option to the checkout page.

    IMPORTANT: Make sure to include the processingOptions.saveRecurringToken parameter in the body of your one-time-use token request and set it equal to true.

    Complete step 4 in Button Iframe URLs to create a Confirm/Place Order page.

    Complete step 5 in Button Iframe URLs to create a Checkout page. Include the URL from the "braintreePayPal" paymentMethod to add that payment option to the checkout page.

    IMPORTANT: Make sure to include the processingOptions.saveRecurringToken parameter in the body of your one-time-use token request and set it equal to true.

  4. Shopper Completes Payment and You Save APM Token

    If the customer clicks the PayPal (through Braintree) button as the payment method (steps 6-7 in Button Iframe URLs), then, in the event posted to your window, the response includes an apm.token parameter.

    Save the apm.token value somewhere in order to use it again (probably similar to how you save TokenEx tokens already).

    WARNING: This apm.token value cannot be retrieved through the API at any other time.

    By way of example, a response may look like the following. Notice the apm object and its token:

    Example Braintree PayPal Sale Response
    {
      "id": "eyJuYW1lIjoiYnJhaW50cmVlUGF5UGFsIiwibWVyY2hhbnRJZCI6IjEwMTAzOSIsInJlZk51bWJlciI6InA0NXljeWQ5IiwicmFuZG9tIjowLCJjdXJyZW5jeSI6InVzZCJ9",
      "merchantId": "101039",
      "transactionDate": "2021-07-13T22:12:56.780Z",
      "transactionStatus": "settled",
      "amount": 4,
      "transactionType": "sale",
      "currency": "USD",
      "gatewayResponse": {
        "result": "settling",
        "refNumber": "p45ycyd9",
        "gatewayName": "braintreePayPal",
        "message": "settling"
      },
      "data": {
        "amount": 4,
        "currency": "USD",
        "settlementCurrency": "USD",
        "customer": {
          "lastName": "Test",
          "shipToAddressOne": "123 Ship St",
          "shipToPhone": "5033335678",
          "orderNumber": "1151057c04214a688c382ee1f666e76e",
          "shipToCountry": "US",
          "shipToAddressTwo": "Warehouse 456",
          "billToState": "UT",
          "billToCity": "Testerville",
          "shipToPostal": "67890",
          "firstName": "Nexio",
          "shipToCity": "Shipperville",
          "billToAddressOne": "123 Test St",
          "billToCountry": "US",
          "billToPostal": "12345",
          "billToAddressTwo": "Suite 123",
          "billToPhone": "8015551234",
          "email": "[email protected]",
          "shipToState": "OR"
        }
      },
      "apm": {
        "token": "apm:66b742ee-7abc-4e36-81ea-0a26d23d2822"
      }
    }
    

  5. Run Merchant-Initiated Payment

    Later, when you are ready to initiate another transaction for the customer without their input, use that stored apm.token value from step 4 above to run a payment.

    Send a POST request to the APM Run Transaction endpoint, as in the following example. Notice the inclusion of the apm object with its token in the body of the request:

    Example Merchant-Initiated Request
    curl -X POST https://api.nexiopaysandbox.com/apm/v3/process \
      -H 'Content-Type: application/json' \
      -H 'Accept: application/json' \
      -H 'Authorization: Basic [Base64_encoded_login]'
      -d '{
      "isAuthOnly": false,
      "apm": {
        "token": "apm:66b742ee-7abc-4e36-81ea-0a26d23d2822"
      },
      "data": {
        "currency":"USD",
        "amount": 9.95,
        "description": "test purchase",
        "customer": {
          "orderNumber": "sdgsrgrsb",
          "firstName":"Joe",
          "lastName":"Brown",
          "billToAddressOne": "123 Street",
          "billToAddressTwo": "Box 232",
          "billToCity": "Narnia",
          "billToState": "TX",
          "billToPostal": "46632",
          "billToCountry": "USA"
        }
      }
    }'
    

    You will then get a response, which will be similar to other payment responses that you normally get. On success, the response looks similar to the following:

    Example 200 Response
    {
      "id": "eyJuYW1lIjoiYnJhaW50cmVlUGF5UGFsIiwibWVyY2hhbnRJZCI6IjEwMTAzOSIsInJlZk51bWJlciI6Ims3ZDN6cDJlIiwicmFuZG9tIjowLCJjdXJyZW5jeSI6InVzZCJ9",
      "merchantId": "101039",
      "transactionDate": "2021-07-13T22:14:03.514Z",
      "transactionStatus": "settled",
      "amount": 9.95,
      "transactionType": "sale",
      "currency": "USD",
      "gatewayResponse": {
        "result": "settling",
        "refNumber": "k7d3zp2e",
        "gatewayName": "braintreePayPal",
        "message": "settling"
      },
      "data": {
        "amount": 88,
        "currency": "USD",
        "settlementCurrency": "USD",
        "customer": {
          "orderNumber": "sdgsrgrsb",
          "firstName": "Joe",
          "lastName": "Brown",
          "billToAddressOne": "123 Street",
          "billToAddressTwo": "Box 232",
          "billToCity": "Narnia",
          "billToState": "TX",
          "billToPostal": "46632",
          "billToCountry": "USA"
        }
      }
    }
    

Required fields

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

FieldRequired?Description
data.amountYThe transaction amount.
data.currencyYThe three-character ISO currency code for the transaction.
data.customer.orderNumberYThe order number.
data.customer.firstNameConditionalThe customer's first name, as it appears on the card. This parameter is not required for a 'continue button' payment flow.
data.customer.lastNameConditionalThe customer's last name, as it appears on the card. This parameter is not required for a 'continue button' payment flow.
data.customer.emailConditionalThe customer's email address. This parameter is not required for a 'continue button' payment flow.
data.customer.customerRefConditionalFor recurring transactions, you must include a value for this parameter in the request.
customerRedirectUrlConditionalThe URL to which the customer will be redirected after completing their payment. The customer will be sent here upon successful or failed payment. This URL must use the HTTPS protocol. Required if you intend to use Nexio’s redirectUrls with your own buttons.
processingOptions.doNotProcessPaymentConditionalIf you want to set up a 'continue button' flow, such as on a shopping cart page before getting to the checkout page, include this parameter in the body of your one-time-use token request and set it equal to true.

For this flow, you do not have to include the following parameters: data.customer.firstName, data.customer.lastName, and data.customer.email. These fields are returned from PayPal in the response for this flow.
processingOptions.saveRecurringTokenConditionalIf you want to save a recurring token for a future merchant-initiated transaction, include this parameter in the body of your one-time-use token request and set it equal to true. In addition, if the amount to process on the Confirm/Place Order page will be more than the current amount for a 'continue button' payment flow, you must include this parameter so that you can send the payment request (for example, if adding tax and shipping costs to the amount).
data.paymentMethodOptionalThe identifier for the alternative payment method. Use this parameter when you want to only return the PayPal (with Braintree) iframe button URL or the PayPal (with Braintree) redirect URL (rather than data for all payment methods associated with the account).

The value to use is braintreePayPal.

Transaction types and implementation methods

Regardless of the implementation workflow you implement, consumers will be redirected to PayPal (with Braintree) to complete their transactions.

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

Testing data

For testing data, see PayPal Test Accounts.

Response handling

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

Nexio responds with transaction results in one of the following ways, depending on your integration workflow:

  • Event messages: This applies to integrations that do not pass a customerRedirectUrl in the request.
  • Response fields in the URL: This applies to integrations that do provide a customerRedirectUrl in the request.

In addition to one of the above, 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.

  • Webhook notification: 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 above.

Status workflows

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

Sale

When isAuthOnly is false, successful sale transactions will have the following statuses:

  • pending (called "authorized" when querying transactions and in Nexio Dashboard)
  • settled

When isAuthOnly is true, successful sale transactions will have the following statuses:

  • authOnlyPending
  • authOnly

Capture

Successful capture transactions will have the following status:

  • settled

Refund

Successful refund transactions will have the following status:

  • settled

Next steps

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

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


Did this page help you?