Skip to main content
Glama
danny121583

PayPal AI Billing MCP Gateway

by danny121583

PayPal AI Billing Kit (v1.9.0)

AI-Powered Invoicing, Mistake-Recovery Workflows, Conversational Authorization, Automated Sandbox Card Checkout, Merchant-Branded PDF Receipts & Unified 82-Tool Model Context Protocol (MCP) Gateway for PayPal Sandbox.

License: MIT Live Demo Unified MCP Gateway OpenAPI 3.1.0


Live Public Endpoints

Endpoint

Public URL

Purpose

Web Application (Vercel)

https://paypal-ai-billing-kit.vercel.app

Interactive Provider & Customer Billing Dashboard (Desktop & Mobile Web)

Dedicated Unified MCP Gateway (Cloudflare Worker)

https://paypal-ai-billing-mcp.apd1034.workers.dev/mcp

Primary JSON-RPC 2.0 MCP Server (POST & GET) exposing 82 unified tools for ChatGPT MCP, Claude Desktop, and MCP Inspector

Vercel MCP Mirror

https://paypal-ai-billing-kit.vercel.app/api/mcp

Mirror JSON-RPC 2.0 MCP endpoint

OpenAPI 3.1.0 Spec

https://paypal-ai-billing-mcp.apd1034.workers.dev/api/openapi.json

Machine-readable OpenAPI 3.1.0 schema for ChatGPT Custom GPT Actions

Interactive MCP Docs

https://paypal-ai-billing-mcp.apd1034.workers.dev/docs/mcp

Human-readable MCP documentation and curl examples

Downloadable PDF Receipt API (Sample Link)

https://paypal-ai-billing-mcp.apd1034.workers.dev/api/receipts/PPB-INV-2026-1003.pdf

Sample PDF 1.4 receipt (#PPB-INV-2026-1003) for instant viewing; every PayPal Sandbox transaction dynamically generates its own unique receipt via /api/receipts/:invoice_number.pdf (Content-Type: application/pdf)


Related MCP server: Braintree MCP Server

Overview

PayPal AI Billing Kit is a standalone, open-source AI billing and payment application built for the PayPal AI Hackathon 2026. It pairs a multi-role Billing Dashboard (Provider & Customer perspectives) with an in-app Gemini 3.5 Flash-Lite Billing AI Assistant (thinkingLevel: "MEDIUM") and a Unified 82-Tool Model Context Protocol (MCP) Gateway connected to PayPal Sandbox REST v1/v2/v3 APIs (api-m.sandbox.paypal.com) and Official PayPal MCP Discovery (mcp.sandbox.paypal.com/sse).

Key Capabilities

  1. Unified 82-Tool MCP Gateway (https://paypal-ai-billing-mcp.apd1034.workers.dev/mcp):

    • 21 Native Application Tools (source: "native_application"): Customer lookup, invoice search, balance explanation, transaction history, structured + PDF receipts (get_payment_receipt, generate_receipt_pdf), session-isolated audit logs, business metrics, proposal creation, real PayPal Sandbox wallet & card order creation/capture/refund, unpaid invoice voiding, and conversational command execution.

    • 47 Official PayPal MCP Tools (source: "official_paypal_mcp"): paypal_discover_official_mcp plus all 46 official PayPal MCP tools registered by their exact official names (create_invoice, create_recurring_series, activate_recurring_series, get_recurring_series, cancel_recurring_series, delete_recurring_series, list_invoices, get_invoice, send_invoice, send_invoice_reminder, cancel_sent_invoice, delete_invoice, setup_invoice_auto_reminders, update_invoice_auto_reminder, search_invoicing, update_invoicing, cancel_invoice_auto_reminder, generate_invoice_qr_code, generate_invoice_number, record_payment_for_invoice, record_refund_for_invoice, create_conditional_rules_for_invoice, create_product, list_products, update_product, show_product_details, create_subscription_plan, list_subscription_plans, show_subscription_plan_details, create_subscription, show_subscription_details, cancel_subscription, update_subscription, create_shipment_tracking, get_shipment_tracking, update_shipment_tracking, create_order, get_order, pay_order, list_disputes, get_dispute, accept_dispute_claim, list_transactions, create_refund, get_refund, get_merchant_insights).

    • 14 PayPal Sandbox REST-to-MCP Adapter Tools (source: "paypal_rest_adapter"): 8 existing (paypal_get_order, paypal_get_refund, paypal_list_invoices, paypal_generate_invoice_number, paypal_list_disputes, paypal_check_card_eligibility, execute_sandbox_card_payment, run_sandbox_card_lifecycle_test) + 6 new (update_plan, paypal_authorize_order, paypal_list_webhooks, paypal_list_webhook_event_types, paypal_list_invoice_templates, paypal_create_vault_setup_token).

    • Permission Tiers: 39 read_only, 3 proposal_only, and 40 confirmed_demo_write.

  2. Automated Server-Side PayPal Sandbox Direct-Card Checkout (Orders v2 payment_source.card):

    • Alongside standard PayPal Wallet Checkout (PAYER_ACTION_REQUIRED → buyer approval URL) and explicitly labeled Demo Settlement Simulation, supports server-side PayPal Sandbox card payments using allowlisted developer test card profiles (visa_sandbox, mastercard_sandbox, amex_sandbox, decline_refused, decline_expired, decline_insufficient_funds) for automated Order → Capture → Receipt → Refund verification without exposing or accepting raw card numbers (RAW_CARD_CREDENTIALS_FORBIDDEN).

  3. 8-State Payment-Attempt Classification & Session-Isolated Audit Trail:

    • Distinguishes awaiting_buyer_approval, approval_required (ORDER_NOT_APPROVED), payment_declined, buyer_canceled, authorized, captured, refunded, and processing_error so premature capture attempts never inflate declined-card metrics.

    • Enforces strict session and role isolation on get_financial_audit_history (canonical_seed vs session_private).

  4. Dual Authorization Model (Cryptographic Proposals + Conversational Authorization):

    • HMAC-SHA256 Proposal Tokens (PPB-PROP-1...): Server-persisted in public.billing_ai_action_proposals with 30-minute expiration, parameter binding, and single-use consumption.

    • Explicit Conversational Authorization (evaluateConversationalAuthorization): Direct user instructions (e.g., "Create a $35 invoice for Alex Rivera for immunization", "Pay Alex Rivera's $35 invoice", "Refund $20 on invoice PPB-INV-2026-1003", "Void unpaid invoice PPB-INV-2026-1001") execute immediately within $500 single-action and $2,500 daily guardrails, while capability questions ("Can you refund invoices?") and hypothetical questions ("What would happen if I paid?") never trigger writes.

  5. Real End-to-End PayPal Sandbox Payments & Refunds:

    • Creates real PayPal Sandbox Orders (POST /v2/checkout/orders), enforces genuine buyer approval on sandbox.paypal.com, captures payments (POST /v2/checkout/orders/{id}/capture), and executes partial or full refunds (POST /v2/payments/captures/{id}/refund).

  6. Professional Merchant-Branded PDF 1.4 Receipts:

    • Dynamically generates a unique, merchant-first downloadable PDF receipt (GET /api/receipts/:invoice_number.pdf) and base64-encoded PDF inside get_payment_receipt and generate_receipt_pdf for every paid or refunded statement (#PPB-INV-2026-1003.pdf is provided above as a sample PDF for quick viewing, while all live PayPal Sandbox transactions generate their own unique receipt with their real PayPal Order, Capture, and Refund IDs). Features Jenkins Wellness & Telehealth Practice (Provider: Dr. Sarah Jenkins), distinct state titles (Payment Receipt — Paid, Payment & Refund Receipt — Refunded, Payment Receipt — Partially Refunded, Sample Demo Receipt — Not a Real PayPal Payment), card brand & last 4 digits, "Payment processed through PayPal" attribution, and "This receipt was generated electronically. Please retain it for your records." footer.


Connecting ChatGPT MCP to PayPal AI Billing Kit

  1. Open ChatGPT → Settings → Connectors / Developer Mode (MCP).

  2. Add a new MCP Server with:

    • MCP Server URL: https://paypal-ai-billing-mcp.apd1034.workers.dev/mcp

    • Authentication: None required for isolated visitor demo sessions (or OAuth 2.0 auto-discovered via /.well-known/oauth-authorization-server).

  3. Refresh the connector and try these prompts directly in ChatGPT:

Show me Alex Rivera's pending invoices.
Explain Jordan Taylor's failed payment.
Create a $35 invoice for Alex Rivera for immunization.
Prepare payment for Alex Rivera's $35 invoice.
Pay Alex Rivera's $35 invoice PPB-INV-2026-1002.
Give me the payment receipt and PDF download link for PPB-INV-2026-1003.
Refund $15 on invoice PPB-INV-2026-1003.
Inspect PayPal Sandbox order 4G312456A5669123W using paypal_get_order.
Show me the financial audit history.

Application Walkthrough & Screenshots (docs/screenshots/)

1. Provider Dashboard & Connected PayPal Sandbox Status

Provider Dashboard

2. Customer Perspectives (Alex Rivera & Jordan Taylor)

Alex Rivera (Pending & Paid Invoices)

Jordan Taylor (Failed Payment & Recovery)

Alex Rivera

Jordan Taylor

3. Invoice Creation & PayPal Sandbox Connection Controls

Create Invoice Modal

PayPal Sandbox Connected

PayPal Sandbox Disconnected

Create Invoice

PayPal Connected

PayPal Disconnected

4. Failed Payment Recovery, Billing AI Assistant, Unified MCP Modal & Guardrails

Failed Payment Retry (#PPB-INV-2026-1004)

Billing AI Assistant

Failed Payment Retry

Billing AI Assistant

Unified MCP Agent Interface (82 Tools)

Financial Guardrails & Audit Trail

MCP Agent Interface

Guardrails and Audit Trail


Complete 82-Tool Unified MCP Reference (21 Native + 47 Official PayPal MCP + 14 PayPal REST Adapters)

Tier 1 — Read-Only Discovery, Receipts & PayPal Sandbox Inspection (39 Tools)

Tool Name

Source

Description

discover_billing_capabilities

native_application

Returns system capabilities, guardrails ($500 single / $2,500 daily), and 82-tool catalog.

list_demo_customers

native_application

Lists fictional demo customers (Alex Rivera, Jordan Taylor) and provider (Dr. Sarah Jenkins).

search_invoices

native_application

Filters invoices by customer name, status (sent, paid, partially_refunded, refunded, failed, void), or query.

get_invoice_details

native_application

Returns full line-item breakdown, PayPal Order/Capture IDs, payment transactions, and refund history.

explain_outstanding_balances

native_application

Summarizes unpaid balances, overdue invoices, and failed payment recovery steps.

get_transaction_history

native_application

Lists PayPal Order creations, captures, refunds, and failure diagnostics.

get_payment_receipt

native_application

Generates a structured payment receipt plus downloadable PDF URL (pdf_download_url) and pdf_base64.

generate_receipt_pdf

native_application

Generates and validates a binary PDF 1.4 receipt for a paid or refunded statement (refuses unpaid invoices).

get_financial_audit_history

native_application

Lists session-isolated append-only audit entries from billing_audit_events.

get_paypal_sandbox_status

native_application

Verifies live PayPal Sandbox OAuth 2.0 connectivity and merchant connection status.

get_business_metrics

native_application

Computes total invoiced, collected, outstanding, refunded, and genuine failed payment metrics.

paypal_discover_official_mcp

official_paypal_mcp

Probes PayPal's official remote MCP server (mcp.sandbox.paypal.com/sse), OAuth metadata, and 46-tool catalog.

get_recurring_series

official_paypal_mcp

Retrieves a recurring invoice series by ID (GET /v2/invoicing/recurring-invoices/{id}).

list_invoices

official_paypal_mcp

Lists invoices from PayPal Invoicing v2 with pagination (GET /v2/invoicing/invoices).

get_invoice

official_paypal_mcp

Retrieves a PayPal Sandbox invoice by ID (GET /v2/invoicing/invoices/{id}).

search_invoicing

official_paypal_mcp

Searches PayPal invoices or recurring series (POST /v2/invoicing/search-invoices / search-recurring-invoices).

generate_invoice_qr_code

official_paypal_mcp

Generates a QR code image payload for a PayPal invoice (POST /v2/invoicing/invoices/{id}/generate-qr-code).

generate_invoice_number

official_paypal_mcp

Generates the next sequential PayPal invoice number (POST /v2/invoicing/generate-next-invoice-number).

list_products

official_paypal_mcp

Lists PayPal Catalog Products (GET /v1/catalogs/products).

show_product_details

official_paypal_mcp

Retrieves details of a PayPal Catalog Product (GET /v1/catalogs/products/{id}).

list_subscription_plans

official_paypal_mcp

Lists PayPal Subscription Plans (GET /v1/billing/plans).

show_subscription_plan_details

official_paypal_mcp

Retrieves PayPal Subscription Plan details (GET /v1/billing/plans/{id}).

show_subscription_details

official_paypal_mcp

Retrieves PayPal Subscription details (GET /v1/billing/subscriptions/{id}).

get_shipment_tracking

official_paypal_mcp

Retrieves shipment tracking information (GET /v1/shipping/trackers; requires shipping scope).

get_order

official_paypal_mcp

Retrieves PayPal Checkout Order details (GET /v2/checkout/orders/{id}).

list_disputes

official_paypal_mcp

Lists PayPal Customer Disputes (GET /v1/customer/disputes).

get_dispute

official_paypal_mcp

Retrieves details of a specific PayPal dispute (GET /v1/customer/disputes/{id}).

list_transactions

official_paypal_mcp

Lists PayPal Reporting Transactions (GET /v1/reporting/transactions; requires reporting scope).

get_refund

official_paypal_mcp

Retrieves details of a PayPal Refund (GET /v2/payments/refunds/{id}).

get_merchant_insights

official_paypal_mcp

Retrieves PayPal Merchant Insights (GET /v1/merchant/insights; unsupported in Sandbox mode).

paypal_get_order

paypal_rest_adapter

Fetches a live PayPal Sandbox Order (GET /v2/checkout/orders/{id}).

paypal_get_refund

paypal_rest_adapter

Fetches a live PayPal Sandbox Refund (GET /v2/payments/refunds/{id}).

paypal_list_invoices

paypal_rest_adapter

Lists invoices from the PayPal Sandbox Invoicing v2 API (GET /v2/invoicing/invoices).

paypal_generate_invoice_number

paypal_rest_adapter

Generates the next PayPal Sandbox invoice number (POST /v2/invoicing/generate-next-invoice-number).

paypal_list_disputes

paypal_rest_adapter

Lists customer disputes from the PayPal Sandbox Disputes API (GET /v1/customer/disputes).

paypal_check_card_eligibility

paypal_rest_adapter

Checks merchant eligibility for PayPal Sandbox Orders v2 payment_source.card and lists safe test card profiles.

paypal_list_webhooks

paypal_rest_adapter

Lists configured PayPal Sandbox Webhooks (GET /v1/notifications/webhooks).

paypal_list_webhook_event_types

paypal_rest_adapter

Lists all subscribed/available PayPal Sandbox Webhook Event Types (GET /v1/notifications/webhooks-event-types).

paypal_list_invoice_templates

paypal_rest_adapter

Lists merchant PayPal Invoicing v2 Templates (GET /v2/invoicing/templates).

Tier 2 — Proposal-Only (3 Tools)

Tool Name

Source

Description

create_invoice_proposal

native_application

Validates guardrails and issues a signed proposal_id (PPB-PROP-1...) to create an invoice.

prepare_payment_proposal

native_application

Issues a signed proposal_id (PPB-PROP-1...) to initiate PayPal Sandbox checkout.

prepare_refund_proposal

native_application

Validates refundable balance and issues a signed proposal_id (PPB-PROP-1...) for a refund.

Tier 3 — Confirmed Financial Workflows, Official PayPal MCP Writes & REST-to-MCP Adapters (40 Tools)

Tool Name

Source

Description

create_approved_invoice

native_application

Persists a new invoice using either a signed proposal_id or an explicit user_instruction.

create_paypal_checkout_order

native_application

Creates a real PayPal Sandbox Order (v2/checkout/orders) and returns the checkout_approval_url.

capture_paypal_checkout_order

native_application

Captures an approved PayPal Sandbox Order (v2/checkout/orders/{id}/capture) and classifies ORDER_NOT_APPROVED as approval_required.

execute_sandbox_card_payment

paypal_rest_adapter

Executes a real server-side PayPal Sandbox card payment (payment_source.card) using allowlisted Sandbox card profiles.

run_sandbox_card_lifecycle_test

paypal_rest_adapter

Runs a complete isolated 7-step PayPal Sandbox card lifecycle test (Invoice → Order → Capture → Verify → Receipt → Refund → Verify).

execute_approved_refund

native_application

Executes a PayPal Sandbox Refund (v2/payments/captures/{id}/refund) via proposal_id or user_instruction.

void_unpaid_invoice

native_application

Voids an unpaid invoice (draft, sent, overdue, failed) via proposal_id or user_instruction.

execute_conversational_instruction

native_application

Evaluates a natural-language instruction with evaluateConversationalAuthorization and executes authorized actions.

reset_demo_session

native_application

Resets the caller's isolated demo_session_id back to the clean 6-invoice canonical baseline.

create_invoice

official_paypal_mcp

Creates a draft invoice in PayPal Invoicing v2 (POST /v2/invoicing/invoices).

create_recurring_series

official_paypal_mcp

Creates a draft recurring invoice series (POST /v2/invoicing/recurring-invoices).

activate_recurring_series

official_paypal_mcp

Activates a draft recurring invoice series (POST /v2/invoicing/recurring-invoices/{id}/activate).

cancel_recurring_series

official_paypal_mcp

Cancels an active recurring invoice series (POST /v2/invoicing/recurring-invoices/{id}/cancel).

delete_recurring_series

official_paypal_mcp

Deletes a draft recurring invoice series (DELETE /v2/invoicing/recurring-invoices/{id}).

send_invoice

official_paypal_mcp

Sends a draft PayPal invoice to its recipient (POST /v2/invoicing/invoices/{id}/send).

send_invoice_reminder

official_paypal_mcp

Sends a reminder for a sent PayPal invoice (POST /v2/invoicing/invoices/{id}/remind).

cancel_sent_invoice

official_paypal_mcp

Cancels a sent PayPal invoice (POST /v2/invoicing/invoices/{id}/cancel).

delete_invoice

official_paypal_mcp

Deletes a draft PayPal invoice (DELETE /v2/invoicing/invoices/{id}).

setup_invoice_auto_reminders

official_paypal_mcp

Initializes merchant automatic invoice reminder configurations (POST /v2/invoicing/setup-reminders).

update_invoice_auto_reminder

official_paypal_mcp

Updates an invoice auto-reminder configuration (PUT /v2/invoicing/reminders/{id}).

update_invoicing

official_paypal_mcp

Replaces a PayPal invoice or recurring series (PUT /v2/invoicing/invoices/{id} / recurring-invoices/{id}).

cancel_invoice_auto_reminder

official_paypal_mcp

Cancels automatic reminders on a sent PayPal invoice (POST /v2/invoicing/invoices/{id}/cancel-reminders).

record_payment_for_invoice

official_paypal_mcp

Records an external payment on a PayPal invoice (POST /v2/invoicing/invoices/{id}/payments).

record_refund_for_invoice

official_paypal_mcp

Records an external refund on a PayPal invoice (POST /v2/invoicing/invoices/{id}/refunds).

create_conditional_rules_for_invoice

official_paypal_mcp

Creates conditional payment rules on a PayPal invoice (POST /v2/invoicing/invoices/{id}/conditional-rules).

create_product

official_paypal_mcp

Creates a PayPal Catalog Product (POST /v1/catalogs/products).

update_product

official_paypal_mcp

Patches a PayPal Catalog Product (PATCH /v1/catalogs/products/{id}).

create_subscription_plan

official_paypal_mcp

Creates a PayPal Subscription Plan (POST /v1/billing/plans).

create_subscription

official_paypal_mcp

Creates a PayPal Subscription (POST /v1/billing/subscriptions).

cancel_subscription

official_paypal_mcp

Cancels a PayPal Subscription (POST /v1/billing/subscriptions/{id}/cancel).

update_subscription

official_paypal_mcp

Patches a PayPal Subscription (PATCH /v1/billing/subscriptions/{id}).

create_shipment_tracking

official_paypal_mcp

Creates shipment tracking info (POST /v1/shipping/trackers-batch; requires shipping scope).

update_shipment_tracking

official_paypal_mcp

Updates shipment tracking info (PUT /v1/shipping/trackers/{id}; requires shipping scope).

create_order

official_paypal_mcp

Creates a PayPal Checkout Order (POST /v2/checkout/orders).

pay_order

official_paypal_mcp

Captures an approved PayPal Checkout Order (POST /v2/checkout/orders/{id}/capture).

accept_dispute_claim

official_paypal_mcp

Accepts liability for a PayPal Customer Dispute (POST /v1/customer/disputes/{id}/accept-claim).

create_refund

official_paypal_mcp

Refunds a captured PayPal payment (POST /v2/payments/captures/{id}/refund).

update_plan

paypal_rest_adapter

Patches a PayPal Subscription Plan (PATCH /v1/billing/plans/{plan_id}).

paypal_authorize_order

paypal_rest_adapter

Authorizes an intent: "AUTHORIZE" PayPal Checkout Order (POST /v2/checkout/orders/{id}/authorize).

paypal_create_vault_setup_token

paypal_rest_adapter

Creates a PayPal Payment Method Tokens v3 setup token (POST /v3/vault/setup-tokens).


Local Setup & Verification Suite

# 1. Install dependencies
npm install

# 2. Run Jest unit tests (SDK, Conversational Auth, Unified 82-Tool MCP Registry, PDF Receipts)
npm test -- --watchAll=false

# 3. Verify all 82 Unified MCP Tools (46 Official PayPal MCP + 14 REST Adapters + 21 Native) against live PayPal Sandbox
npm run verify:full-paypal-mcp

# 4. Run full 25-stage automated PayPal Sandbox, MCP, Card Lifecycle & Security verification
npm run verify:paypal-full

# 5. Verify all 82 Unified MCP Gateway tools against Cloudflare Worker + Supabase + Vercel
npm run verify:mcp

# 6. Verify Gemini 3.5 Flash-Lite AI, Proposal Security, Guardrails & Conversational Authorization
npm run verify:ai-security

# 7. Run Playwright E2E browser verification against live Vercel deployment
npm run verify:e2e

# 8. Run secret & project isolation scan
npm run scan:secrets

See docs/UNIFIED_MCP_AND_SECURITY_ARCHITECTURE.md for the complete architectural and security specification.


License

MIT License — see LICENSE.

Related MCP Connectors

Related MCP Servers

  • A
    license
    Not graded
    quality
    D
    maintenance
    A Python implementation that enables Large Language Models to interact with PayPal's APIs through function calling, supporting features like invoices, orders, products, subscriptions, and transactions.
    1
    MIT
  • F
    license
    Not graded
    quality
    D
    maintenance
    Enables AI systems to interact with PayPal Braintree payment processing, allowing them to fetch transactions, create payments, and manage customer data via MCP tools.
    4
    -
  • A
    license
    Not graded
    quality
    F
    maintenance
    Enables integration with PayPal APIs for managing invoices, payments, disputes, subscriptions, and more through natural language.
    742 npm
    13
    Apache 2.0