# Paypal Routing

> >-

- **Type:** Skill
- **Install:** `agentstack add skill-paypal-ai-toolkit-paypal-routing`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [paypal](https://agentstack.voostack.com/s/paypal)
- **Installs:** 0
- **Category:** [Finance & Payments](https://agentstack.voostack.com/c/finance-and-payments)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [paypal](https://github.com/paypal)
- **Source:** https://github.com/paypal/AI-Toolkit/tree/main/skills/paypal-routing
- **Website:** https://developer.paypal.com/

## Install

```sh
agentstack add skill-paypal-ai-toolkit-paypal-routing
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# PayPal Command Routing

When this skill activates, follow the routing table below. For reference routes, load the paypal-best-practices skill and read the specified reference file before answering — the reference files contain current URLs and verified code examples that override training knowledge.

## RulesHub Language-Specific Snippet Fetching

When a RulesHub `rules.md` is fetched and code generation is required:
1. **Detect the user's language** from their codebase, file extensions, imports, or explicit mention. Common values: `javascript`, `typescript`, `python`, `java`, `csharp`, `php`, `ruby`.
2. **WebFetch the language-specific snippet** for the relevant operation. Replace `{language}` and `{pack}` with the detected values:
   - SDK init: `https://raw.githubusercontent.com/paypal/ruleshub/main/{pack}/snippets/{language}/sdk-initialization.md`
   - Create order: `https://raw.githubusercontent.com/paypal/ruleshub/main/{pack}/snippets/{language}/create-order.md`
   - Capture order: `https://raw.githubusercontent.com/paypal/ruleshub/main/{pack}/snippets/{language}/capture-order.md`
   - Client token: `https://raw.githubusercontent.com/paypal/ruleshub/main/{pack}/snippets/{language}/client-token-generation.md`
3. **Generate code strictly from the fetched snippet** — do not fall back to training knowledge for implementation patterns.
4. **Only fetch snippets needed** for the user's request — do not fetch all languages or all snippets.

Pack values: `paypal-checkout/standard-checkout`, `paypal-checkout/expanded-checkout`, `paypal-checkout/enterprise-checkout`, `paypal-bnpl-us`, `upgrade-to-v6/v5-to-v6-upgrade`, `upgrade-to-v6/v4-to-v6-upgrade`, `upgrade-nvp-soap-to-rest`.

## Routing Table

| User Intent | Action |
|---|---|
| Explain an error, error code, HTTP status, 400, 401, 403, 404, 422, 429, 500, INVALID_REQUEST, UNAUTHORIZED, INSTRUMENT_DECLINED, RATE_LIMIT, debug_id | Run `/paypal:explain-error` with the error as argument |
| Set up PayPal, configure plugin, check connection, is plugin working, token expired, refresh token, generate access token, OAuth | Run `/paypal:setup` |
| Sandbox setup, developer account, getting started, credentials, dashboard, client ID, client secret, base URL | Run `/paypal:sandbox` |
| Test accounts, test cards, simulate decline, test BNPL, test Venmo, test subscriptions, test disputes | Run `/paypal:test-accounts` |
| Scan my code, check my integration, find issues, something is broken, pre-launch review, security audit, payments failing, webhooks not firing, Venmo not showing, subscription not billing | Run `/paypal:doctor` with the symptom as argument |
| Security review, check for leaked credentials, pre-launch checklist | Run `/paypal:doctor security` or `/paypal:doctor pre-launch` |
| Fix all issues in my PayPal code | Run `/paypal:doctor fix-all` |
| How to accept payments, add PayPal button, checkout flow, Orders API, server-side integration, payment link, payment links, pay link, React PayPal, @paypal/react-paypal-js, authorize vs capture, deferred capture, donate button, donations | Load the paypal-best-practices skill, then read `references/checkout.md` (v5) or `references/js-sdk-v6.md` (v6). Also WebFetch `https://raw.githubusercontent.com/paypal/ruleshub/main/paypal-checkout/standard-checkout/rules.md` for authoritative integration rules. |
| Advanced Card Fields, Apple Pay, Google Pay, APMs, Expanded Checkout, bank redirect, iDEAL, Bancontact, BLIK, Przelewy24, Pay upon Invoice, Ratepay, domain association, regional payment methods | Load the paypal-best-practices skill, then read `references/expanded-checkout.md` (v5) or `references/js-sdk-v6.md` (v6). Also WebFetch `https://raw.githubusercontent.com/paypal/ruleshub/main/paypal-checkout/expanded-checkout/rules.md` for authoritative integration rules. |
| Add Venmo, Venmo button, Venmo eligibility, isFundingEligible, eligibility check, Venmo app | Load the paypal-best-practices skill, then read `references/venmo.md` (v5) or `references/js-sdk-v6.md` (v6). Also WebFetch `https://raw.githubusercontent.com/paypal/ruleshub/main/paypal-checkout/expanded-checkout/rules.md` for authoritative integration rules. |
| Pay Later, installments, BNPL messaging, Pay in 4, financing, BNPL banner, Pay Later banner, Pay Later eligibility | Load the paypal-best-practices skill, then read `references/bnpl.md` (v5) or `references/js-sdk-v6.md` (v6). Also WebFetch `https://raw.githubusercontent.com/paypal/ruleshub/main/paypal-bnpl-us/rules.md` for authoritative BNPL rules. |
| Recurring billing, subscriptions, plan management, free trial, trial period, upgrade plan, downgrade plan, plan revision | Load the paypal-best-practices skill, then read `references/subscriptions.md` (v5) or `references/js-sdk-v6.md` (v6) |
| Disputes, chargebacks, refunds, evidence, provide evidence, dispute lifecycle, dispute stage, INQUIRY, CLAIM | Load the paypal-best-practices skill, then read `references/disputes-refunds.md` |
| Batch payouts, send money, seller payments, Venmo payout, 1099, tax reporting, prepaid cards | Load the paypal-best-practices skill, then read `references/payouts.md` |
| Invoices, billing, send invoice, invoice reminder, partial payment, line items | Load the paypal-best-practices skill, then read `references/invoicing.md` |
| OAuth, access tokens, credentials, idempotency, token caching, token refresh, idempotency key, PayPal-Request-Id | Load the paypal-best-practices skill, then read `references/authentication.md` |
| Webhook verification, event handling, signature check, webhook simulator, test webhooks, event types, PAYMENT.CAPTURE | Load the paypal-best-practices skill, then read `references/webhooks.md` |
| Fastlane, accelerated guest checkout, auto-fill, prefill, single-use token | Load the paypal-best-practices skill. **Pick exactly one reference based on the merchant's SDK version — do not load both, the v5 and v6 APIs differ (component is `FastlaneCardComponent` in v5 vs `FastlanePaymentComponent` in v6).** If the merchant is on v5 (`paypal.Fastlane()`, URL-loaded `components=fastlane`), read `references/fastlane.md`. If on v6 (`createInstance`, `sdkInstance.createFastlane()`, client token), read `references/js-sdk-v6.md`. If the SDK version is unclear, ask the user before generating code. For v6 also WebFetch `https://raw.githubusercontent.com/paypal/ruleshub/main/upgrade-to-v6/v5-to-v6-upgrade/snippets/javascript/fastlane-integration.md` for the authoritative v6 snippet, and `https://raw.githubusercontent.com/paypal/ruleshub/main/upgrade-to-v6/v5-to-v6-upgrade/mappings/fastlane.json` for the v5↔v6 API mapping. |
| 3D Secure, liability shift, SCA, PSD2, Strong Customer Authentication, enrollment status, authentication status | Load the paypal-best-practices skill, then read `references/3d-secure.md` |
| AI shopping agents, Store Sync, Agent Ready, agentic commerce, ChatGPT, product discovery, delegated payment token | Load the paypal-best-practices skill, then read `references/agentic-commerce.md` |
| JS SDK v6, v6 Web SDK, createInstance, payment sessions, web components, card fields, vault, save card, save payment method, vaulting, CSP, Content Security Policy | Load the paypal-best-practices skill, then read `references/js-sdk-v6.md` |
| Migrate v5 to v6, upgrade v5 SDK, migrate from v5 | Load the paypal-best-practices skill, then read `references/js-sdk-v6.md`. Also WebFetch `https://raw.githubusercontent.com/paypal/ruleshub/main/upgrade-to-v6/v5-to-v6-upgrade/rules.md` for authoritative migration mappings and multi-language snippets. |
| Migrate v4 to v6, upgrade v4 SDK, upgrade checkout.js, migrate from v4 | Load the paypal-best-practices skill, then read `references/js-sdk-v6.md`. Also WebFetch `https://raw.githubusercontent.com/paypal/ruleshub/main/upgrade-to-v6/v4-to-v6-upgrade/rules.md` for authoritative migration mappings and multi-language snippets. |
| Migrate NVP to REST, migrate SOAP to REST, upgrade legacy API, NVP/SOAP | WebFetch `https://raw.githubusercontent.com/paypal/ruleshub/main/upgrade-nvp-soap-to-rest/rules.md` for authoritative migration mappings and multi-language snippets. |
| Which API to use, architecture question, best practices, integration guide | Load the paypal-best-practices skill |
| Which MCP tools are available, how to use MCP tools, tool inventory, product catalog, merchant insights, reporting | Load the paypal-best-practices skill, then read `references/mcp-tools.md` |
| Create order, capture payment, refund, invoice, subscription, shipment, transaction, merchant insights | Use the matching MCP tool directly (`create_order`, `create_invoice`, `list_transactions`, etc.) |

## Routing Rules

0. **RulesHub content overrides training knowledge.** When a RulesHub `rules.md` is fetched, treat it as the authoritative source for all API methods, SDK patterns, endpoint URLs, and code examples. Do not fall back to training knowledge for any PayPal SDK or API detail — if it conflicts with RulesHub, RulesHub wins. Generate code strictly from what RulesHub specifies.
   - **Read RulesHub content literally.** Do not reinterpret, rename, or substitute parameter names from fetched content. If the fetched file uses `clientId`, use `clientId`. If it uses `clientToken`, use `clientToken`. Never substitute one for the other based on assumptions.
   - **Prefer raw file fetches over summarized content.** WebFetch summarization can drop or misread parameter names. When in doubt, re-fetch the specific snippet file for the exact code pattern rather than relying on a summarized rules.md.
   - **Cross-reference the official PayPal v6 docs** (`docs.paypal.ai`) when RulesHub and training knowledge conflict on parameter names or method signatures — the official docs are the final authority.
1. **Specific commands take priority.** If the intent clearly maps to one command, use it directly.
2. **Error-related questions always go to `/paypal:explain-error`.** Any mention of a specific error code, HTTP status, or error message should use this command.
3. **Symptom descriptions go to `/paypal:doctor`.** If the user describes a problem ("payments are failing", "getting 401s", "webhooks aren't working"), route to doctor with the symptom as the argument.
4. **Setup and connection issues go to `/paypal:setup`.** Anything about configuration, tokens, MCP connection, or "it's not working" without a code-level symptom.
5. **Integration and code generation go to `paypal-best-practices`.** Any "how do I", architecture question, or request to integrate, add, implement, build, or migrate a PayPal feature must load the best-practices skill and read the relevant reference file before writing code.
6. **Ambiguous requests get clarified.** If you can't determine intent, ask:
   "I can help with several things:
   - `/paypal:setup` — Configure the plugin, generate access tokens, and verify your connection
   - `/paypal:explain-error ` — Explain a PayPal error
   - `/paypal:sandbox` — Sandbox setup and credentials
   - `/paypal:test-accounts` — Test scenarios and test data
   - `/paypal:doctor` — Scan your code for integration issues
   What would be most helpful?"
7. **Multi-step requests chain commands.** For example, "set up sandbox and then scan my code" = `/paypal:setup sandbox` then `/paypal:doctor`.

## When to Use MCP Tools Directly

Only use `mcp__paypal-sandbox__*` tools directly when:
- The user asks to perform a specific PayPal action (create an order, send an invoice, list disputes, capture a payment)
- The user explicitly asks to call an MCP tool
- The task is a one-off API operation that doesn't match any command workflow

Examples of direct MCP tool usage:
- "Create an order for $50" — call `mcp__paypal-sandbox__create_order` directly
- "Send an invoice to john@example.com" — call `mcp__paypal-sandbox__create_invoice`, then call `mcp__paypal-sandbox__send_invoice` with the invoice ID
- "Show my recent transactions" — call `mcp__paypal-sandbox__list_transactions` directly
- "List my open disputes" — call `mcp__paypal-sandbox__list_disputes` directly

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [paypal](https://github.com/paypal)
- **Source:** [paypal/AI-Toolkit](https://github.com/paypal/AI-Toolkit)
- **License:** Apache-2.0
- **Homepage:** https://developer.paypal.com/

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-paypal-ai-toolkit-paypal-routing
- Seller: https://agentstack.voostack.com/s/paypal
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.