paypal-mcp Skill

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) ✓                 │
└─────────────────────────────────────────────────────────────────┘

paypal-mcp