paypal-integration

What this skill does

# 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

1. Sign up for a **PayPal Business account** at paypal.com/business if you do not already have one
2. Verify your business identity (required before you can receive payments)
3. For development and testing: sign up at **developer.paypal.com** and create sandbox buyer/seller accounts
4. 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:**
1. Go to **Settings → Payments**
2. Under **Payment providers**, click **PayPal** or **Activate PayPal**
3. If not already connected, click **Activate** and log in with your PayPal Business account to link it
4. 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:**
1. In your PayPal Business dashboard, go to **Account Settings → Payment Preferences**
2. Enable **Venmo** and **Pay Later** — these appear automatically in the Shopify checkout once activated on your PayPal account
3. To show a Pay Later banner on product pages: install the **PayPal Pay Later Messaging** app from the Shopify App Store

#### WooCommerce

1. Install the **WooCommerce PayPal Payments** plugin (the official plugin maintained by WooCommerce/PayPal — available free from WordPress.org)
2. Go to **WooCommerce → Settings → Payments → PayPal Payments → Set Up**
3. Click **Connect to PayPal** and log in with your PayPal Business account (OAuth setup — no need to copy/paste API keys)
4. The plugin automatically enables: PayPal Standard, Venmo, Pay Later, card fields, and the PayPal Credit option
5. 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)
6. 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

1. Go to **Settings → Payment Methods → Online Payment Methods**
2. Find **PayPal Powered by Braintree** and click **Set Up**
3. Click **Connect with PayPal** and authorize with your PayPal Business account
4. Enable the payment methods you want: PayPal, Venmo, Pay Later
5. 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:**

```html
<!-- 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:**

```javascript
// 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:**

```jsx
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:**

```javascript
// 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

1. Go to **developer.paypal.com → Sandbox → Accounts** and use the pre-created sandbox buyer and seller accounts
2. 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
   ```
3. Test a full purchase flow using the sandbox buye