---- dataentry gateway ----
type                   : gateway # do not change this line
name                   : PayPal Express Checkout # 
countries              : AF, AX, AL, DZ, AS, AD, AO, AI, AQ, AG, AR, AM, AW, AU, AT, AZ, BS, BH, BD, BB, BY, BE, BZ, BJ, BM, BT, BO, BA, BW, BV, BR, IO, BN, BG, BF, BI, KH, CM, CA, CV, KY, CF, TD, CL, CN, CX, CC, CO, KM, CG, CD, CK, CR, CI, HR, CU, CY, CZ, DK, DJ, DM, DO, EC, EG, SV, GQ, ER, EE, ET, FK, FO, FJ, FI, FR, GF, PF, TF, GA, GM, GE, DE, GH, GI, GR, GL, GD, GP, GU, GT, GN, GW, GY, HT, HM, VA, HN, HK, HU, IS, IN, ID, IR, IQ, IE, IM, IL, IT, JM, JP, JO, KZ, KE, KI, KP, KR, KW, KG, LA, LV, LB, LS, LR, LY, LI, LT, LU, MO, MK, MG, MW, MY, MV, ML, MT, MH, MQ, MR, MU, YT, MX, FM, MD, MC, MN, MS, MA, MZ, MM, NA, NR, NP, NL, AN, NC, NZ, NI, NE, NU, NF, MP, NO, OM, PK, PW, PS, PA, PG, PY, PE, PH, PN, PL, PT, PR, QA, RE, RO, RU, RW, SH, KN, LC, PM, VC, WS, SM, ST, SA, SN, CS, SC, SL, SG, SK, SI, SB, SO, ZA, GS, ES, LK, SD, SR, SJ, SZ, SE, CH, SY, TW, TJ, TZ, TH, TL, TG, TK, TO, TT, TN, TR, TM, TC, TV, UG, UA, AE, GB, US, UM, UY, UZ, VU, VE, VN, VG, VI, WF, EH, YE, ZM, ZW # 
support-added          : 0.6.0 # 
support-removed        :  # 
supports-3dsecure      : yes # 
supports-multicurrency : yes # enter "yes" or "no" (without quotes)
gateway_url            : http://www.paypal.com/ # 
----



====== PayPal Express Checkout ======


[[https://www.paypal-marketing.com/emarketing/partner/directory/directory.page#m=p&n=24657428861|{{:gateways:paypal:pp_partner_logo_rgb.jpg?nolink |FoxyCart is a PayPal Gold Partner }}]]
FoxyCart is proud to be a [[https://www.paypal-marketing.com/emarketing/partner/directory/directory.page#m=p&n=24657428861|PayPal Gold Partner]].

<WRAP center round important 100%>
**Version 2.0**: Note that we no longer recommend using the PayPal Express Checkout option for PayPal-hosted payment, except in very specific cases. Our **PayPal Checkout** option under the [[gateways:paypal:commerce_platform#paypal_checkout|PayPal Commerce Platform]] option provides an updated version of the PayPal-hosted option.
</WRAP>

===== What It Is =====
PayPal Express Checkout is what most people think of when they think of PayPal. Using Express Checkout the customer //leaves your site// and goes to PayPal.com to login and pay. If you want to allow the user to pay by credit card //without leaving your site// then you'll need a "real" gateway, as PayPal Express Checkout //cannot// process payments outside of PayPal.com. (Think about entering your PayPal password on a site that isn't PayPal.com. Big, big no-no there.)

<WRAP round tip>
__**Is Express Checkout the same as PayPal Standard?**__
The short answer is, "Yes, you can use PayPal Express Checkout with your standard PayPal account." But it's a good question. PayPal "Standard" is a type of account, where as PayPal Express Checkout is a way to //use// that account. So you can't get a PayPal Express Checkout //account//, but you can use PayPal Express Checkout with any type of PayPal account. (PayPal Standard is somewhat similar to Express Checkout, but it's standalone and does not integrate in the same way as Express Checkout.)
</WRAP>
===== Setting Up PayPal Express Checkout for FoxyCart =====
Typically all you'll have to do is enter your email address in your FoxyCart Admin's "payment" section.

{{ :gateways:paypal:screen_shot_2016-10-03_at_3.33.05_pm.png?nolink&600 |}}

FoxyCart currently has two different integrations for PayPal Express Checkout in FoxyCart 2.0 - "PayPal Commerce Platform" and "PayPal Express Checkout (Legacy)". Generally speaking, you will want to use the "Commerce Platform" integration for your store. The main difference between the two integrations is how subscriptions are handled - with the Commerce Platform integration providing a superior experience for customers and store administrators. For FoxyCart versions 1.1 and older, the single PayPal Express Checkout integration is the same as our "Legacy" integration in 2.0.

When using PayPal to sell subscriptions with the Commerce Platform integration, it does require enabling a feature within your PayPal account that isn't available in all countries. Review the subscriptions section below for more details on this. If you're not sure, please reach out to us and we'll be happy to help you out.
==== Setting Up Your Currency ====
Because PayPal Express Checkout (unlike most gateways) can accept a variety of currencies, it's important to set your currency in your FoxyCart admin's "settings" page, through the "store locale" option. Otherwise it may default to the USD, which may not be what you're after.

==== Allowing Non-PayPal Users to Pay via Credit Card (through PayPal) ====
Your customer who choose PayPal as a payment method will be taken to a screen that allows a login, but in some cases may also allow payment with a credit card //without// requiring the customer to create a PayPal account. This is not universally available, however. It is only available if:
  * The store's PayPal account is a Verified Business Account.
  * The customer is in a country or region that allows payment without a PayPal account. (China, for instance, does not seem to have this option.)
  * The customer doesn't have existing PayPal cookies that may change their options.
These criteria are controlled by PayPal, and FoxyCart has no control over whether or not a customer is allowed to pay through PayPal without creating an account. For more info please see [[https://www.x.com/thread/39145|PayPal's developer forum]].

==== Subscriptions and Recurring Billing with PayPal Express Checkout ====

If you are selling subscriptions or recurring billing products through FoxyCart and are offering PayPal as a payment option, <wrap important>you must complete the steps here</wrap>.

<wrap important>FoxyCart's legacy PayPal Express Checkout integration has some limitations regarding subscriptions which you should be aware of.</wrap> Because of these limitations, the PayPal Express Checkout integration in FoxyCart version 1.1, and the PayPal Express Checkout (Legacy) integration in version 2.0, does not allow users to modify their carts via the ''sub_token''. You also can not have a subscription with a start date in the future if you're using the legacy Express Checkout integration. Beginning with 2.0, our new PayPal Commerce Platform integration does support native FoxyCart subscriptions, meaning you can use the ''sub_token'' to work with PayPal subscriptions. Here are some additional limitations as described in PayPal's documentation:

  * To be able to create a recurring payments profile for the buyer, you must ensure that the buyer's PayPal account includes an active credit card.
  * You can increase the profile amount by only 20% in each 180-day interval after you create the profile.
  * For recurring payments with the Express Checkout API, PayPal does not allow certain updates, such as billing amount, within 3 days of the scheduled billing date.

There is also an additional limitation if you have subscriptions that are only intended to run once and never renew. For example, a subscription add to cart URL that looks like ''&sub_frequency=1m&sub_enddate=1m'', meaning the subscription will end on the same day that it is meant to next renew. In these instances, PayPal won't cancel that subscription correctly, but will instead continue to renew the subscription indefinitely. It will instead need to be cancelled manually.

<WRAP important round>
//**Please note:**//
1. These steps require a Premier or Business account. You will not be able to complete them if you have a Personal account. \\
2. Again, **you must complete the steps here**. Failure to properly configure your IPN will cause subscriptions in FoxyCart to be out of sync with PayPal. Your customers may not be charged or if they are charged, FoxyCart won't have any record of it. Please ensure this is setup correctly before going live.
</WRAP>

=== Part 1: Set up the IPN ===

<wrap tip>Please note that PayPal updates their UI fairly regularly, and their own documentation often doesn't actually line up with how to access certain settings. If you have an issue with the following, please let us know so we can try to update things.</wrap>

FoxyCart's integration with PayPal's [[https://cms.paypal.com/us/cgi-bin/?&cmd=_render-content&content_ID=developer/howto_admin_recurringpayments|recurring payments]] system requires the use of PayPal's [[https://developer.paypal.com/webapps/developer/docs/classic/ipn/integration-guide/IPNIntro/|Instant Payment Notification]] (IPN) system in order to keep our system and their system in sync after each transaction is processed (or fails to process). Follow these steps to activate your IPN:

  - Login to PayPal.
  - In the top right hand corner, click the gear / settings icon, then click "Account Settings".
  - In the left hand side, select "Notifications".
  - In the "Instant payment notifications" row, click the "Update" to the right of "Instant payment notifications".
  - Click the "Choose IPN Settings" button. \\ {{:docs:paymentgateways:paypal_ipn_step3.jpg}}
  - Enter ''https://yourdomain.foxycart.com/ipn.php'', but replace the ''yourdomain.foxycart.com'' with your full FoxyCart store domain. (If you're using a remote store domain like ''store.example.com'' then use that.) \\ {{:docs:paymentgateways:paypal_ipn_step4.jpg}}

=== Part 2: Set up the API Access ===
{{section>payments_pro#step_2_-_configure_api_access&notitle&noheader&nodate&nomdate&nouser&nopermalink&nofooter&noindent&noeditbutton}}


=== Part 3: Enable "Reference Transaction" Support ===

<wrap important>This step is required only for the "PayPal Commerce Platform" payment option</wrap>

Reference Transactions is PayPal functionality that allows FoxyCart to create a billing agreement with your store's customers who wish to pay with PayPal, to allow us to continue to charge your subscription customers at each renewal. It's not enabled by default though for your account, and so you need to contact PayPal to ask for it to be enabled.

Our PayPal rep has let us know that the best number for FoxyCart users in the US to call to get Reference Transaction support enabled for their accounts is 1-888-221-1161. For our users outside of the US, you can reach out to your local PayPal support number - after logging into your account, select "Help & Contact" at the bottom of the page, followed by "Call Us" to see the number for your region. Let them know you'd like to have Reference Transaction support enabled for your PayPal account. If you have any trouble, please [[http://www.foxycart.com/contact|let us know]] and we'll help walk you through it.

<wrap important>
Failure to have Reference Transactions enabled for your account will result in customer attempts to purchase subscriptions failing - returning the customer to the checkout with an error.
</wrap>

=== Part 4: Testing ===
  - Test by signing up for a subscription and ensuring it processes as desired. You can use PayPal's sandbox (details below) if you need.

For more details about recurring payments, please see [[https://developer.paypal.com/webapps/developer/docs/classic/express-checkout/integration-guide/ECGettingStarted/|PayPal's documentation]].
==== Authorize Only ====

If you would like to only authorize payments from customers, and then manually capture the funds later, this can be enabled using the "authorize only (do not capture funds)" checkbox.

Note that enabling this option requires that you also grant API permissions for Foxy to be able to authorize payments on behalf of your account. Review the "[[#subscriptions_and_recurring_billing_with_paypal_express_checkout|Subscriptions and Recurring Billing with PayPal Express Checkout]]" section above, and in particular Part 2, for details on doing that.

==== PayPal Credit ====

Foxy v2.0 and above support PayPal Credit. It can be enabled by a simple checkbox in the PayPal settings. For more, please [[https://www.foxy.io/blog/gateway-improvement-paypal-credit/|see our blog post about PayPal Credit]].

==== Errors? ====
If you're doing subscriptions via PayPal Express or if you see the following error in your store's error logs:
<code>
Error: There was an error processing your payment: (10002 Authentication/Authorization Failed) You do not have permissions to make this API call
</code>
You'll have to follow the [[gateways:paypal:payments_pro|Setting It Up]] instructions for PayPal's Payments Pro, as your account has been set to block 3rd parties from making PayPal requests on your behalf.


===== Testing =====
==== Obtaining a Test Account ====
Testing PayPal Express Checkout is a little different than normal, as PayPal has a [[https://cms.paypal.com/us/cgi-bin/?cmd=_render-content&content_ID=developer/howto_testing_sandbox|fully functional sandbox system]]. It's slightly cumbersome and confusing at first, but it does work very well once you figure it out.

==== Running Test PayPal Express Checkout Transactions ====
{{ :gateways:paypal:paypal-payments.png?250|}}
  - First, set up a sandbox account as directed [[https://developer.paypal.com/webapps/developer/docs/classic/lifecycle/ug_sandbox/|on this page]].
  - Once your sandbox account is created, you'll need to create a test buyer and a test seller account [[https://developer.paypal.com/developer/accounts|on this page]]. In its current iteration, PayPal automatically creates one buyer (your email appended with "-buyer", and has a type corresponding to PERSONAL) and one seller (your email appended with "-facilitator", and has a type corresponding to BUSINESS)
  - Login to the [[https://www.sandbox.paypal.com/|sandbox]] with your buyer account and replenish its funds.
  - In your FoxyCart admin, go to the [[https://admin.foxycart.com/admin.php?ThisAction=EditPaymentGateway|Edit Payment Gateway]] section and input your seller email account for both the PayPal Express Checkout //and// the PayPal Payments Pro email values. (See the image on the right for reference)
  - Attempt a checkout FoxyCart's PayPal Express Checkout <wrap important>//from the same browser that you are already logged into the PayPal Sandbox from//</wrap>. Use the test buyer email address to complete the payment. Again, because you have to be logged into the PayPal Sandbox to process a test transaction it //will not work// unless you're both logged into the sandbox and attempting your FoxyCart checkout flow in the same browser.
  - <wrap hi>If you want to test subscriptions or authorize-only transactions</wrap>, login to your [[https://www.sandbox.paypal.com/|sandbox PayPal account]] as the test seller account. From there, you will need to follow the details as described above for setting up support for subscriptions, with the exception that you'll need to enter the IPN url as ''sandbox_api1.foxycart.com'' instead of ''billing_api1.foxycart.com''. If it prompts you that ''sandbox_api1'' isn't a valid third party URL, ensure that you're still logged into the Sandbox and not PayPal proper.
==== Test Card Numbers ====
Review the test account you created (above). All test information should be there. <wrap help>Know more? Feel free to edit this page with info.</wrap>


===== Important Notes and Caveats =====



===== User Notes and Experiences =====
<wrap tip>Please note that, If you are using Multiship, only the first address will be sent as the shipping address to PayPal.</wrap> 

<wrap tip>If you have tips, experience, or helpful notes related to this gateway that would benefit others, please add them below, including your name and the date.</wrap> We reserve the right to edit or remove comments that don't add value to this page.