PayPal Complete Payments

What it is

PayPal Complete Payments is an integration option for PayPal that supports credit and debit card payments directly on the checkout, available in specific countries, as well as the ability to pay with a PayPal account, PayPal Credit, Venmo and a number of other local payment methods that PayPal supports with PayPal Checkout.

PayPal Checkout

PayPal Checkout is what most people think of when they think of PayPal: customers pay with their PayPal account through PayPal's payment pages. Previous integrations redirected the customer to a PayPal hosted payment page, but PayPal Complete Payments loads a popup over the page instead, which is a much cleaner experience for customers.

PayPal Checkout also supports local payment methods like Bancontact, BLIK, eps, iDEAL, MyBank, Przelewy24 (P24) and Trustly. Local options are determined dynamically on the checkout based on the customer's location and the type of products being ordered, whether subscriptions or one-off.

PayPal Checkout is supported in all countries where PayPal payments are supported, and just requires a PayPal account.

If you're selling subscriptions, local payment methods aren't supported for recurring payments. Customers will just see PayPal as a payment option if a subscription is present in the cart.

PayPal Checkout with card payments

Along with PayPal and local payment options, Complete Payments can accept credit cards directly on the Foxy checkout without the customer leaving the page.

Card payments aren't supported in all countries, and require a PayPal Business account plus some additional application requirements. Countries currently supported: Australia, Austria, Belgium, Bulgaria, Canada, China, Cyprus, Czech Republic, Denmark, Estonia, Finland, France, Germany, Greece, Hong Kong, Hungary, Ireland, Italy, Japan, Latvia, Liechtenstein, Lithuania, Luxembourg, Malta, Mexico, Netherlands, Norway, Poland, Portugal, Romania, Singapore, Slovakia, Slovenia, Spain, Sweden, United Kingdom, United States.

Setting up PayPal Complete Payments

If you already use PayPal Complete Payments and just want to add Apple Pay, there are extra setup steps to complete first. Skip down to Using Apple Pay with PayPal Complete Payments below.

If you're setting up PayPal Complete Payments for the first time and want to use Apple Pay, follow the instructions here, then go to Register your Foxy domain with PayPal.

If you're unsure about any of this, reach out to us and we'll be happy to help.

Connecting PayPal with your Foxy store is done through an authentication flow from the Foxy administration:

1. 1

   In the Foxy administration, navigate to the Payment page. This setup currently requires the legacy admin at admin.foxycart.com.

2. 2

   Enable the checkbox labelled Accept payments using your PayPal Commerce Platform account.

3. 3

   In the options that appear, click the Connect to… button for the PayPal option you want, whether just PayPal Checkout, or PayPal Checkout with Card Payments if it's supported in your country.

4. 4

   You'll be redirected to PayPal to log in and provide the necessary details. Depending on the integration you selected, you may need to provide a number of different details to PayPal to complete the flow.

5. 5

   Once you complete the necessary information, you'll be redirected back to the Foxy administration.

6. 6

   If the connection was successful you'll see the connected email address shown. If you connected with Card Payments, you'll have some additional settings:

   • Card verification mode — whether to verify entered card details for $0 purchases, or for all purchases

   • Authorize only — if enabled, only authorizes funds without capturing them. Funds need to be captured manually through the PayPal administration, or through Foxy if your store is enabled for the beta capture/refund functionality

   • Show credit card form — show the credit card form on the checkout for card payments. Leave this unchecked to use a different gateway for card payments

   • Show apple pay button — show the Apple Pay button on the checkout. There are extra setup steps required first; see Register your Foxy domain with PayPal below

Setting up your currency

Because PayPal Checkout can accept a variety of currencies, unlike most gateways, it's important to set your currency in the template sets page of the Foxy admin using the store locale option. Otherwise it may default to USD, which may not be what you're after.

Subscriptions and recurring billing with PayPal Checkout

If you're selling subscriptions or recurring billing products through Foxy and offering PayPal Checkout as a payment option, you must request Reference Transaction support be enabled on your PayPal account. A Premier or Business account is also required.

Reference Transactions is PayPal functionality that lets Foxy create a billing agreement with customers who pay with PayPal, so we can continue to charge your subscription customers at each renewal. It isn't enabled by default, so you need to contact PayPal to ask for it.

Our PayPal rep has told us the best number for Foxy users in the US is 1-888-221-1161. Outside the US, reach out to your local PayPal support number — after logging into your account, select Help & Contact at the bottom of the page, then Call Us to see the number for your region. Let them know you'd like Reference Transaction support enabled. If you have any trouble, let us know and we'll help walk you through it.

Authorize only

If you'd like to only authorize payments from customers and manually capture the funds later, enable the authorize only (do not capture funds) checkbox.

PayPal Credit

PayPal Complete Payments also supports PayPal Credit as a payment option. Nothing needs to be enabled — it's shown dynamically to customers if PayPal determines they meet the criteria to use it.

Using Apple Pay with PayPal Complete Payments

If you've already been using PayPal Complete Payments and just want to add Apple Pay, follow these steps. If you're new to PayPal Complete Payments, go back to Setting up PayPal Complete Payments first, then come back and complete Register your Foxy domain with PayPal.

1. 1

   Go to the Foxy admin's payment settings. You'll need to use the legacy admin for now at admin.foxycart.com.

2. 2

   If PayPal Complete Payments is your only payment method, temporarily enable Let customers pay with a Purchase Order near the bottom of the list. You'll disable it again shortly.

3. 3

   Disable Accept payments using your PayPal Commerce Platform account and save.

4. 4

   Once you're returned to the settings page, re-enable Accept payments using your PayPal Commerce Platform account and use Connect to PayPal Checkout with Card Payments to reconnect your PayPal account.

5. 5

   Select the options you want for showing the card form, express checkout, and Apple Pay.

6. 6

   Uncheck Let customers pay with a Purchase Order.

7. 7

   Save the settings and test. If you're not using the Purchase Order option, make sure it isn't showing on the checkout.

Register your Foxy domain with PayPal

You need to enable Apple Pay in your PayPal account before you can use it in Foxy. Menus change frequently, so if you don't see these options and aren't sure what to do, reach out to Foxy support.

1. 1

   Make sure Apple Pay is enabled in your PayPal Complete Payments configuration in the Foxy administration.

2. 2

   Log in to your store's PayPal account.

3. 3

   Hover over the profile name in the upper right and click Account Settings.

4. 4

   Scroll down on the left to Payment methods.

5. 5

   Under Apple Pay, click Manage Apple Pay.

6. 6

   Click Add Domain.

7. 7

   Under Add your website, enter the store domain.

8. 8

   You can skip downloading the domain verification file. Click Register Domain.

Testing

Obtaining a test account

Testing PayPal Checkout is a little different to normal, as PayPal has a fully functional sandbox system. It's slightly cumbersome and confusing at first, but works well once you figure it out.

Running test PayPal Checkout transactions

1. 1

   Set up a sandbox account as directed on PayPal's developer site.

2. 2

   Once your sandbox account is created, create a test buyer and a test seller account. PayPal automatically creates one buyer — your email appended with -buyer, type PERSONAL — and one seller — your email appended with -facilitator, type BUSINESS.

3. 3

   Log in to the sandbox with your buyer account and replenish its funds.

4. 4

   In your Foxy admin, go to the payment gateway settings and complete the connection flow using your test seller account credentials for PayPal Complete Payments.

5. 5

   Attempt a checkout with PayPal Checkout from the same browser you're already logged into the PayPal Sandbox from. Use the test buyer email address to complete the payment. Because you have to be logged into the PayPal Sandbox to process a test transaction, this will not work unless you're both logged into the sandbox and attempting your Foxy checkout flow in the same browser.

Test card numbers

Review the test account you created above. All test information should be there.

Important notes and caveats

Possible action: webhook handling

Depending on the payment method the customer used, we don't necessarily know at the time of checkout whether the transaction completed. We rely on a notification from the gateway afterwards to confirm whether it was approved. These transactions are initially marked as pending, and we update them when the gateway confirms the result.

Each time the status changes, a webhook is sent to your endpoint if you're subscribed to transaction events. The status node will be present and contains one of three values: pending, approved or rejected. Depending on what your endpoint does, make sure you check for the appropriate status value first.

For PayPal Checkout, Venmo and other alternate payment methods PayPal provides, we also process refund notifications. This means a transaction/refunded event can be sent to a transaction webhook. On the legacy JSON webhook the equivalent event is Transaction Captured / Refunded / Voided.

If you're using Multiship, only the first address is sent to PayPal as the shipping address.