PayPal

PayPal

This connector works with one PayPal business account through the PayPal REST APIs (https://api-m.paypal.com, or https://api-m.sandbox.paypal.com for the sandbox): orders and captures, refunds, invoices (Invoicing v2), the transaction history (Transaction Search), balances, disputes, catalog products, subscription plans and subscriptions, and payout batches. It signs in as your own REST app with its client ID and secret (OAuth2 client credentials); no PayPal user has to click through a consent screen.

Setup (about 10 minutes)

1. Sign in at https://developer.paypal.com with the PayPal business account and open Apps & Credentials. The toggle at the top switches between Sandbox and Live; each has its own apps and keys.
2. Use the Default Application or click Create App, type Merchant, and (in the sandbox) pick the sandbox business account it should act for.
3. Open the app and, under its features, tick what the AI should reach: Invoicing, Transaction Search, Subscriptions (also covers catalog products), Customer Disputes, Payouts. PayPal can take up to 9 hours to grant a newly ticked feature to an app that already issued tokens; until then those calls answer 403 NOT_AUTHORIZED.
4. Copy the Client ID and Secret into PAYPAL_CLIENT_ID and PAYPAL_CLIENT_SECRET.
5. Set PAYPAL_API_URL to https://api-m.sandbox.paypal.com for sandbox keys or https://api-m.paypal.com for live keys. Sandbox keys do not work against the live URL and the other way round (the token request fails with invalid_client).
6. Install. AnythingMCP fetches an access token from PAYPAL_API_URL/v1/oauth2/token with the client ID and secret and renews it before it expires.

Money moves: confirm first. paypal_capture_order, paypal_refund_capture and paypal_cancel_subscription move or stop real money on a live account, and paypal_send_invoice, paypal_remind_invoice and paypal_cancel_invoice email the customer. Before calling any of them, state exactly what will happen (amount, currency, customer, ids) and wait for the user's explicit yes. Pass request_id (any UUID) on captures and refunds so a retry cannot act twice. paypal_delete_draft_invoice is installed switched off.

Orders: paypal_create_order creates an order and returns an approve (or payer-action) link. The buyer must open it and approve before paypal_capture_order can collect the money; capturing an unapproved order fails with 422 ORDER_NOT_APPROVED. Amounts are strings with the currency's decimals: {"currency_code": "EUR", "value": "19.99"}. When an order lists items, amount.breakdown.item_total must equal their sum. The capture id needed for refunds is in purchase_units[].payments.captures[].id.

Refunds: paypal_refund_capture with no amount refunds the whole capture; pass amount for a partial refund. Refunds can only be made on captures, up to the captured amount minus earlier refunds.

Invoices: paypal_create_draft_invoice creates a draft (nothing is emailed); paypal_send_invoice sends it (or, with send_to_recipient: false, just makes it payable through its link). paypal_remind_invoice works on sent, unpaid invoices (at most 2 reminders a day). paypal_cancel_invoice works only on sent invoices; drafts are deleted instead. Invoice numbers are generated if you leave detail.invoice_number out.

Transaction history (paypal_search_transactions): start_date and end_date in RFC 3339 with seconds (2026-10-01T00:00:00Z or 2026-10-01T00:00:00+02:00), at most 31 days apart; for longer periods call once per month. New transactions show up after up to 3 hours, history goes back 3 years. Amount filters use minor units: [500 TO 1005] means 5.00 to 10.05.

Disputes: dispute_state filters by REQUIRED_ACTION (waiting for you), UNDER_PAYPAL_REVIEW, RESOLVED and so on; date filters reach back 180 days.

Subscriptions: plans belong to catalog products (paypal_list_products, paypal_list_plans). paypal_list_subscriptions filters by plan and status. paypal_list_subscription_transactions needs start_time and end_time. paypal_cancel_subscription ends a subscription for good (it cannot be reactivated) and needs a reason.

Paging: invoices and disputes take page and page_size; products, plans and subscriptions allow at most 20 per page; the transaction history up to 500.

Common errors

• 401 invalid_client or invalid_token: wrong client ID or secret, or keys from the other environment than PAYPAL_API_URL.
• 403 NOT_AUTHORIZED / PERMISSION_DENIED: the feature is not ticked on the app (Transaction Search, Invoicing, Disputes, Subscriptions, Payouts), or was ticked less than 9 hours ago.
• 422 UNPROCESSABLE_ENTITY: a business rule, named in details[].issue (ORDER_NOT_APPROVED, AMOUNT_MISMATCH, CAPTURE_FULLY_REFUNDED, ...).
• 429 RATE_LIMIT_REACHED: wait a little and retry.

Out of scope here: card payments and vaulting, webhooks, sending payouts, accepting or answering disputes, editing plans.