paypal-integration（PayPal 集成）

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)

1. 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:

<!-- 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

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 buyer account credentials
4. 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

Related Skills

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