canonical: https://jentic.com/apis/paypal.com/paypal-payments-api-v2

# PayPal Payments API v2

The PayPal Payments API v2 works with the payments that result from a PayPal order, so an application can capture authorized money, refund captured payments, and read the details of authorizations, captures, and refunds. You show an authorization and then capture, void, or reauthorize it, show a capture and refund it, and show a refund. It is designed to be used after an order is created with the PayPal Orders API, which produces the authorization this API acts on.

## For AI agents

Capture, void, and reauthorize PayPal authorized payments, refund captured payments, and show the details of authorizations, captures, and refunds. Authenticates with OAuth2 using the client credentials flow.

## Scope

Does not create orders, store payment methods, or handle payouts. Use for capturing, voiding, reauthorizing, refunding, and showing PayPal payments only.

## Capabilities

- Show the details of an authorized payment
- Capture money from an authorized payment
- Void or reauthorize an authorization
- Show the details of a captured payment
- Refund a captured payment
- Show the details of a refund

## Use cases

### Agent-Driven Payment Capture

An AI agent connected through Jentic captures an authorized PayPal payment once an order is ready to fulfil, then shows the capture to confirm it succeeded. This lets a fulfilment workflow settle payment on request without a human opening the PayPal dashboard.

Example prompt: Capture the authorized payment for this order and confirm the capture succeeded

### Refund Handling

A support workflow refunds a captured PayPal payment when a customer returns an item, then shows the refund to record its status. The agent reads the capture first to refund the right amount against the correct payment.

Example prompt: Refund the captured payment for this order and return the refund status

### Authorization Lifecycle Management

An orders workflow shows an authorization, then voids it when the order is cancelled or reauthorizes it when a capture is delayed past the authorization window. This keeps held funds aligned with the state of the order.

Example prompt: Void the authorization for this cancelled order so the held funds are released

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/v2/payments/authorizations/{authorization_id}` | Show details for authorized payment |
| POST | `/v2/payments/authorizations/{authorization_id}/capture` | Capture authorized payment |
| POST | `/v2/payments/authorizations/{authorization_id}/void` | Void authorized payment |
| GET | `/v2/payments/captures/{capture_id}` | Show captured payment details |
| POST | `/v2/payments/captures/{capture_id}/refund` | Refund captured payment |
| GET | `/v2/payments/refunds/{refund_id}` | Show refund details |

## Key resources

- **Authorizations** — Held funds from an order that can be shown, captured, voided, or reauthorized
- **Captures** — Money taken from an authorization, shown and refundable by id
- **Refunds** — Money returned from a capture, shown by id

## AI readiness

This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.

- **Score:** 47 / 100
- **Maturity:** Foundational
- **Dimensions:**
  - Foundational Compliance: 90 / 100
  - Developer Experience & Jentic Compatibility: 75 / 100
  - AI-Readiness & Agent Experience: 19 / 100
  - Agent Usability: 94 / 100
  - Security: 85 / 100
  - AI Discoverability: 100 / 100
- **View full report:** https://jentic.com/apis/paypal.com/paypal-payments-api-v2/scorecard
- **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/
- **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview

### Score it yourself

Every API in the directory is allowlisted, so you can re-score it with no key required.

- **Score your own API:** https://jentic.com/scorecard.md
- **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md

```sh
npx @jentic/api-scorecard-cli score <openapi-url>
```

## Why Jentic

- **Setup:** Wiring the PayPal Payments API v2 by hand means running the OAuth2 client credentials flow, refreshing the token, and coordinating with the Orders API that produces each authorization. Through Jentic you install once, import PayPal Payments from the API Directory, store the credentials once, and your agent calls it.
- **Permission scoping:** You choose which operations your agent may call, so you can allow showing and capturing payments while leaving refunds and voids out. Because the payment id sits in the URL path, a rule can pin the agent to specific payments, and every call it makes is logged.
- **Credential handling:** Your PayPal client credentials are stored once, encrypted, by your own Jentic One instance, and the access token is obtained and injected at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'capture an authorized payment' or 'refund a capture', and Jentic returns the matching PayPal Payments operation with its input schema so the agent calls the right endpoint without reading the reference docs.

## Related APIs

- **PayPal Orders API v2** — Creates and manages the PayPal orders that produce the authorizations this API captures
- **Mollie API** — European payment platform covering payments, captures, and refunds across methods

## FAQ

### Is there a PayPal Payments MCP server?

You don't need an MCP server to give your agent the PayPal Payments API v2. Jentic connects it directly from the API Directory: import it, store your credentials once, and your agent can capture, refund, and show payments straight away, with no extra server to run and no tool definitions to load into the agent's context.

### Can I limit what my agent is allowed to do with the PayPal Payments API v2?

Yes. You choose which operations your agent may call, so you can allow showing and capturing payments while leaving refunds and voids out. Because the payment id sits in the URL path, a rule can pin the agent to specific payments, and every call it makes is logged.

### What authentication does the PayPal Payments API v2 use?

The PayPal Payments API v2 authenticates with OAuth2 using the client credentials flow per its OpenAPI spec, and requests carry the resulting access token. Through Jentic the client credentials are stored encrypted by your own instance and the token is obtained and added at call time, so they never appear in the agent's prompt or logs.

### Can I refund a payment with the PayPal Payments API v2?

Yes. The API refunds a captured payment and returns the refund so you can record its status. You can also show the capture first to refund the right amount against the correct payment.

### What are the rate limits for the PayPal Payments API v2?

The OpenAPI spec does not specify rate limits for the PayPal Payments API v2. For current limits and integration guidance, see the PayPal developer documentation at https://developer.paypal.com.

### How do I capture a PayPal payment through Jentic?

Import the PayPal Payments API v2 from the Jentic API Directory, then have your agent issue a request such as 'capture the authorized payment for this order'. Jentic matches the intent to the capture operation and returns its input schema so the agent builds the correct request, with your stored credentials injected at call time.