Creating Payment Methods with Payee Email

When creating a payment method to use with a PayPal Order, you can pass the payeeEmail parameter to automatically route all payments processed on that payment method to a PayPal account other than the one linked in your Braintree Control Panel. This is useful when you want to settle funds from all parts of a given order to the same PayPal account, but you have a multi-currency setup with separate PayPal accounts or different accounts for different parts of your business. Regardless of the reason for using a different PayPal account, the account you specify in payeeEmail must be one that you own.

How it works

Normal PayPal Order flow without payee email

In the normal PayPal Order flow, the customer successfully authenticates with PayPal on the client side, and you use one of the options on the server-side section to create a payment method that you will charge for the order. When you process transactions against this payment method, Braintree sends funds from those transactions to the PayPal account linked in your Control Panel.

Using payee email with PayPal Order

The first part of the payee email flow is the same as above, but when you create a payment method for the order, you'll also specify a payeeEmail for your own PayPal account where you want to receive the funds from the order's transactions. The PayPal account you specify gets all the funds for all the transactions processed against this payment method, as if those transactions were processed entirely on that account. The PayPal account linked in your Braintree Control Panel does not see these transactions in its account or reporting.

Examples

Create new customer with payment method and payee email

If you do not already have a record for this customer in your Vault, you can create a new customer with a payment method using Customer: Create with the paymentMethodNonce() parameter and your payeeEmail.

Java

CustomerRequest request = new CustomerRequest()
    .firstName("Fred")
    .lastName("Jones")
    .paymentMethodNonce(nonceFromTheClient)
    .options()
    .paypal()
    .payeeEmail("PRIMARY_EMAIL_ADDRESS_FOR_RECEIVING_ACCOUNT")
    .done();

Result<customer> result = gateway.customer().create(request);
result.isSuccess(); // true
Customer customer = result.getTarget();
customer.getId(); // e.g. 160923
customer.getPaymentMethods().get(0).getToken(); // e.g. f28w

Update existing customer with new payment method and payee email

If the customer already exists in your Vault, you can add a new payment method to that customer using Customer: Update with the paymentMethodNonce() parameter and your payeeEmail.

Java

CustomerRequest request = new CustomerRequest()
    .paymentMethodNonce(nonceFromTheClient)
    .options()
    .paypal()
    .payeeEmail("PRIMARY_EMAIL_ADDRESS_FOR_RECEIVING_ACCOUNT")
    .done();

Result<customer> updateResult = gateway.customer().update("the_customer_id", request);
result.isSuccess(); // true

If the customer can't be found, it will throw a NotFoundException. Alternatively, you can use Payment Method: Create to accomplish the same thing as above.

Setup

PayPal permissions

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

Multi-currency configuration

Currency is not controlled by the 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.

Refunds

Refunds are processed the same way as a normal refund via Braintree, with no reference to the 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 payeeEmail parameter is 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 payeeEmail you plan to use.