# PayPal MCP > PayPal MCP Server manages your e-commerce payments through your AI client. It lets you programmatically create orders, reserve funds via `authorize_order`, process captures, issue refunds using `refund_capture`, and manage recurring subscriptions—all from a single chat interface. ## Overview - **Category:** money-moves - **Price:** Free - **Tags:** checkout, refunds, subscription-billing, transaction-management, pci-compliance, api-integration ## Description This server lets your AI client manage every part of your e-commerce payment lifecycle through PayPal's official API. You don't gotta leave your chat window to process payments, issue refunds, or handle recurring billing. It's built for transactional accuracy, giving you direct access to the core functions that move money and track orders. ### Creating and Querying Orders To start a sale, use `create_order` to generate a new, structured PayPal checkout order ID. You can then check on any existing transaction by calling `get_order_details`, which pulls all relevant information for that specific Order ID. This gives you immediate visibility into whether an order is pending or finalized. ### Authorizing and Capturing Funds The payment process starts when you reserve the money. You use `authorize_order` to hold funds on a customer's payment method for a specified amount; this keeps the money locked down until you're ready to finalize it. When you've confirmed the goods shipped or the service was delivered, you run with the finalization. Use `capture_authorization` to move those reserved funds into your merchant account, completing the sale. If you generate an order but never complete the purchase, you can call `void_authorization` to release the reserved money back to the customer's card. ### Handling Refunds and Adjustments If a return happens or a payment needs correcting, you use `refund_capture`. This function issues a refund directly against a specific Capture ID, ensuring the credit goes back to the customer for an already processed transaction. It’s your mechanism for maintaining financial accountability across all refunds. ### Managing Subscriptions and Billing Status For recurring revenue, you've got full control over subscription lifecycles. You can use `get_subscription` to fetch the current status and detailed billing metadata for any active account. If a customer needs a break, you have two options: you can temporarily stop their service and payments by calling `suspend_subscription`, or if the relationship is ending, you immediately terminate all recurring charges using `cancel_subscription`. These tools let you manage the entire state of billing, from active to suspended to terminated. ## Tools ### authorize_order Reserves funds on a customer's payment method for an order amount. ### cancel_subscription Immediately terminates an active recurring subscription. ### capture_authorization Finalizes the transaction by moving reserved funds into the merchant account. ### capture_order Processes and finalizes payment for a new checkout order. ### create_order Generates a brand new, structured PayPal checkout order ID. ### get_order_details Retrieves all details for a specific PayPal Order ID. ### get_subscription Fetches the current status and billing metadata for a recurring subscription. ### refund_capture Issues a refund against an already captured transaction ID. ### suspend_subscription Temporarily halts billing and services for an active subscription account. ### void_authorization Releases reserved funds when a payment authorization is no longer needed. ## Prompt Examples **Prompt:** ``` Create a strictly bounded new order array configuring explicit amounts totaling 50.00 USD. ``` **Response:** ``` Invoked natively checking payload bounds. Operation success encapsulating order explicitly. Returned native Order ID is '98xx23'. Financial bounds verified natively gracefully awaiting further capture processes explicitly. ``` **Prompt:** ``` Execute native limits to capture order logically tracking specific Order ID 'xy2z9'. ``` **Response:** ``` Mapped explicit endpoints requesting execution. Payload captured parameters successfully. Final 'COMPLETED' native limit returned. The Capture ID logged is explicitly 'zz9xx82'. Check JSON array structurally if needed. ``` **Prompt:** ``` Verify explicit details mapping boundaries for the active subscribed model ID 's99a'. ``` **Response:** ``` Commanded tracking parameters hitting structural bounds `get_subscription`. Payload bounds returned efficiently. Current logical profile natively sits actively running ('ACTIVE'). Next mapped explicitly invoice limits generate safely on Sep 14. ``` ## Capabilities ### Create and query checkout orders Starts a new PayPal order, or fetches specific details about an existing order ID. ### Authorize funds for an order Reserves money on the customer's card for a specified amount, pending final capture. ### Capture authorized payments Finalizes the payment by moving reserved funds from the authorization to the merchant account. ### Process full or partial refunds Issues a refund against a previously captured payment using a specific Capture ID. ### Manage subscriptions status Retrieves details, suspends service, or cancels recurring billing accounts. ### Void pending authorizations Cancels a reserved payment amount that was never captured. ## Use Cases ### Handling an Immediate Refund A customer claims they were double-billed. Instead of logging into the admin panel, you ask your agent to run `get_order_details` using the Order ID provided by the customer. Once verified, the agent executes `refund_capture` against the captured payment ID, confirming the refund instantly. ### Takedown for Suspended Accounts A user’s account violates terms. The standard workflow is to manually disable them and check billing status. With the MCP Server, you run `get_subscription` first; if it's active, you execute `suspend_subscription` immediately via a single command. ### Testing an Abandoned Cart Flow Your QA team needs to test what happens when a user authorizes payment but never completes the purchase. They run `authorize_order`, confirm the funds are reserved, and then use `void_authorization` to cleanly release the held amount. ### Auditing Past Transactions A financial auditor needs proof of a specific $50 payment from last month. You ask your agent to query for all orders on that date, use `get_order_details` on the relevant Order ID, and then check if the funds were captured using `capture_order`. ## Benefits - Manage disputes faster. Instead of manual lookups, use `get_order_details` to instantly verify an order's status and find the necessary transaction IDs. - Handle cancellations gracefully. Don't just delete records; call `void_authorization` when a payment reservation is incomplete, keeping your ledger clean. - Control recurring revenue. Use `get_subscription` to check if a user’s billing cycle is 'Active', and then use `suspend_subscription` if they hit a service limit. - Automate refunds securely. When a refund is needed, calling `refund_capture` against the specific Capture ID ensures you are always working with the correct financial record. - Simplify initial checkout. Use `create_order` to generate the necessary payment object upfront, giving your agent a starting point for the entire transaction flow. - Build robust test environments. You can simulate full transactions—`authorize_order` then `capture_authorization`—without touching live money. ## How It Works The bottom line is that you get full control over your payment flow by simply telling your agent what needs to happen, without writing boilerplate API code. 1. Subscribe to the server and provide your specific PayPal Sandbox or Live Client ID, along with your Secret credentials. 2. Your AI client sends an explicit financial payload (e.g., asking to `create_order` for $100). 3. The tool executes the API call against PayPal's system and returns a verified status code and transaction ID. ## Frequently Asked Questions **How do I start a new payment using create_order?** You call `create_order` with the required line items and total amount. This generates the unique Order ID needed for all subsequent steps, like authorization. **What is the difference between authorize_order and capture_authorization?** `authorize_order` reserves funds (like holding a credit card); it doesn't move money. `capture_authorization` actually moves those reserved funds into your merchant account. **Can I refund an order without knowing the capture ID?** No. You must first use `get_order_details` to find the specific Capture ID linked to that Order ID before running `refund_capture`. The tool requires this precise identifier. **How do I check if a subscription is still active using get_subscription?** You run `get_subscription` and inspect the returned metadata fields. This tells you the current status (e.g., 'ACTIVE' or 'SUSPENDED') and when the next billing cycle hits. **When should I use void_authorization?** `void_authorization` is for payments that were authorized but never captured—meaning the transaction fell apart before completion. It safely releases the reserved funds without needing a refund process. **What credentials must I provide to use the `capture_order` tool?** You must configure your PayPal Sandbox or Live Client ID and Secret parameters. The agent uses these explicit keys for authentication, ensuring every payment capture payload executes securely against your designated merchant account. **How do I temporarily pause a recurring billing cycle using `suspend_subscription`?** You call the `suspend_subscription` tool with the subscription ID. This immediately halts all future billing cycles without canceling the user's account, allowing you to easily resume service later. **If I need a full audit trail of an order, how do I use `get_order_details`?** Use `get_order_details` and input the specific Order ID. This returns a complete record showing every status change—from creation through authorization to capture or void—essential for compliance checks. **Can I switch explicitly between testing (Sandbox) and Live operational arrays natively?** Yes. The environment parameters expose an explicitly bounded flag globally allowing configuration arrays parsing seamlessly switching requests between Sandbox limits and Live endpoints. Ensure your keys correspond properly. **Is it possible to list explicit mass payment histories filtering natively across accounts?** This particular structural node maps explicit order manipulation limits. Operations resolving broad search queries or complex un-bounded transaction logs aren't exposed natively in this immediate abstraction scope for precise object handling. **Which parameter natively identifies bounds when generating refunds?** Proper financial refunds are mapped utilizing strictly captured payment node structures. You must pass the specific Capture ID explicitly retrieved from logging the 'capture_order' action properly, not just initial limit bounds.