Use the PayPal Agent Toolkit to expose PayPal payment operations as LLM tool calls so your AI agent can create, capture, and refund orders via function calling
Install the PayPal Agent Toolkit from npm or PyPI (the toolkit is open-source and published by PayPal); initialize it with your PayPal client ID and secret from the PayPal Developer Dashboard.
Register the toolkit's tool definitions with your LLM framework (OpenAI Agents SDK, LangChain, or CrewAI); the toolkit exposes PayPal APIs as structured function-call schemas including create_order, capture_payment, create_refund, and get_order_details.
When the agent needs to initiate a purchase, call create_order with amount, currency, and item details; PayPal returns an order ID and an approval URL — for agent-autonomous flows using pre-authorized payment methods, approval happens without redirecting the user.
After the buyer's payment method is confirmed, call capture_payment with the order ID to settle the transaction; handle INSTRUMENT_DECLINED and PAYER_ACTION_REQUIRED errors explicitly as they require user intervention.
For returns, call create_refund with the capture ID and amount; PayPal supports partial refunds — specify the amount field to refund a subset of the capture total.
Known gotchas
The PayPal Agent Toolkit exposes REST API operations as tool calls; it does not implement ACP or AP2 protocol flows — it is a direct PayPal REST API wrapper for agent use, not a protocol adapter.
PayPal's PYUSD stablecoin is supported by the toolkit for merchants in supported regions; standard PayPal wallet and card payments are universally supported, but PYUSD availability varies by geography.
Autonomous agent flows that skip buyer redirect for payment approval require the buyer to have pre-authorized the agent via a PayPal consent flow; without prior consent, capture_payment will return PAYER_ACTION_REQUIRED.
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp