The first time you charge a customer using PayPal, it will need to be via the API. After that, you can create a PayPal transaction from a Vault record, either via the Control Panel or the API. While PayPal transactions will go through a similar lifecycle as other payment types, there are a few exceptions.

Storing in the Vault

If you are using our Vault flow, PayPal customers will be prompted to enter their PayPal credentials and accept an agreement that will let you store their information in the Braintree Vault for future use.

The customer can cancel or change the payment method associated with the agreement at any time in their PayPal Account Profile. This agreement is associated with the PayPal Business Account credentials that you entered in the Control Panel. If you change which PayPal Business Account you use with Braintree, customers will have to re-enter their PayPal credentials and accept a new agreement.

Depending on your specific integration, you may need to pass additional information with individual PayPal transactions created from the Vault via the API. Learn more about integration options when accepting PayPal.


The simplest approach for any transaction is to authorize and submit for settlement at the same time. However, Braintree and PayPal do support separate authorization and capture, which can be helpful if you have a delayed order fulfillment process and prefer to wait to capture funds until you’re ready to provide your goods or services.

PayPal will not allow you to capture funds if your customer’s account is restricted or locked, or if your account has a high restriction level. Also note: You can't settle more than the authorized amount unless your industry and processor support settlement adjustment (settling a certain percentage over the authorized amount); contact us for details.

You can attempt to capture funds for up to 29 days after a successful authorization, but we recommend capturing sooner rather than later – PayPal can’t ensure that 100% of the authorized funds will be available during that entire 29-day period.

For more details on PayPal authorizations, see PayPal’s article on Authorization & Capture.


While most payment types settle transactions in batches, PayPal funds are captured immediately when you submit each transaction for settlement. This allows us to give you instant feedback on whether a settlement was successful, so you can confidently ship your goods or provide your services.

When settlement is successful, you’ll receive a processor settlement response of Settled. Otherwise, you’ll receive a declined or pending response, depending on the situation and whether you’re using multiple partial settlements. See our transaction status reference for more info.

If you have a delayed order fulfillment process, we also support multiple partial settlements against the same authorization, which is helpful if you send physical goods to customers in multiple shipments. You can create a parent authorization for the entire order amount, and when you’re ready to send each portion of the order, you can charge the customer for that portion in a separate child transaction. For more details on this functionality, see our developer documentation.

Refunds and voids

Just like other payment types, you can issue voids and full or partial refunds for PayPal transactions. We recommend that you do this in the Control Panel or via the Braintree API to ensure the transaction status is accurate in both your PayPal console and the Braintree Control Panel.

PayPal requires that refunds are issued within 180 days of the sale.


Disputed PayPal transactions can be managed in either the Braintree Control Panel or in the PayPal Resolution Center. Learn more.

Seller Protection

If you sell shipped goods, as long as you pass a properly-formatted shipping address with the transaction and meet PayPal's Seller Protection requirements, you’ll be protected from certain types of chargebacks.

Next Page: Disputes →