paypal-mcp

PayPal MCP server integration for invoices, payments, subscriptions, disputes, and transaction reporting via @paypal/mcp.

GF(3) Assignment

Trit: 0 (ERGODIC)
Role: Coordinator - orchestrates payment flows between crypto and fiat
Color: #26D826 (green)

MCP Server Setup

Amp Configuration (~/.amp/servers.json)

{
  "paypal": {
    "command": "npx",
    "args": ["-y", "@paypal/mcp", "--tools=all"],
    "env": {
      "PAYPAL_ACCESS_TOKEN": "${PAYPAL_ACCESS_TOKEN}",
      "PAYPAL_ENVIRONMENT": "SANDBOX"
    }
  }
}

Claude Configuration (~/.claude.json)

{
  "mcpServers": {
    "paypal": {
      "command": "npx",
      "args": ["-y", "@paypal/mcp", "--tools=all"],
      "env": {
        "PAYPAL_ACCESS_TOKEN": "${PAYPAL_ACCESS_TOKEN}",
        "PAYPAL_ENVIRONMENT": "PRODUCTION"
      }
    }
  }
}

Token Generation

PayPal requires OAuth2 access tokens. Token validity:

• Sandbox: 3-8 hours
• Production: 8 hours

Generate Access Token

# Sandbox
curl -X POST https://api-m.sandbox.paypal.com/v1/oauth2/token \
  -H "Accept: application/json" \
  -H "Accept-Language: en_US" \
  -u "${PAYPAL_CLIENT_ID}:${PAYPAL_CLIENT_SECRET}" \
  -d "grant_type=client_credentials"

# Production
curl -X POST https://api-m.paypal.com/v1/oauth2/token \
  -H "Accept: application/json" \
  -H "Accept-Language: en_US" \
  -u "${PAYPAL_CLIENT_ID}:${PAYPAL_CLIENT_SECRET}" \
  -d "grant_type=client_credentials"

Token Refresh Script

#!/bin/bash
# paypal-token-refresh.sh
export PAYPAL_ACCESS_TOKEN=$(curl -s -X POST \
  "https://api-m.${PAYPAL_ENVIRONMENT:-sandbox}.paypal.com/v1/oauth2/token" \
  -H "Accept: application/json" \
  -u "${PAYPAL_CLIENT_ID}:${PAYPAL_CLIENT_SECRET}" \
  -d "grant_type=client_credentials" | jq -r '.access_token')
echo "Token refreshed: ${PAYPAL_ACCESS_TOKEN:0:20}..."

Available Tools

Invoices

| Tool | Description | |------|-------------| | create_invoice | Create a new invoice | | list_invoices | List all invoices | | get_invoice | Get invoice details by ID | | send_invoice | Send invoice to recipient | | send_invoice_reminder | Send payment reminder | | cancel_sent_invoice | Cancel a sent invoice | | generate_invoice_qr_code | Generate QR code for invoice payment |

Payments

| Tool | Description | |------|-------------| | create_order | Create a payment order | | get_order | Get order details | | pay_order | Capture/execute payment | | create_refund | Issue a refund | | get_refund | Get refund status |

Dispute Management

| Tool | Description | |------|-------------| | list_disputes | List all disputes | | get_dispute | Get dispute details | | accept_dispute_claim | Accept a dispute claim |

Shipment Tracking

| Tool | Description | |------|-------------| | create_shipment_tracking | Add tracking info to transaction | | get_shipment_tracking | Get tracking status |

Catalog Management

| Tool | Description | |------|-------------| | create_product | Create product in catalog | | list_products | List all products | | show_product_details | Get product details | | update_product | Update product info |

Subscription Management

| Tool | Description | |------|-------------| | create_subscription_plan | Create billing plan | | update_plan | Update plan details | | list_subscription_plans | List all plans | | show_subscription_plan_details | Get plan details | | create_subscription | Create subscription for customer | | show_subscription_details | Get subscription status | | update_subscription | Modify subscription | | cancel_subscription | Cancel active subscription |

Reporting

| Tool | Description | |------|-------------| | list_transactions | List transactions with filters |

Key Use Cases

1. Create and Send Invoice

User: Create an invoice for $150 consulting fee to client@example.com

Agent Flow:
1. create_invoice(amount: 150, currency: "USD", recipient: "client@example.com", description: "Consulting services")
2. send_invoice(invoice_id: "<returned_id>")
3. generate_invoice_qr_code(invoice_id: "<returned_id>")

2. Process Order Payment

User: Create an order for $99.99 and capture payment

Agent Flow:
1. create_order(amount: 99.99, currency: "USD", intent: "CAPTURE")
2. get_order(order_id: "<returned_id>") -- verify status
3. pay_order(order_id: "<returned_id>") -- capture funds

3. List Recent Transactions

User: Show me transactions from the last 7 days

Agent Flow:
1. list_transactions(start_date: "2024-12-24", end_date: "2024-12-31")

4. Subscription Workflow

User: Create a monthly $29 subscription plan

Agent Flow:
1. create_product(name: "Premium Service", type: "SERVICE")
2. create_subscription_plan(product_id: "<id>", name: "Monthly Premium", billing_cycles: [{frequency: "MONTH", price: 29}])
3. create_subscription(plan_id: "<plan_id>", subscriber_email: "user@example.com")

APT → PYUSD → PayPal Integration Pattern

Bridge crypto (Aptos) to fiat (PayPal) via PYUSD stablecoin:

┌─────────────────────────────────────────────────────────────────┐
│                    APT → PYUSD → PAYPAL FLOW                     │
└─────────────────────────────────────────────────────────────────┘

┌──────────┐     ┌──────────┐     ┌──────────┐     ┌──────────┐
│   APT    │────▶│  DEX     │────▶│  PYUSD   │────▶│  PayPal  │
│  Wallet  │     │  Swap    │     │  Bridge  │     │  Payout  │
└──────────┘     └──────────┘     └──────────┘     └──────────┘
     │                │                │                │
     │ aptos_swap     │ liquidswap     │ pyusd_redeem   │ create_order
     │                │                │                │ pay_order

Triadic Flow (GF(3) Balanced)

;; +1 GENERATOR: Aptos swap APT→PYUSD
(aptos_swap {:from "APT" :to "PYUSD" :amount 100})

;; 0 COORDINATOR: Bridge PYUSD to PayPal (this skill)
(create_order {:amount 100 :currency "USD" :funding "PYUSD"})

;; -1 VALIDATOR: Verify settlement
(get_order {:order_id order-id})  ;; Confirm COMPLETED status

DuckDB Tracking

CREATE TABLE paypal_bridge_txns (
  txn_id VARCHAR PRIMARY KEY,
  aptos_txn_hash VARCHAR,
  pyusd_amount DECIMAL(18,6),
  usd_amount DECIMAL(10,2),
  paypal_order_id VARCHAR,
  status VARCHAR,  -- PENDING, BRIDGED, SETTLED, FAILED
  created_at TIMESTAMP,
  settled_at TIMESTAMP,
  gf3_trit INT CHECK (gf3_trit IN (-1, 0, 1))
);

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | PAYPAL_ACCESS_TOKEN | Yes | OAuth2 access token | | PAYPAL_ENVIRONMENT | Yes | SANDBOX or PRODUCTION | | PAYPAL_CLIENT_ID | For refresh | App client ID | | PAYPAL_CLIENT_SECRET | For refresh | App client secret |

Error Handling

Common PayPal API errors:

• AUTHENTICATION_FAILURE - Token expired, refresh required
• INVALID_RESOURCE_ID - Invoice/order not found
• PERMISSION_DENIED - Scope not authorized
• RATE_LIMIT_REACHED - Too many requests, backoff

Triadic Skill Composition

PayPal-MCP as ERGODIC (0) coordinator in payment triads:

┌─────────────────────────────────────────────────────────────────┐
│  PAYMENT TRIAD                                                   │
├─────────────────────────────────────────────────────────────────┤
│  +1 GENERATOR   │  aptos-agent      │  Create crypto txn        │
│   0 COORDINATOR │  paypal-mcp       │  Bridge to fiat           │
│  -1 VALIDATOR   │  duckdb-ies       │  Verify settlement        │
├─────────────────────────────────────────────────────────────────┤
│  Σ trits = (+1) + (0) + (-1) = 0 ≡ 0 (mod 3) ✓                 │
└─────────────────────────────────────────────────────────────────┘

See Also

• aptos-agent - Aptos blockchain interactions
• aptos-trading - DEX swaps for APT→PYUSD
• duckdb-ies - Transaction tracking and analytics
• google-workspace - Invoice delivery via Gmail

References

• PayPal MCP Server
• PayPal REST API Docs
• PYUSD Documentation