PayPal

PayPal payments: search transactions and balances, create, show and capture orders, refund captures, review disputes, and list, show and send invoices.

12 actions token_login 8 read3 write1 destructive Calls api-m.paypal.com

Connect

TypeScript

const conn = await setu.connections.initiate({ userId: "user_1", toolkit: "paypal" });
console.log(conn.connectUrl); // show this to your user
await conn.waitUntilActive();

Permissions requested

This toolkit uses a single credential and requests no scopes.

Actions

Capture order paymentwritepaypal.capture_orderCapture the payment for an approved order. This moves money from the buyer to the merchant account and is hard to reverse (only by refund). Pass request_id to make retries safe.

Input	Type		Description
`order_id`	string	Required	PayPal order id (must be APPROVED by the buyer)
`request_id`	string	Optional	Unique idempotency key (PayPal-Request-Id header)

TypeScript

await setu.execute({
  userId: "user_1",
  action: "paypal.capture_order",
  input: {
    "order_id": "<order_id>"
  },
});

Create orderwritepaypal.create_orderCreate a PayPal order for a purchase (intent CAPTURE or AUTHORIZE). No money moves yet: the buyer must approve it through the approve link, then it can be captured. Pass request_id to make retries safe.

Input	Type		Description
`intent`	string	Required	CAPTURE or AUTHORIZE
`purchase_units`	array of object	Required	Purchase units, each with amount {currency_code, value} and optional reference_id, description, payee
`payment_source`	object	Optional	Optional payment source, for example {"paypal": {"experience_context": {...}}}
`request_id`	string	Optional	Unique idempotency key (PayPal-Request-Id header)

TypeScript

await setu.execute({
  userId: "user_1",
  action: "paypal.create_order",
  input: {
    "intent": "<intent>",
    "purchase_units": []
  },
});

Search balancesreadpaypal.get_balancesList the account's balances per currency (total, available and withheld), optionally as of a past time.

Input	Type		Description
`as_of_time`	string	Optional	ISO 8601 time to read balances at; default is now
`currency_code`	string	Optional	Only this currency, e.g. USD

TypeScript

await setu.execute({
  userId: "user_1",
  action: "paypal.get_balances",
  input: {},
});

Show captured paymentreadpaypal.get_captureShow details of a captured payment by capture id: amount, status, fees and net amount.

Input	Type		Description
`capture_id`	string	Required	PayPal capture id

TypeScript

await setu.execute({
  userId: "user_1",
  action: "paypal.get_capture",
  input: {
    "capture_id": "<capture_id>"
  },
});

Show disputereadpaypal.get_disputeShow one dispute by id: reason, state, amount, messages and offers.

Input	Type		Description
`dispute_id`	string	Required	PayPal dispute id, e.g. PP-D-27803

TypeScript

await setu.execute({
  userId: "user_1",
  action: "paypal.get_dispute",
  input: {
    "dispute_id": "<dispute_id>"
  },
});

Show invoicereadpaypal.get_invoiceShow one PayPal invoice by id: status, number, amount, recipients and payments.

Input	Type		Description
`invoice_id`	string	Required	PayPal invoice id, e.g. INV2-9DRB-YTHU-2V9Q-7Q24

TypeScript

await setu.execute({
  userId: "user_1",
  action: "paypal.get_invoice",
  input: {
    "invoice_id": "<invoice_id>"
  },
});

Show order detailsreadpaypal.get_orderShow the details and status of a PayPal order by id (CREATED, APPROVED, COMPLETED and so on).

Input	Type		Description
`order_id`	string	Required	PayPal order id

TypeScript

await setu.execute({
  userId: "user_1",
  action: "paypal.get_order",
  input: {
    "order_id": "<order_id>"
  },
});

List disputesreadpaypal.list_disputesList customer disputes, optionally only those in a given state or created after a time.

Input	Type		Description
`dispute_state`	string	Optional	Comma-separated states, e.g. REQUIRED_ACTION,OPEN_INQUIRIES,UNDER_REVIEW,RESOLVED
`start_time`	string	Optional	Only disputes created at or after this ISO 8601 time
`page_size`	integer	Optional	Items per page (1 to 50)
`next_page_token`	string	Optional	Token from the previous response to get the next page

TypeScript

await setu.execute({
  userId: "user_1",
  action: "paypal.list_disputes",
  input: {},
});

List invoicesreadpaypal.list_invoicesList PayPal invoices, 20 per page by default.

Input	Type		Description
`page`	integer	Optional	Page number starting at 1
`page_size`	integer	Optional	Items per page (1 to 100)
`total_required`	boolean	Optional	true to include total_items and total_pages

TypeScript

await setu.execute({
  userId: "user_1",
  action: "paypal.list_invoices",
  input: {},
});

Search transactionsreadpaypal.list_transactionsSearch PayPal transaction history between two dates (at most 31 days apart; data can lag by up to 3 hours). Returns transaction ids, amounts and statuses.

Input	Type		Description
`start_date`	string	Required	Start of range, ISO 8601 with timezone, e.g. 2026-09-01T00:00:00-0700
`end_date`	string	Required	End of range, ISO 8601 with timezone
`transaction_id`	string	Optional	Only this transaction id
`transaction_status`	string	Optional	Status code: D denied, P pending, S success, V reversed
`fields`	string	Optional	Comma-separated sections: transaction_info, payer_info, shipping_info, auction_info, cart_info, incentive_info, store_info or all
`page_size`	integer	Optional	Items per page (1 to 500)
`page`	integer	Optional	Page number starting at 1

TypeScript

await setu.execute({
  userId: "user_1",
  action: "paypal.list_transactions",
  input: {
    "start_date": "<start_date>",
    "end_date": "<end_date>"
  },
});

Refund captured paymentdestructivepaypal.refund_captureRefund a captured payment, in full or in part (give amount for a partial refund). This sends money back to the buyer and cannot be undone.

Input	Type		Description
`capture_id`	string	Required	PayPal capture id
`amount`	object	Optional	Partial refund amount {currency_code, value}; omit to refund the full capture
`note_to_payer`	string	Optional	Reason shown to the buyer
`invoice_id`	string	Optional	Your own invoice id for reconciliation
`request_id`	string	Optional	Unique idempotency key (PayPal-Request-Id header)

TypeScript

await setu.execute({
  userId: "user_1",
  action: "paypal.refund_capture",
  input: {
    "capture_id": "<capture_id>"
  },
  confirm: true,
});

Send invoicewritepaypal.send_invoiceSend (or re-send) a draft PayPal invoice to the customer by email. This emails a real customer.

Input	Type		Description
`invoice_id`	string	Required	PayPal invoice id
`subject`	string	Optional	Email subject
`note`	string	Optional	Note to the payer
`send_to_recipient`	boolean	Optional	Email the recipient (default true)
`send_to_invoicer`	boolean	Optional	Send a copy to the merchant
`additional_recipients`	array of string	Optional	CC email addresses

TypeScript

await setu.execute({
  userId: "user_1",
  action: "paypal.send_invoice",
  input: {
    "invoice_id": "<invoice_id>"
  },
});