PayPal Advanced Options

Payee

By passing the payeeId or payeeEmail parameter with PayPal transaction sale requests, you can dynamically route PayPal payments to different PayPal accounts that you own. This is useful if you have a multi-currency setup with separate PayPal accounts, or if you have different accounts for different parts of your business.

How it works

Normal payment flow without specifying a payee

When processing PayPal payments, Braintree uses your PayPal business account linked in your Braintree Control Panel. This ensures your PayPal account is correctly configured for smooth processing with Braintree. For a transaction, you typically pass the paymentMethodNonce or paymentMethodToken representing the customer's PayPal account, and Braintree sends that payment to the PayPal account linked in your Control Panel.

Java

TransactionRequest request = new TransactionRequest()
    .amount(new BigDecimal("10.00"))
    .paymentMethodNonce(nonceFromTheClient);
Result<transaction> result = gateway.transaction().sale(request); // e.g. 594019

Payment flow using payee

Braintree has the ability to change the receiving PayPal account dynamically in the transaction API call. When you specify a payeeId or payeeEmail, that PayPal account gets all the funds for the transaction, as if it was processed entirely on that account. The PayPal account linked in your Braintree Control Panel does not see this transaction in its account or reporting. See PayPal's documentation on payee.

Payee ID

The payeeId represents the PayPal account identifier for the payee. It can be found in the PayPal business account settings under Merchant account ID. Both payeeIdand payeeEmail produce the same behavior, but payeeId may be preferable since it cannot be changed in the PayPal business account.

Java

TransactionRequest request = new TransactionRequest()
    .amount(new BigDecimal("10.00"))
    .paymentMethodNonce(nonceFromTheClient)
    .options()
    .paypal()
    .payeeId("PAYPAL_MERCHANT_ID_FOR_RECEIVING_ACCOUNT")
    .done()
    .done();
Result<transaction> result = gateway.transaction().sale(request);

Note

When creating a transaction with the paymentMethodNonce() , the options-paypal-payeeId() parameter can only be used if the nonce represents a vaulted PayPal account. When creating a transaction with the paymentMethodToken() , the options-paypal-payeeId() parameter cannot be used if the payment method represents a PayPal Order.

Payee email

The payeeEmail represents the PayPal account email for the payee. It can be found in the PayPal business account settings under Email. Both payeeId and payeeEmail produce the same behavior, but payeeEmail has none of the restrictions associated with payeeId above.

Java

TransactionRequest request = new TransactionRequest()
    .amount(new BigDecimal("10.00"))
    .paymentMethodNonce(nonceFromTheClient)
    .options()
    .paypal()
    .payeeEmail("PRIMARY_EMAIL_ADDRESS_FOR_RECEIVING_ACCOUNT")
    .done()
    .done();
Result<transaction> result = gateway.transaction().sale(request);

Setup

PayPal permissions

Depending on your processing setup, your PayPal accounts may need some additional configuration to support payeeId and payeeEmail.

Multi-currency configuration

Currency is not controlled by the payeeId nor payeeEmail parameter. In order to set a specific currency for the transaction, you will need to use a Braintree merchantAccountId that's been set up for that currency. Be sure the merchantAccountId you specify also has PayPal payments enabled.

Java

TransactionRequest request = new TransactionRequest()
    .amount(new BigDecimal("10.00"))
    .merchantAccountId("merchantNameCURRENCYCODE")
    .paymentMethodNonce(nonceFromTheClient)
    .options()
    .paypal()
    .payeeId("PAYPAL_MERCHANT_ID_FOR_RECEIVING_ACCOUNT")
    .done()
    .done();
Result<transaction> result = gateway.transaction().sale(request);

Refunds

Refunds are processed the same way as a normal refund via Braintree, with no reference to the payeeId or payeeEmail. Braintree will automatically withdraw the funds from the same PayPal account that received them from the original transaction.

Reporting in the Braintree Control Panel

The payeeId and payeeEmail parameters are not exposed in transaction reporting in the Braintree Control Panel. If you need to report on these transactions separately, let us know and we can set up a unique merchantAccountId for each payeeId and payeeEmail you plan to use.