Creating Payment Methods with Payee Email

When creating a payment method to use with a PayPal Order, you can pass the payee_email 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 payee_email must be one that you own.

How it worksAnchorIcon

Normal PayPal Order flow without payee emailAnchorIcon

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 OrderAnchorIcon

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 payee_email 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.

ExamplesAnchorIcon

Create new customer with payment method and payee emailAnchorIcon

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 payment_method_nonce parameter and your payee_email.
  1. Ruby
result = gateway.customer.create(
    :first_name => "Charity",
    :last_name => "Smith",
    :payment_method_nonce => nonce_from_the_client,
    :options => {
        :paypal => {
            :payee_email => "PRIMARY_EMAIL_ADDRESS_FOR_RECEIVING_ACCOUNT"
        }
    }
);

if result.success? {
    puts result.customer.id;
    puts result.customer.payment_methods[0].token;
} else {
    p result.errors;
}

Update existing customer with new payment method and payee emailAnchorIcon

If the customer already exists in your Vault, you can add a new payment method to that customer using Customer: Update with the payment_method_nonce parameter and your payee_email.
  1. Ruby
result = gateway.customer.update(
    "a_customer_id", // id of customer to update
    :payment_method_nonce => nonce_from_the_client,
    :options => {
        :paypal => {
            :payee_email => "PRIMARY_EMAIL_ADDRESS_FOR_RECEIVING_ACCOUNT"
        }
    }
);

if result.success? {
    puts "customer successfully updated";
} else {
    p result.errors;
}
If the customer can't be found, it will raise a Braintree::NotFoundError. Alternatively, you can use Payment Method: Create to accomplish the same thing as above.

SetupAnchorIcon

PayPal permissionsAnchorIcon

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

Multi-currency configurationAnchorIcon

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

RefundsAnchorIcon

Refunds are processed the same way as a normal refund via Braintree, with no reference to the 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 PanelAnchorIcon

The payee_email 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 merchant_account_id for each payee_email you plan to use.