---

name: paypal-integration description: "掌握 PayPal 支付集成，包括快速结账、IPN 处理、循环计费和退款工作流。" risk: unknown source: community date_added: "2026-02-27"

PayPal 集成

掌握 PayPal 支付集成，包括快速结账、IPN 处理、循环计费和退款工作流。

不适用场景

• 任务与 PayPal 集成无关
• 需要此范围之外的不同领域或工具

使用说明

• 明确目标、约束条件和所需输入。
• 应用相关最佳实践并验证结果。
• 提供可操作的步骤和验证方法。
• 如需详细示例，请打开 resources/implementation-playbook.md。

何时使用此技能

• 集成 PayPal 作为支付选项
• 实现快速结账流程
• 设置 PayPal 循环计费
• 处理退款和支付争议
• 处理 PayPal Webhooks (IPN)
• 支持国际支付
• 实现 PayPal 订阅

核心概念

1. 支付产品

PayPal Checkout

• 一次性支付
• 快速结账体验
• 访客和 PayPal 账户支付

PayPal Subscriptions

• 循环计费
• 订阅计划
• 自动续费

PayPal Payouts

• 向多个收款人付款
• 市场和平台支付

2. 集成方式

客户端（JavaScript SDK）

• 智能支付按钮
• 托管支付流程
• 最少后端代码

服务端（REST API）

• 完全控制支付流程
• 自定义结账 UI
• 高级功能

3. IPN（即时支付通知）

• 类似 Webhook 的支付通知
• 异步支付更新
• 需要验证

快速入门

// Frontend - PayPal Smart Buttons
<div id="paypal-button-container"></div>

<script src="https://www.paypal.com/sdk/js?client-id=YOUR_CLIENT_ID&currency=USD"></script>
<script>
  paypal.Buttons({
    createOrder: function(data, actions) {
      return actions.order.create({
        purchase_units: [{
          amount: {
            value: '25.00'
          }
        }]
      });
    },
    onApprove: function(data, actions) {
      return actions.order.capture().then(function(details) {
        // Payment successful
        console.log('Transaction completed by ' + details.payer.name.given_name);

        // Send to backend for verification
        fetch('/api/paypal/capture', {
          method: 'POST',
          headers: {'Content-Type': 'application/json'},
          body: JSON.stringify({orderID: data.orderID})
        });
      });
    }
  }).render('#paypal-button-container');
</script>

# Backend - Verify and capture order
from paypalrestsdk import Payment
import paypalrestsdk

paypalrestsdk.configure({
    "mode": "sandbox",  # or "live"
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET"
})

def capture_paypal_order(order_id):
    """Capture a PayPal order."""
    payment = Payment.find(order_id)

    if payment.execute({"payer_id": payment.payer.payer_info.payer_id}):
        # Payment successful
        return {
            'status': 'success',
            'transaction_id': payment.id,
            'amount': payment.transactions[0].amount.total
        }
    else:
        # Payment failed
        return {
            'status': 'failed',
            'error': payment.error
        }

快速结账实现

服务端订单创建

import requests
import json

class PayPalClient:
    def __init__(self, client_id, client_secret, mode='sandbox'):
        self.client_id = client_id
        self.client_secret = client_secret
        self.base_url = 'https://api-m.sandbox.paypal.com' if mode == 'sandbox' else 'https://api-m.paypal.com'
        self.access_token = self.get_access_token()

    def get_access_token(self):
        """获取 OAuth 访问令牌。"""
        url = f"{self.base_url}/v1/oauth2/token"
        headers = {"Accept": "application/json", "Accept-Language": "en_US"}

        response = requests.post(
            url,
            headers=headers,
            data={"grant_type": "client_credentials"},
            auth=(self.client_id, self.client_secret)
        )

        return response.json()['access_token']

    def create_order(self, amount, currency='USD'):
        """创建 PayPal 订单。"""
        url = f"{self.base_url}/v2/checkout/orders"
        headers = {
            "Content-Type": "application/json",
            "Authorization": f"Bearer {self.access_token}"
        }

        payload = {
            "intent": "CAPTURE",
            "purchase_units": [{
                "amount": {
                    "currency_code": currency,
                    "value": str(amount)
                }
            }]
        }

        response = requests.post(url, headers=headers, json=payload)
        return response.json()

    def capture_order(self, order_id):
        """捕获支付。"""
        url = f"{self.base_url}/v2/checkout/orders/{order_id}/capture"
        headers = {
            "Content-Type": "application/json",
            "Authorization": f"Bearer {self.access_token}"
        }
        response = requests.post(url, headers=headers)
        return response.json()