PayPal Integration

Overview

PayPal Checkout lets shoppers pay using their PayPal balance, Venmo, Pay Later (installments), or a card processed by PayPal. It is particularly valuable in Germany, Netherlands, and Brazil where PayPal is the dominant payment method, and in any market where customers prefer not to enter card details. All major platforms have official PayPal integrations that require only credentials — no custom code needed for standard checkout.

When to Use This Skill

When adding PayPal as a payment option alongside a card processor
When implementing PayPal Express Checkout on the product page or cart (reduces steps to purchase)
When targeting markets where PayPal is the dominant payment method (Germany, Netherlands, Brazil)
When adding Venmo or Pay Later (installments) to appeal to younger shoppers

Core Instructions

Step 1: Create and configure your PayPal Business account

Sign up for a PayPal Business account at paypal.com/business if you do not already have one
Verify your business identity (required before you can receive payments)
For development and testing: sign up at developer.paypal.com and create sandbox buyer/seller accounts
Create an app at developer.paypal.com → My Apps → Create App to get your Client ID and Secret

Step 2: Install PayPal on your platform

Shopify

PayPal Express Checkout is built into Shopify and is enabled by default on most stores.

To verify or reconfigure:

Go to Settings → Payments
Under Payment providers, click PayPal or Activate PayPal
If not already connected, click Activate and log in with your PayPal Business account to link it
Choose between:
- PayPal Express Checkout: the classic checkout flow (recommended)
- PayPal Complete Payments: a newer integration that also supports Venmo and Pay Later

Enable Venmo and Pay Later:

In your PayPal Business dashboard, go to Account Settings → Payment Preferences
Enable Venmo and Pay Later — these appear automatically in the Shopify checkout once activated on your PayPal account
To show a Pay Later banner on product pages: install the PayPal Pay Later Messaging app from the Shopify App Store

WooCommerce

Install the WooCommerce PayPal Payments plugin (the official plugin maintained by WooCommerce/PayPal — available free from WordPress.org)
Go to WooCommerce → Settings → Payments → PayPal Payments → Set Up
Click Connect to PayPal and log in with your PayPal Business account (OAuth setup — no need to copy/paste API keys)
The plugin automatically enables: PayPal Standard, Venmo, Pay Later, card fields, and the PayPal Credit option
Configure button placement under WooCommerce → Settings → Payments → PayPal Payments → Smart Payment Buttons:
- Enable buttons on: product pages, cart page, checkout page
- Configure button color (gold, blue, silver, white, black)
To show Pay Later messaging on product pages: go to Pay Later Messaging section in the plugin settings and enable it

PayPal Checkout (alternative, older integration): The older WooCommerce PayPal Checkout plugin still works but the newer WooCommerce PayPal Payments plugin is recommended for all new setups.

BigCommerce

Go to Settings → Payment Methods → Online Payment Methods
Find PayPal Powered by Braintree and click Set Up
Click Connect with PayPal and authorize with your PayPal Business account
Enable the payment methods you want: PayPal, Venmo, Pay Later
Configure which pages show the PayPal buttons in the configuration panel

Alternatively, BigCommerce supports PayPal Commerce Platform — go to Settings → Payment Methods and choose PayPal Commerce Platform for access to the full suite of PayPal payment options.

Custom / Headless

For headless storefronts, use the PayPal JavaScript SDK with the Orders API v2:

Load the PayPal JavaScript SDK:

<!-- Always load from the CDN — never install as an npm package -->
<script src="https://www.paypal.com/sdk/js?client-id=YOUR_CLIENT_ID&currency=USD&intent=capture&components=buttons"></script>

Create a PayPal order server-side:

// POST /api/paypal/create-order
async function createPayPalOrder(req, res) {
  const { cartId } = req.body;
  const cart = await db.carts.findUnique({ where: { id: cartId } });
  const accessToken = await getPayPalAccessToken();

  const orderRes = await fetch('https://api-m.paypal.com/v2/checkout/orders', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${accessToken}`,
      'Content-Type': 'application/json',
      'PayPal-Request-Id': cartId, // Idempotency key
    },
    body: JSON.stringify({
      intent: 'CAPTURE',
      purchase_units: [{
        reference_id: cartId,
        amount: {
          currency_code: 'USD',
          value: cart.total.toFixed(2),
        },
      }],
    }),
  });

  const order = await orderRes.json();
  res.json({ id: order.id });
}

Render PayPal buttons and capture payment:

useEffect(() => {
  if (!window.paypal) return;

  window.paypal.Buttons({
    style: { layout: 'vertical', color: 'gold', shape: 'rect' },

    createOrder: async () => {
      const res = await fetch('/api/paypal/create-order', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ cartId }),
      });
      const data = await res.json();
      return data.id; // PayPal Order ID
    },

    onApprove: async (data) => {
      // Always capture server-side — never trust client-side only
      const res = await fetch('/api/paypal/capture-order', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ orderId: data.orderID, cartId }),
      });
      const result = await res.json();
      if (result.success) router.push(`/orders/${result.shopOrderId}/confirmation`);
    },

    onCancel: () => {
      // User closed PayPal popup — leave cart intact, show no error
    },

    onError: (err) => {
      console.error('PayPal error:', err);
      setError('PayPal encountered an error. Please try again or use a card.');
    },
  }).render('#paypal-button-container');
}, [cartId]);

Capture the payment server-side:

// POST /api/paypal/capture-order
async function capturePayPalOrder(req, res) {
  const { orderId, cartId } = req.body;
  const accessToken = await getPayPalAccessToken();

  const captureRes = await fetch(`https://api-m.paypal.com/v2/checkout/orders/${orderId}/capture`, {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${accessToken}`,
      'Content-Type': 'application/json',
      'PayPal-Request-Id': `capture-${orderId}`, // Idempotency key
    },
  });

  const capture = await captureRes.json();
  if (capture.status !== 'COMPLETED') {
    return res.status(400).json({ error: 'Payment capture failed' });
  }

  // Create your internal order record
  const order = await createOrderFromCart(cartId, {
    paymentMethod: 'paypal',
    paypalOrderId: orderId,
    paypalCaptureId: capture.purchase_units[0].payments.captures[0].id,
  });

  res.json({ success: true, shopOrderId: order.id });
}

Handle PayPal webhooks:

Register webhooks in your PayPal developer dashboard for: PAYMENT.CAPTURE.COMPLETED, PAYMENT.CAPTURE.REFUNDED, PAYMENT.CAPTURE.REVERSED. Verify webhook signatures using PayPal's signature verification API before processing.

Step 3: Test with PayPal sandbox

Go to developer.paypal.com → Sandbox → Accounts and use the pre-created sandbox buyer and seller accounts

Set environment variables to use sandbox:

PAYPAL_CLIENT_ID=<sandbox-client-id>
PAYPAL_CLIENT_SECRET=<sandbox-client-secret>
PAYPAL_API_BASE=https://api-m.sandbox.paypal.com

Test a full purchase flow using the sandbox buyer account credentials
Verify the webhook fires and your handler processes it correctly

Best Practices

Always capture server-side — do not trust the onApprove client callback alone; always capture using the Orders API from your server
Use PayPal-Request-Id header — this idempotency key prevents double charges if a request is retried
Enable Pay Later messaging on product pages — showing "4 interest-free payments of $X" before checkout increases AOV; the WooCommerce plugin has this built in
Handle onCancel gracefully — when users close the PayPal popup, do not show an error; just let them try again or choose another payment method
Verify webhook signatures — PayPal can call your webhook endpoint with forged payloads; always verify the paypal-transmission-sig header

Common Pitfalls

Problem	Solution
"This seller doesn't accept payments" error	Ensure your PayPal account has completed seller onboarding (email verification, bank account linked); also verify sandbox vs. production credentials match
PayPal popup blocked on some browsers	The `createOrder` callback must return a value immediately from a user click event; any async delay can trigger popup blockers — move server calls before the button renders or use PayPal's built-in API
Order confirmed by webhook before capture completes	Use the `PAYMENT.CAPTURE.COMPLETED` webhook (not `CHECKOUT.ORDER.APPROVED`); the latter fires before funds are captured
Duplicate order on webhook retry	Check for an existing order with the PayPal capture ID before creating a new one
WooCommerce PayPal plugin not showing Venmo/Pay Later	Venmo and Pay Later must be enabled in your PayPal Business account settings (not just the plugin) — check Account Settings → Payment Preferences in PayPal
Shopify PayPal not processing after reconnection	Disconnect and reconnect your PayPal account in Shopify → Settings → Payments; old OAuth tokens sometimes expire

Related Skills

@stripe-integration
@checkout-flow-optimization
@order-processing-pipeline
@buy-now-pay-later

paypal-integration