PayPal connector for AI agents

Tools your payments agent reaches for on PayPal, scope checked on every call.

CALL ANY TOOL

63 tools for payments on PayPal: create, send, and remind invoices, create, capture, and refund orders, run subscription plans, send payouts, handle disputes, and track shipments.

paypal_authorization_capture

Capture authorization

Capture all or part of an authorized PayPal payment, moving the held funds to the merchant. Returns the capture with its id, status and amount. Use authorization_capture after order_authorize; leave the amount empty to capture the full authorized amount. Use order_capture for orders created with intent CAPTURE.

Parameters

Name

Type

Required

Description

authorization_id

string

Required

The PayPal authorization ID, found in purchase_units[].payments.authorizations[].id of the order returned by order_authorize or order_get. Example: 0VF52814937998046

amount_value

string

Optional

Amount to capture. Leave empty to capture the full authorized amount as a decimal string in the currency's units, for example 10.50 for ten dollars and fifty cents. Use whole numbers for currencies without decimals such as JPY. Set currency_code together with this field.

currency_code

string

Optional

Three-letter ISO 4217 currency code for the capture amount, in upper case. Required whenever an amount is given. Example: USD

final_capture

boolean

Optional

Set to true if you will not capture any more against this authorization, which releases the remaining hold. Defaults to false.

invoice_id

string

Optional

Your own invoice number for this capture, shown in the buyer's transaction history. Up to 127 characters. Example: INV-1001

note_to_payer

string

Optional

A note about this capture shown to the buyer in their transaction history and email. Up to 255 characters. Example: Thanks for your order

request_id

string

Optional

Optional idempotency key sent as the PayPal-Request-Id header. If a request with the same key was already processed, PayPal returns the original result instead of repeating the operation, so retries are safe. Use any unique string up to 108 characters, such as a UUID. Example: 7b92603e-77ed-4896-8e78-5dea2050476a

soft_descriptor

string

Optional

Text that appears on the buyer's card or bank statement, up to 22 characters. Example: ACME*ORDER1001

paypal_authorization_get

Get authorization

paypal_authorization_void

Void authorization

paypal_balances_list

List balances

paypal_dispute_escalate

Dispute escalate

paypal_dispute_get

Get dispute

paypal_invoice_cancel

Cancel invoice

paypal_invoice_create

Create invoice

Create a draft PayPal invoice with its currency, invoice details, recipients and line items. Returns the new invoice, including its id and status DRAFT. Use invoice_create to draft an invoice, then invoice_send to deliver it. Use invoice_number_generate first if you want to set the invoice number yourself.

Parameters

Name

Type

Required

Description

detail

object

Required

Invoice details. currency_code (three-letter code) is required. You can also set invoice_number (auto-incremented when omitted), reference such as a PO number, invoice_date (YYYY-MM-DD), payment_term with term_type (DUE_ON_RECEIPT, NET_10, NET_15, NET_30, NET_45, NET_60, NET_90, NO_DUE_DATE or DUE_ON_DATE_SPECIFIED with a due_date), a note shown to the recipient, terms_and_conditions and a private memo. Example: {"currency_code": "USD", "invoice_number": "INV-1001", "invoice_date": "2026-10-14", "payment_term": {"term_type": "NET_30"}, "note": "Thank you for your business."}

additional_recipients

array

Optional

Email addresses to CC on invoice notifications. Example: ["accounts@example.com"]

amount

object

Optional

Invoice-level amount adjustments in a breakdown object: shipping (amount and optional tax), discount (invoice_discount as percent or amount) and custom (label and amount). PayPal calculates item and tax totals itself. Example: {"breakdown": {"shipping": {"amount": {"currency_code": "USD", "value": "10.00"}}}}

configuration

object

Optional

Invoice options: allow_tip, tax_calculated_after_discount, tax_inclusive, partial_payment (allow_partial_payment and minimum_amount_due) and template_id. Example: {"allow_tip": false, "partial_payment": {"allow_partial_payment": true, "minimum_amount_due": {"currency_code": "USD", "value": "50.00"}}}

invoicer

object

Optional

The merchant's business details printed on the invoice: business_name, a name object, an address object, email_address, phones, website, tax_id, additional_notes and logo_url. When omitted, PayPal uses the account's profile. Example: {"business_name": "Acme Supplies", "email_address": "billing@acme.example", "website": "https://acme.example"}

items

array

Optional

Line items. Each item needs a name, a quantity (string, up to five decimals) and a unit_amount with currency_code and value; you can add description, tax (name and percent), discount (percent or amount), item_date and unit_of_measure (QUANTITY, HOURS or AMOUNT). Example: [{"name": "Consulting", "quantity": "2", "unit_amount": {"currency_code": "USD", "value": "150.00"}, "unit_of_measure": "HOURS"}]

primary_recipients

array

Optional

Who the invoice is billed to. Each entry has a billing_info object (email_address, name with given_name and surname, business_name, address, phones, language) and an optional shipping_info object. Example: [{"billing_info": {"email_address": "customer@example.com", "name": {"given_name": "Jane", "surname": "Doe"}}}]

paypal_invoice_number_generate

Generate invoice number

paypal_invoice_qr_code_generate

Generate invoice qr code

paypal_invoice_remind

Invoice remind

paypal_invoice_send

Send invoice

paypal_invoice_template_get

Get invoice template

paypal_invoice_template_update

Update invoice template

paypal_invoice_templates_list

List invoice templates

paypal_invoices_search

Search invoices

Search PayPal invoices by recipient email or name, invoice number, status, currency, total amount range or date range; an invoice must match every criterion you give. Returns matching invoices with id, status, detail, recipients and amount, plus paging links. Use invoices_search to filter. Use invoices_list to browse everything.

Parameters

Name

Type

Required

Description

archived

boolean

Optional

true returns only archived invoices, false only unarchived ones. Leave empty to include both.

creation_date_range

object

Optional

Only invoices created within this range, given as start and end date-times (ISO 8601). Example: {"start": "2026-10-01T00:00:00Z", "end": "2026-10-31T23:59:59Z"}

currency_code

string

Optional

Only invoices in this three-letter currency. Example: USD

due_date_range

object

Optional

Only invoices whose due date falls in this range, given as start and end dates (YYYY-MM-DD). Example: {"start": "2026-10-01", "end": "2026-10-31"}

invoice_date_range

object

Optional

Only invoices whose invoice date falls in this range, given as start and end dates (YYYY-MM-DD). Example: {"start": "2026-01-01", "end": "2026-03-31"}

invoice_number

string

Optional

Only the invoice with this invoice number. Example: INV-1001

memo

string

Optional

Only invoices whose private memo matches this text. Example: Q4 retainer

page

integer

Optional

Page number to return, starting at 1. Defaults to 1. Combine with page_size: page=2 with page_size=20 returns items 21 to 40.

page_size

integer

Optional

Number of items per page, from 1 to 100. PayPal uses 20 when omitted.

payment_date_range

object

Optional

Only invoices paid within this range, given as start and end date-times (ISO 8601). Example: {"start": "2026-10-01T00:00:00Z", "end": "2026-10-31T23:59:59Z"}

recipient_business_name

string

Optional

Only invoices whose recipient has this business name. Example: Globex Corp

recipient_email

string

Optional

Only invoices billed to this email address. Example: customer@example.com

recipient_first_name

string

Optional

Only invoices whose recipient has this first name. Example: Jane

recipient_last_name

string

Optional

Only invoices whose recipient has this last name. Example: Doe

reference

string

Optional

Only invoices with this reference, such as a purchase order number. Example: PO-5521

status

array

Optional

Only invoices in any of these statuses: DRAFT, SENT, SCHEDULED, PAID, MARKED_AS_PAID, CANCELLED, REFUNDED, PARTIALLY_PAID, PARTIALLY_REFUNDED, MARKED_AS_REFUNDED, UNPAID or PAYMENT_PENDING. Example: ["SENT", "UNPAID"]

total_amount_range

object

Optional

Only invoices whose total falls in this range, given as lower_amount and upper_amount, each with currency_code and value. Example: {"lower_amount": {"currency_code": "USD", "value": "100.00"}, "upper_amount": {"currency_code": "USD", "value": "500.00"}}

total_required

boolean

Optional

Set to true to include total_items and total_pages in the response so you know how many pages exist. Defaults to false.

paypal_order_capture

Capture order

paypal_order_create

Create order

Create a PayPal checkout order for one or more purchase units, with intent CAPTURE (take the payment once the buyer approves) or AUTHORIZE (hold the funds and capture later). Returns the order id, status (usually CREATED, or PAYER_ACTION_REQUIRED) and links, including the approve link the buyer must open. Use order_create to start a payment, then order_capture or order_authorize after approval. Use invoice_create to bill a customer by email instead.

Parameters

Name

Type

Required

Description

intent

string

Required

CAPTURE takes the payment as soon as the buyer approves and you call order_capture. AUTHORIZE places a hold that you capture later with authorization_capture (after order_authorize). One of: `CAPTURE`, `AUTHORIZE`.

purchase_units

array

Required

One or more purchase units (up to 10). Each needs an amount with a three-letter currency_code and a string value. Add a reference_id when there is more than one unit, and optionally description, custom_id, invoice_id, soft_descriptor, items (with name, quantity and unit_amount, which then requires amount.breakdown.item_total) and shipping. Example: [{"reference_id": "default", "description": "Order #1001", "amount": {"currency_code": "USD", "value": "25.00"}}]

payment_source

object

Optional

Optional payment source. For PayPal checkout, pass a paypal object with experience_context to set return_url and cancel_url (where the buyer lands after approving or cancelling), brand_name, user_action (PAY_NOW or CONTINUE) and shipping_preference. You can also charge a saved instrument with vault_id. Example: {"paypal": {"experience_context": {"return_url": "https://example.com/return", "cancel_url": "https://example.com/cancel", "user_action": "PAY_NOW"}}}

request_id

string

Optional

paypal_order_tracker_update

Update order tracker

paypal_order_tracking_add

Add order tracking

paypal_payout_get

Get payout

paypal_plan_create

Create plan

Create a subscription billing plan for a catalog product, with up to two trial cycles plus one regular billing cycle, payment preferences and optional taxes. Returns the plan with its id (P-...), status and billing cycles. Use plan_create before subscription_create, which needs a plan_id. Requires a product_id from product_create or products_list.

Parameters

Name

Type

Required

Description

billing_cycles

array

Required

Billing cycles run in sequence order. Each has a frequency (interval_unit DAY, WEEK, MONTH or YEAR and interval_count), tenure_type TRIAL or REGULAR, a sequence number starting at 1, total_cycles (0 means the regular cycle repeats until cancelled) and a pricing_scheme with fixed_price (currency_code and value); a free trial omits pricing_scheme. Example: [{"frequency": {"interval_unit": "MONTH", "interval_count": 1}, "tenure_type": "REGULAR", "sequence": 1, "total_cycles": 0, "pricing_scheme": {"fixed_price": {"currency_code": "USD", "value": "10.00"}}}]

name

string

Required

Plan name, 1 to 127 characters. Example: Basic Monthly

payment_preferences

object

Required

How payments are handled: auto_bill_outstanding (bill missed amounts in the next cycle, default true), setup_fee (currency_code and value charged at sign-up), setup_fee_failure_action (CONTINUE or CANCEL) and payment_failure_threshold (failed payments allowed before suspension). Example: {"auto_bill_outstanding": true, "setup_fee_failure_action": "CONTINUE", "payment_failure_threshold": 3}

product_id

string

Required

The catalog product this plan bills for, from product_create or products_list. Example: PROD-XXCD1234QWER65782

description

string

Optional

Plan description, 1 to 127 characters. Example: Basic plan billed monthly

quantity_supported

boolean

Optional

Set to true to let subscribers choose a quantity of the product. Defaults to false.

request_id

string

Optional

status

string

Optional

Initial plan status: ACTIVE (the default; subscriptions can be created right away) or CREATED (activate later with plan_activate). One of: `CREATED`, `ACTIVE`.

taxes

object

Optional

Tax applied to the plan: percentage as a string and inclusive (true if the price already includes tax). Example: {"percentage": "10", "inclusive": false}

paypal_plan_deactivate

Deactivate plan

paypal_plan_get

Get plan

paypal_plan_pricing_update

Update plan pricing

paypal_plans_list

List plans

paypal_product_update

Update product

paypal_refund_get

Get refund

paypal_subscription_capture

Capture subscription

paypal_subscription_transactions_list

List subscription transactions

For more tools, view docs.

Build your Agent

Same auth pattern across LangChain, OpenAI, Anthropic, and Google ADK.

import { ScalekitClient } from "@scalekit-sdk/node";
import { createReactAgent } from "@langchain/langgraph/prebuilt";

const sk = new ScalekitClient(env.SCALEKIT_ENV_URL, env.SCALEKIT_CLIENT_ID, env.SCALEKIT_CLIENT_SECRET);

// PayPal tools available to this agent
const { tools } = await sk.tools.listScopedTools("user_123", {
  filter: { connectionNames: ["paypal"], toolNames: [
    "paypal_invoices_search",
    "paypal_invoice_remind",
    "paypal_disputes_list"] },
  pageSize: 100,
});

const agent = createReactAgent({ llm, tools });
await agent.invoke({ messages: [{ role: "user", content: "Send a reminder for every unpaid invoice older than 30 days and list open disputes" }] });

import OpenAI from "openai";
import { ScalekitClient } from "@scalekit-sdk/node";

const sk = new ScalekitClient(env.SCALEKIT_ENV_URL, env.SCALEKIT_CLIENT_ID, env.SCALEKIT_CLIENT_SECRET);
const openai = new OpenAI();

const { tools } = await sk.tools.listScopedTools("user_123", {
  filter: { connectionNames: ["paypal"] }, pageSize: 100,
});

const res = await openai.chat.completions.create({
  model: "gpt-5",
  messages: [{ role: "user", content: "Send a reminder for every unpaid invoice older than 30 days and list open disputes" }],
  tools,
});

// Execute the tool call with the vaulted PayPal service account credentials
await sk.tools.executeTool(res.choices[0].message.tool_calls[0], "user_123");

import Anthropic from "@anthropic-ai/sdk";
import { ScalekitClient } from "@scalekit-sdk/node";

const sk = new ScalekitClient(env.SCALEKIT_ENV_URL, env.SCALEKIT_CLIENT_ID, env.SCALEKIT_CLIENT_SECRET);
const anthropic = new Anthropic();

const { tools } = await sk.tools.listScopedTools("user_123", {
  filter: { connectionNames: ["paypal"] }, pageSize: 100,
});

const msg = await anthropic.messages.create({
  model: "claude-sonnet-5",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Send a reminder for every unpaid invoice older than 30 days and list open disputes" }],
  tools,
});

// Tool call runs with the vaulted PayPal service account credentials
await sk.tools.executeTool(msg.content, "user_123");

import { Agent } from "@google/adk/agents";
import { ScalekitClient } from "@scalekit-sdk/node";

const sk = new ScalekitClient(env.SCALEKIT_ENV_URL, env.SCALEKIT_CLIENT_ID, env.SCALEKIT_CLIENT_SECRET);

const { tools } = await sk.tools.listScopedTools("user_123", {
  filter: { connectionNames: ["paypal"] }, pageSize: 100,
});

const agent = new Agent({
  name: "payments_agent",
  model: "gemini-2.5-pro",
  instruction: "PayPal tools available to this agent",
  tools,
});

await agent.run("Send a reminder for every unpaid invoice older than 30 days and list open disputes");

Try these prompts

Copy any prompt into your agent. Each maps directly to a PayPal tool. Click to copy, paste into your agent, done.

Invoices

Copy the prompt

Copied

Create a draft invoice for jordan@example.com for 3 hours of design work at $120.

Copy the prompt

Copied

Send a reminder for every unpaid invoice older than 30 days.

Copy the prompt

Copied

Record a $500 bank transfer payment against this invoice.

Orders and refunds

Copy the prompt

Copied

Capture the authorized payment on this order.

Copy the prompt

Copied

Refund $25 of this captured payment.

Copy the prompt

Copied

Add UPS tracking number 1Z999AA10123456784 to this order.

Subscriptions and payouts

Copy the prompt

Copied

Create a monthly plan at $29 for our Analytics product.

Copy the prompt

Copied

Suspend this subscription.

Copy the prompt

Copied

Send $150 payouts to these 4 affiliates by email.

SEE HOW AUTH WORKS

You connect PayPal once with a service account, and Scalekit authenticates every call. Credentials stay vaulted, every call is scope checked, and every action is logged.

Authorize

Your user connects

PayPal

once. We tie it to their identity and the meetings they approved — no shared bot account, no org-wide access

Who:

user ‘A’

when:

Once per user

access:

Limited to user

Store

Their

PayPal

token lives in a vault scoped to them. User A's meetings are never reachable by an agent acting for user B, even on the same connection

vault:

encrypted

scope:

per-user

tokens:

auto-refreshed

Resolve

When your agent calls a

PayPal

tool, we fetch the right token server-side. It never touches your agent, never appears in the LLM context, never shows up in your logs

speed:

~40ms

check:

before every call

seen by:

nobody

Audit

Every

PayPal

tool call is logged — who triggered it, which meeting was fetched, what came back. 90 days of history, tied to the user who authorized it

history:

90 days

export:

SIEM-ready

logged:

every call

Test other agents

See the same auth pattern across other accounting and finance connectors.

GTM and RevOps Teams

Revenue forecast commentary

Pulls open pipeline from Salesforce and HubSpot, calculates coverage against quota, flags at-risk stages, posts commentary to Slack, and logs every snapshot to Google Sheets.

GTM and RevOps Teams

CRM AI agent

Reads the Granola transcript after every call, extracts next steps and updates the HubSpot record, drafts the follow-up in Gmail, and confirms in Slack, all on the rep's own delegated OAuth.

Why Scalekit

Secure your agent's access. Connectors ship in minutes

01.

Shared tokens break per-user analytics

PayPal sees every call from one REST API app, so a refund or payout looks the same no matter who asked for it. Scalekit logs which user triggered each agent call, so your audit trail still shows who did what.

// paypal sees
caller → rest_api_app

// scalekit log
caller → user_abc ✓

02.

Authentication is not authorization

03.

Multi-tenancy is architectural

04.

PayPal today. Ten connectors tomorrow.

“Our agents act across Salesforce, Gong, Google Drive, and more, on behalf of every customer. Scalekit behind the scenes meant we can keep adding tools without ever rebuilding how credentials or tool calling work.”

Venu Madhav Kattagoni

Head of Engineering / Von

FAQs

Frequently Asked Questions

Does the agent access PayPal through a service account?

Yes. You connect PayPal once with a service account, and Scalekit authenticates every call. The connection uses a PayPal REST API app's client credentials, so every tool acts on the PayPal account that owns that app. Scalekit logs which user's agent made each call.

Where are the PayPal service account credentials stored?

In Scalekit's managed AES-256 token vault, namespaced per tenant. Revocation is a single dashboard action. Credentials never appear in prompts, logs, or LLM context.

Can I limit what the agent does in PayPal?

Yes. Filter by tool name in listScopedTools to expose only what you want, for example the list and get tools without paypal_payout_create, which sends money to recipients, or paypal_capture_refund, which refunds a captured payment. Scalekit also enforces scope checks before every API call.

What happens when PayPal access is turned off?

Disable the connection in the Scalekit dashboard and the next tool call fails closed with a clear error. Other tenants are unaffected, and the change is logged.

Which PayPal account does the agent work on?

The PayPal account that owns the REST API app behind the connection. paypal_balances_list returns its balances per currency, and paypal_transactions_list searches its transaction history between two dates up to 31 days apart.