--- name: iblai-connect-paypal description: "Read and write PayPal data through the PayPal REST APIs (Orders v2, Invoicing v2 and others) and expose it to an ibl.ai agent as an MCP tool. Use when the user asks an agent to work with PayPal data, or to set up a PayPal MCP connection on ibl.ai." metadata: kind: guide --- # PayPal connector for AI agents > A starting point maintained on ibl.ai at https://ibl.ai/developer/connectors/paypal — not part of the iblai/vibe repository. Checked against PayPal's documentation on October 20, 2026; test it against your own PayPal setup before you rely on it. Online payments platform. A PayPal business account holds orders and captured payments, refunds, invoices, disputes, subscriptions, product catalog entries and transaction reports. ## Auth & conventions - **API:** PayPal REST APIs (Orders v2, Invoicing v2 and others) (REST). REST APIs for checkout orders (create, authorize, capture), payments and refunds, invoicing, disputes, subscriptions, catalog products and transaction reporting. - **Base URL:** https://api-m.paypal.com (sandbox: https://api-m.sandbox.paypal.com) - **Access:** Public, self-serve. Any developer logs into the PayPal Developer Dashboard, opens Apps & Credentials, and creates a REST app to get a client ID and secret. Sandbox business and personal test accounts come with the dashboard. - **Auth:** OAuth 2.0 client credentials. POST the Base64-encoded client ID and secret to /v1/oauth2/token with grant_type=client_credentials to get a bearer access token. Cache and reuse the token until it expires instead of requesting one per call. - **Limits:** PayPal does not publish a rate-limit policy; it may temporarily limit traffic that looks abusive and returns HTTP 429 RATE_LIMIT_REACHED. Avoid polling (use webhooks) and reuse cached OAuth tokens. - Keep PayPal credentials in environment variables or the ibl.ai credential store. Never print a token in chat and never commit one to a file. - Destructive or outward-facing calls are marked **Confirm with the user first** — do. ## Reads - **Order details** — GET /v2/checkout/orders/{id} shows an order's status, amounts and payer. - **Invoices** — GET /v2/invoicing/invoices lists invoices; POST /v2/invoicing/search-invoices filters them. - **Disputes** — Disputes API lists and shows customer disputes and their status. - **Transaction reports** — Reporting tools list transactions for a date range. ## Writes - **Create order** — POST /v2/checkout/orders creates an order for the payer to approve. - **Capture payment** — POST /v2/checkout/orders/{id}/capture captures payment for an approved order. **Confirm with the user first.** - **Create draft invoice** — POST /v2/invoicing/invoices creates a draft invoice. - **Send invoice** — POST /v2/invoicing/invoices/{invoice_id}/send sends or schedules the invoice to the customer. **Confirm with the user first.** - **Cancel invoice** — POST /v2/invoicing/invoices/{invoice_id}/cancel cancels a sent invoice. **Confirm with the user first.** ## Expose it to an ibl.ai agent (MCP) PayPal publishes an official MCP server, PayPal MCP Server (https://developer.paypal.com/tools/mcp-server/). Register it below as-is, or host your own server that wraps the calls in this skill. First install the ibl.ai platform skills and connect your organization (writes `IBLAI_ORG`, `IBLAI_USERNAME` and `IBLAI_API_KEY` to `.env`): ```bash npx skills add iblai/vibe --all # then, in your coding agent: /iblai-api-login ``` Every call below sends `Authorization: Api-Token $IBLAI_API_KEY`. 1. **Register the server** — `POST https://api.iblai.app/dm/api/ai-mentor/orgs/$IBLAI_ORG/users/$IBLAI_USERNAME/mcp-servers/` with `name`, `url`, `transport` (`sse` | `websocket` | `streamable_http`) and `auth_type` (`none` | `token` | `oauth2`). Capture the returned `id`. - For an API key or service credential use `auth_type=token` with `auth_scope=platform` for one key across the organization, or scope it to a single agent for one key per agent. 2. **Create the connection** — `POST https://api.iblai.app/dm/api/ai-mentor/orgs/$IBLAI_ORG/users/$IBLAI_USERNAME/mcp-server-connections/` with `server`, `scope` (`platform` | `mentor` | `user`), `auth_type`, and either `credentials` + `authorization_scheme` or a `connected_service` id for OAuth. Credentials are masked on read; never send a masked value back. 3. **Enable it on the agent** — `GET https://api.iblai.app/dm/api/ai-mentor/orgs/$IBLAI_ORG/users/$IBLAI_USERNAME/mentors/{agent_id}/settings/`, add `mcp-tool` to `tool_slugs` and the server id to `mcp_servers`, then `PATCH` the full lists back. They are replaced, not merged. Full reference: https://ibl.ai/developer/platform/mcp/mcp-connections and the `/iblai-api-agent-mcp` skill. ## Example prompts - "List unpaid PayPal invoices older than 30 days with customer and amount" - "Create and send a PayPal invoice to sam@example.com for $275 of design work" - "Show the status of PayPal order 5O190127TN364715T" - "Which PayPal disputes are still open and when is each response due?" ## Guardrails - Holds PCI cardholder-related payment data and payer personal data (names, emails, shipping addresses). Captures, refunds and sent invoices move money or reach customers. - Request the narrowest PayPal scopes or role the task needs, and prefer a read-only credential for agents that only answer questions. - Return the fields the user asked for, not whole records; do not paste personal data into chat that the user did not request. - Before any write, show the user exactly what will change and wait for a yes. - Respect the documented limits above: page through results and back off on rate-limit responses instead of retrying in a loop. ## References - PayPal REST API authentication: https://developer.paypal.com/api/rest/ - PayPal Orders v2 API: https://developer.paypal.com/docs/api/orders/v2/ - PayPal MCP server: https://developer.paypal.com/tools/mcp-server/ - PayPal MCP Server: https://developer.paypal.com/tools/mcp-server/ - This connector on ibl.ai: https://ibl.ai/developer/connectors/paypal - ibl.ai MCP server connections: https://ibl.ai/developer/platform/mcp/mcp-connections