canonical: https://jentic.com/apis/paypal.com

# PayPal APIs

PayPal exposes its payments platform as a family of REST APIs. An agent can create and capture one-time orders, run recurring subscriptions, send and track invoices, save payment methods, disburse batch payouts, manage disputes, and subscribe to event webhooks. The one-time checkout flow spans the Orders and Payments APIs, recurring billing is built on Catalog Products and Subscriptions, and every API shares one set of OAuth credentials. The specifications are PayPal's own.

## For AI agents

Create and capture PayPal orders, run subscriptions, send invoices, save payment methods, issue payouts, manage disputes, and subscribe to webhooks across twelve APIs with one set of OAuth credentials.

## Scope

Use for: PayPal account payments, billing, disbursement, and dispute handling

Not supported:
- In-person card readers
- Bank account opening
- Tax filing
- Accounting ledgers

## APIs

| API | Category | Endpoints | Description |
| --- | --- | --- | --- |
| Invoices | payments | 22 | Programmatically create draft invoice, list invoices. |
| Subscriptions | payments | 16 | Programmatically create plan, list plans. |
| Webhooks Management | communications | 16 | Programmatically create webhook, list webhooks. |
| Disputes | payments | 15 | Programmatically list disputes, show dispute details. |
| Orders | payments | 9 | Create and capture PayPal payment orders, authorize funds, and attach shipping trackers. |
| Payments | payments | 7 | Programmatically show details for authorized payment, capture authorized payment. |
| Payment Method Tokens | payments | 6 | Programmatically create payment token for a given payment source, list all payment tokens. |
| Shipment Tracking | e-commerce | 5 | Programmatically add tracking information for multiple paypal transactions, add tracking information for paypal transaction. |
| Catalog Products | e-commerce | 4 | Programmatically create product, list products. |
| Payouts | payments | 4 | Programmatically create batch payout, show payout batch details. |
| Partner Referrals | payments | 2 | Programmatically create partner referral, show referral data. |
| Transaction Search | payments | 2 | Programmatically list transactions, list all balances. |

## Which API to use

| Need | API | Why |
| --- | --- | --- |
| Take a one-time payment at checkout | paypal-orders-api-v2 | Creates, authorizes, and captures a single order across wallet, card, and local payment methods. |
| Refund, void, or reauthorize a captured payment after checkout | paypal-payments | Operates on the authorization and capture ids an order produces, including issuing refunds. |
| Charge a customer on a recurring schedule | paypal-subscriptions-api-v1 | Defines billing plans and subscriptions for recurring charges on goods or services. |
| Define the products that subscription plans are built on | paypal-catalog-products-v1 | Creates the product records a billing plan references. |
| Bill a customer with an itemized invoice | paypal-invoicing-api-v2 | Creates, sends, and tracks invoices that a customer pays through a hosted link. |
| Pay many recipients at once | paypal-payouts-v1 | Sends batch payouts to PayPal or Venmo recipients in a single call. |
| Save a customer's payment method for later charges | paypal-vault-payment-tokens-v3 | Exchanges a setup token for a stored payment token you reuse in orders and subscriptions. |
| Attach carrier tracking to completed orders | paypal-tracking-v1 | Adds shipment tracking numbers, which also support seller protection. |
| Respond to and resolve customer disputes | paypal-customer-disputes-v1 | Lists disputes and manages evidence, appeals, and settlement through their lifecycle. |
| Reconcile transaction history and balances | paypal-transaction-search-v1 | Reports account transactions and balances for accounting and reconciliation. |
| Get notified when events happen | paypal-webhooks-management-v1 | Subscribes a listener to events such as an order captured or an invoice paid. |
| Onboard seller accounts onto a marketplace platform | paypal-partner-referrals-v2 | Adds seller accounts to a platform; available to approved partners only. |

## Cross-API use cases

### Checkout with refund and dispute handling

Take a payment and handle what comes after it. The agent creates and captures an order with the Orders API, then uses the Payments API on the resulting capture id to issue a partial or full refund when needed. If a buyer opens a dispute, the agent works it through the Disputes API by providing evidence or accepting the claim. One credential covers the whole path from sale to resolution.

Example prompt: Capture an authorized order, refund part of the capture through the Payments API, and if a dispute is opened on it, retrieve the dispute and submit evidence.

### Recurring subscription with a saved payment method

Stand up recurring billing for a product. The agent creates a product with the Catalog Products API, saves the customer's payment method as a reusable token with the Payment Method Tokens API, and then creates and activates a billing plan and subscription with the Subscriptions API that references both. The subscription charges on schedule without the customer re-entering details.

Example prompt: Create a product, mint a stored payment token from a setup token, create and activate a billing plan for that product, then start a subscription against the plan.

### Fulfillment and vendor payout

Complete an order, ship it, and pay a supplier. The agent captures the order with the Orders API, attaches carrier tracking with the Shipment Tracking API so the sale qualifies for seller protection, and disburses the supplier's share with the Payouts API in a single batch call. The sequence covers the money in and the money out.

Example prompt: Capture an order, add a carrier tracking number for it through the Shipment Tracking API, and send a batch payout to the supplier, then confirm the payout batch status.

### Event-driven reconciliation

Keep an accounting record in step with what happens on the account. The agent subscribes to events with the Webhooks Management API, so it is notified when an order is captured, an invoice is paid, or a payout completes, and reconciles each event against the account's history with the Transaction Search API. The two together give the agent both the live signal and the ledger.

Example prompt: Create a webhook subscribing to payment-captured and invoice-paid events, and on each event, look up the matching transactions through the Transaction Search API.

## Why Jentic

- **Setup:** Wiring PayPal by hand means learning its OAuth 2.0 client-credentials flow, exchanging and refreshing bearer tokens, and handling the split between the Orders and Payments APIs. Through Jentic you install once, import the PayPal APIs from the API Directory, store your credentials once, and your agent calls them.
- **Permission scoping:** Most PayPal operations put the resource id in the URL path, so a rule can pin your agent to the operations you allow, such as capturing orders and issuing refunds but never sending a payout. The reporting and collection-create endpoints do not carry a resource id in the path, so for those a rule bounds which operations the agent may call rather than a single resource.
- **Credential handling:** Your PayPal OAuth client id and secret are stored encrypted by your own Jentic One instance and injected at execution time, with the bearer token exchanged for you. The raw credentials never enter the agent's prompt, logs, or context.
- **Discovery method:** An agent searches by intent, for example 'refund a captured payment', and Jentic returns the matching operation from across the twelve PayPal APIs with its input schema, so the agent calls the right API without knowing which one it is.

## Related vendors

- **Stripe** — Payments platform with a comparable API surface for one-time and recurring charges; the common alternative when evaluating payment providers.
- **Square** — Payments and commerce APIs with a strong in-person and point-of-sale side, which PayPal's REST APIs do not cover.
- **Adyen** — Global payment processing API aimed at larger platforms; an alternative when you need many local payment methods across regions.

## FAQ

### Can AI agents use PayPal APIs?

Yes. All twelve PayPal APIs have OpenAPI specifications in the Jentic API Directory, so an agent can discover and call them by intent. Through Jentic the agent searches for an operation, loads its schema, and executes it. Install Jentic One (self-hosted) from its GitHub repo to get started.

### Is there a PayPal MCP server?

You do not need an MCP server to give your agent PayPal. Jentic connects the PayPal APIs directly from the API Directory: import the ones you need, store your OAuth credentials once, and your agent can create orders, issue refunds, and manage subscriptions without loading another server's tool definitions into its context.

### Do I need separate credentials for each PayPal API?

No. PayPal uses one set of OAuth 2.0 credentials across all of its APIs. You create a client id and secret once, exchange them for a bearer token, and the same token is accepted by every API, differing only by scope. Through Jentic the credentials are stored encrypted and injected at execution time, so they never enter the agent's context.

### Can I limit what my agent is allowed to do with PayPal?

Yes. You choose which operations the agent may call through Jentic, and most PayPal operations put the resource id in the URL path, so a rule can pin the agent to specific actions such as capturing an order but not issuing a payout. The reporting endpoints filter by query string, so for those a rule bounds which operations the agent may call rather than a single resource.

### How do I connect my agent to PayPal?

Install Jentic One on your own infrastructure from its GitHub repo, register your PayPal OAuth credentials with it once, and add the PayPal APIs from the Jentic API Directory. Your agent then searches by intent, for example 'capture a PayPal order', and Jentic returns the matching operation with its input schema.

### What is the difference between the Orders API and the Subscriptions API?

Use the Orders API for one-time payments: it creates, authorizes, and captures a single order. Use the Subscriptions API for recurring charges: it defines billing plans and subscriptions that charge on a schedule. For post-sale actions on a one-time payment, such as refunds, you use the Payments API on the capture the order produced.

### What can I build by combining PayPal APIs?

Common patterns chain the APIs across a transaction's life: capture an order and refund or dispute it through the Payments and Disputes APIs, or build recurring billing from Catalog Products, saved payment tokens, and Subscriptions. One set of OAuth credentials covers every API a workflow touches.