PayPal Advanced Options

Payee

By passing the payee_id or payee_email 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 payment_method_nonce or payment_method_token representing the customer's PayPal account, and Braintree sends that payment to the PayPal account linked in your Control Panel.

Ruby

result = gateway.transaction.sale(
  :amount => "10.00",
  :payment_method_nonce => nonce_from_the_client
)

Payment flow using payee

Braintree has the ability to change the receiving PayPal account dynamically in the transaction API call. When you specify a payee_id or payee_email, 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 payee_id represents the PayPal account identifier for the payee. It can be found in the PayPal business account settings under Merchant account ID. Both payee_idand payee_email produce the same behavior, but payee_id may be preferable since it cannot be changed in the PayPal business account.

Ruby

result = gateway.transaction.sale(
  :amount => "10.00",
  :payment_method_nonce => nonce_from_the_client,
  :options => {
    :paypal => {
      :payee_id => "PAYPAL_MERCHANT_ID_FOR_RECEIVING_ACCOUNT"
    }
  }
)

Note

When creating a transaction with the payment_method_nonce , the options-paypal-payee_id parameter can only be used if the nonce represents a vaulted PayPal account. When creating a transaction with the payment_method_token, the options-paypal-payee_id parameter cannot be used if the payment method represents a PayPal Order.

Payee email

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

Ruby

result = gateway.transaction.sale(
  :amount => "10.00",
  :payment_method_nonce => nonce_from_the_client,
  :options => {
    :paypal => {
      :payee_email => "PRIMARY_EMAIL_ADDRESS_FOR_RECEIVING_ACCOUNT"
    }
  }
)

Setup

PayPal permissions

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

Multi-currency configuration

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

Ruby

result = gateway.transaction.sale(
  :amount => "10.00",
  :merchant_account_id => "merchantNameCURRENCYCODE",
  :payment_method_nonce => nonce_from_the_client,
  :options => {
    :paypal => {
      :payee_id => "PAYPAL_MERCHANT_ID_FOR_RECEIVING_ACCOUNT"
    }
  }
)

Refunds

Refunds are processed the same way as a normal refund via Braintree, with no reference to the payee_id or payee_email. 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 payee_id and payee_email 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 merchant_account_id for each payee_id and payee_email you plan to use.