Paypal

PayPal

Same setup mechanics as [[openai]] — secret-mechanism, vault-backed — but PayPal needs two credentials (client_id + client_secret) and uses OAuth client_credentials to mint a short-lived bearer token. This file covers what's different from [[stripe]]: the OAuth dance, sandbox vs live separation, and which mutations require explicit user confirmation.

Quick Reference

Catalogue note. The integration catalogue today exposes one secretEnvKey per service. Until that's extended, the recommended convention is two separate accountKeys on the same service: paypal:client_id and paypal:secret. Resolve both via integration_secrets and pair them in code (see snippet below). The cleaner alternative is a small extension to catalogue.ts and the connect dialog to accept two fields — file a ticket against the integration slice if you need it.

Setting up

1. Create a sandbox app at developer.paypal.com → Apps & Credentials → Sandbox → Create App. Copy Client ID and Secret.
2. Open the admin UI at /integrations → PayPal → accountKey sandbox → paste client_id. Repeat with accountKey sandbox-secret → paste secret.
3. Verify the credentials by exchanging them for a token (see "Minting a token" below). Don't promote to live until at least one full create → approve → capture cycle works in sandbox.
4. For production, repeat the steps with the live app credentials and use accountKey live / live-secret.

Sandbox and live are separate PayPal accounts — orders never cross. Keep them as distinct accountKeys so the agent has to pick deliberately.

Minting a token

The runtime resolves both secrets, you Base64 them, and trade for a bearer:

const { env } = await integration_secrets({ service: 'paypal' })

// Use the explicit account when both sandbox and live are connected.
// Fall back to the default alias (most-recently-updated) otherwise.
const clientId = env.PAYPAL_CLIENT_ID_SANDBOX ?? env.PAYPAL_CLIENT_ID
const clientSecret = env.PAYPAL_CLIENT_SECRET_SANDBOX ?? env.PAYPAL_CLIENT_SECRET
if (!clientId || !clientSecret) {
  return ctx.send(
    'PayPal isn't connected. Open /integrations and add a PayPal client_id + secret first.',
  )
}

const base = clientId.startsWith('A') // live ids start with A (sandbox starts with A too — use accountKey to decide)
  ? 'https://api-m.paypal.com'
  : 'https://api-m.sandbox.paypal.com'

const auth = Buffer.from(`${clientId}:${clientSecret}`).toString('base64')
const tokenRes = await fetch(`${base}/v1/oauth2/token`, {
  method: 'POST',
  headers: {
    Authorization: `Basic ${auth}`,
    'Content-Type': 'application/x-www-form-urlencoded',
  },
  body: 'grant_type=client_credentials',
})
const { access_token } = await tokenRes.json()

The base URL choice is not derivable from the client_id prefix — both sandbox and live ids start with A. Pick the base from the accountKey (sandbox → sandbox base, live → live base) and surface a clear error if the agent is ambiguous about which account it wants.

Each tool call mints a fresh token. Don't try to cache across calls — the runtime doesn't give tools a per-user cache, and 9-hour tokens aren't worth the persistence work.

Calling the API

Orders v2 is the only API a runtime agent should touch directly. Everything else (Subscriptions, Payouts, Disputes) is either covered by Orders or needs human review.

// Create an order (intent: CAPTURE for one-step sale, AUTHORIZE for two-step).
const res = await fetch(`${base}/v2/checkout/orders`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${access_token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    intent: 'CAPTURE',
    purchase_units: [{
      reference_id: ref,
      amount: { currency_code: 'USD', value: '100.00' },
      description,
    }],
  }),
})
const order = await res.json()
// order.id e.g. "7MW20236HK..." — store it; orders expire after 3h.

Then surface order.id and the approval link (from order.links[].href where rel === 'approve') to the user. The agent never approves the order itself — the buyer does, in their PayPal session. Once approved, capture:

await fetch(`${base}/v2/checkout/orders/${order.id}/capture`, {
  method: 'POST',
  headers: { Authorization: `Bearer ${access_token}` },
})

Safety rails

Charging, capturing, and refunding are irreversible — wrap every mutation in an explicit user confirmation, same pattern as [[stripe]]:

await ctx.send(
  `About to capture ${formatMoney(amount)} on PayPal order ${order.id}. Reply "confirm capture" to proceed.`,
)
// ... wait for the user's "confirm capture" message ...
await fetch(`${base}/v2/checkout/orders/${order.id}/capture`, {
  method: 'POST',
  headers: { Authorization: `Bearer ${access_token}` },
})

Mutating calls that always require confirmation:

• POST /v2/checkout/orders/{id}/capture — charges the buyer
• POST /v2/payments/captures/{id}/refund — issues a refund
• POST /v2/payments/authorizations/{id}/void — voids an authorization
• POST /v1/payments/payouts — sends money out

Read-only flows (GET /v2/checkout/orders/{id}, listing transactions for a date range) don't need confirmation, but watch out for date filters that return huge result sets — paginate, don't dump.

3D Secure / SCA is mostly a frontend concern — the buyer's PayPal session handles the challenge during approval. The agent doesn't see it.

What's out of scope for this skill

These belong to the storefront/frontend, not a runtime agent — don't try to script them via this skill:

• JavaScript SDK button rendering (paypal-js, paypal-buttons)
• Pay Later messaging widgets, Apple Pay / Google Pay buttons
• Fastlane / Express Checkout (frontend-only flow)
• Card Fields (Expanded Checkout PCI-handled iframe)
• Webhook receivers — those need a public HTTPS endpoint; if you need them, add a server slice in the host app and surface events to the agent via internal API, don't try to host them inside the runtime

Subscriptions (/v1/billing/subscriptions) and Payouts work via the same OAuth token if the agent really needs them, but both require human review flows that aren't standardized yet — confirm with the user before adding.

Don't

• Don't promote sandbox credentials to live by editing the accountKey — always re-paste from the live app. Live secrets are not derivable from sandbox ones.
• Don't log requests with the Authorization header or the raw client_secret/access_token. Filter before logging.
• Don't fire captures, refunds, or payouts from autonomous loops — always loop in the user, even for "small" amounts.
• Don't reuse an order id across sessions. PayPal orders expire after 3h and one-shot capture; create a fresh order for each buyer interaction.
• Don't infer environment from the client_id prefix — both sandbox and live ids start with A. Drive base URL from the accountKey.
• Don't store webhook signing secrets in this integration row. They're a separate concern owned by the host app, not the user's PayPal account.