The first time you process a PayPal transaction for a new customer, you must do so via the API. After that, you will be able to create PayPal transactions using the customer's Vault record, either via the Control Panel or the API.

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.

Your customer can cancel or change the payment method associated with this 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.

PayPal transaction lifecycle

PayPal transactions go through a similar lifecycle as other payment types, but with a unique settlement process.

Authorization

The simplest approach when processing a transaction is to authorize and submit for settlement at the same time. That being said, Braintree and PayPal do support separate authorization and capture. This option 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.

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.

note
  • 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.

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

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

Settlement

Unlike other payment methods, PayPal transactions are not settled in batches; instead, funds are captured right after you submit each transaction for settlement. This allows us to instantly inform you when a settlement is successful, so you can confidently ship your goods or provide your services immediately.

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.

Multiple partial settlements

Multiple partial settlements are only available for PayPal transactions, and allow you to settle multiple amounts against a single authorization. This method can be helpful if you have a delayed order fulfillment process or 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 will charge the customer for that portion in a separate child transaction. Learn more in our developer documentation.

Refunds and voids

Just like with 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 initial sale.

Disputes

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

Seller Protection

Braintree supports PayPal's Seller Protection for merchants who sell shipped goods online. To qualify for Seller Protection and avoid certain types of chargebacks, you must:

  • Pass a properly-formatted shipping address with each PayPal transaction
  • Meet PayPal's Seller Protection requirements

Next Page: Disputes →