PayPal integration

Overview

PayPal is a global payments platform. The Automize PayPal connector covers orders + captures (the modern payments flow), subscriptions + plans, invoices, payouts (mass-disbursement), and disputes.

• Regions: PayPal is global. Distinct sandbox (sandbox.paypal.com) and live (paypal.com) environments. Some country-specific features (BNPL, crypto) gated regionally.
• Plans: Free to use. Pricing per transaction varies by country, currency, and merchant volume.

Setting up the connection

Auth type: OAuth 2.0 (Client Credentials).

1. Sign in to developer.paypal.com → Apps & Credentials.
2. Create an app (REST API). Pick Sandbox or Live.
3. Copy Client ID + Client Secret.
4. In Automize, open Settings → Connectors → PayPal → Add connection. Choose environment + paste credentials.

Find your credentials at https://developer.paypal.com/dashboard/applications.

Rate limits

PayPal enforces dynamic rate limits – not publicly documented but generous. Connector retries 429 / RATE_LIMIT_REACHED with backoff.

Data model

Modern API (Orders v2):

    Order ─── Captures (authorised/captured charges) ─── Refunds
    Subscription ─── Plan ─── Product
    Invoice (separate flow – emails customer for payment)
    Payout (mass-disbursement to multiple recipients)
    Dispute (chargeback / complaint workflow)

Available operations

22 operations available. Click any row to jump to its detail.

Operations

Authorize order

Authorize a PayPal order for later capture.

Tips

• Authorise (hold funds) after the customer approves. Use with intent=AUTHORIZE. Valid 3 days, extendable to 29.

Cancel subscription

Cancel a PayPal subscription.

Tips

• reason is shown to the customer + stored in subscription history.

Capture order

Capture a PayPal order payment.

Tips

• Captures funds (final charge). Use with intent=CAPTURE flow, or after Authorize.

Errors

• ORDER_NOT_APPROVED – Customer hasn't completed the approval step.
• AUTHORIZATION_VOIDED – Authorisation expired or was voided. Re-authorise.

Create invoice

Create a PayPal invoice.

Tips

• detail (invoice metadata) + invoicer (your business) + primary_recipients[] + items[].
• Status starts as DRAFT. Use Send Invoice to dispatch.

Create order

Create a PayPal order.

Tips

• intent: 'CAPTURE' (immediate capture on approval) or 'AUTHORIZE' (auth first, capture later).
• purchase_units[]: amount + currency_code + reference_id.
• Returns approval_url – redirect the customer there to approve.

Create payout

Create a PayPal payout.

Tips

• Mass-disbursement – pay many recipients in one call.
• items[]: each has receiver (email) + amount.value + amount.currency + recipient_type.

Create plan

Create a PayPal billing plan.

Tips

• billing_cycles[]: pricing structure (frequency + amount per cycle).
• payment_preferences.auto_bill_outstanding=true to retry failed payments.

Create product

Create a PayPal product for subscriptions.

Tips

• For subscriptions: products are catalog items. Plans set the billing cycle.
• type: PHYSICAL, DIGITAL, SERVICE. category: e.g. SOFTWARE.

Create subscription

Create a PayPal subscription.

Tips

• plan_id from Create Plan. subscriber: {name, email_address, shipping_address}.
• application_context.return_url + cancel_url where to send the user after approval.

Create Webhook

Create a webhook subscription

Tips

• url: your Automize webhook URL. event_types: array of event names (PAYMENT.CAPTURE.COMPLETED, etc.).

Get Dispute

Get dispute details

Tips

• Returns dispute incl. timeline + outcome + evidence requirements.

Get Invoice

Get invoice details

Tips

• Returns status: DRAFT, SENT, SCHEDULED, PAID, MARKED_AS_PAID, CANCELLED, REFUNDED, etc.

Get order

Get a PayPal order by ID.

Tips

• Returns order status: CREATED, APPROVED, COMPLETED, VOIDED.

Get payout

Get a PayPal payout by batch ID.

Tips

• payout_batch_id. Returns batch summary + per-item statuses.

Get refund

Get a PayPal refund by ID.

Tips

• refund_id from Refund Capture. Returns status: COMPLETED, PENDING, CANCELLED.

Get subscription

Get a PayPal subscription by ID.

Tips

• Returns status: APPROVAL_PENDING, APPROVED, ACTIVE, SUSPENDED, CANCELLED, EXPIRED.

List disputes

List PayPal disputes/claims.

No input parameters.

Tips

• Active disputes/claims. Filter by status + reason.

List invoices

List PayPal invoices.

No input parameters.

Tips

• Pages 100 per call. Filter by status, total_required (min total).

List Plans

List billing plans

No input parameters.

Tips

• Filter by product_id to find plans for a specific catalog item.

List transactions

List PayPal transactions.

No input parameters.

Tips

• Reporting endpoint. Filter by date range, transaction_status.

Refund capture

Refund a captured PayPal payment.

Tips

• capture_id from a successful Capture Order. amount + note_to_payer.
• Partial refunds allowed. Multiple partial refunds up to the captured amount.

Send invoice

Send a PayPal invoice.

Tips

• Emails the invoice to recipients. Status moves to SENT.

FAQ

Sandbox vs live – switch?

Two separate connections, each with its environment's credentials. Use process variables to pick at runtime.

Orders v2 vs legacy Payments – which?

Orders v2 (this connector). Legacy Payments API is deprecated for new builds. Some processors / SDKs still reference the old API – ignore.

Why is my order stuck CREATED?

Customer hasn't completed the PayPal approval step. They need to visit the approval_url returned by Create Order and click Pay.

Payouts need balance – how do I top up?

Either capture orders into the same PayPal account (revenue), or transfer from a linked bank account in PayPal UI. The connector can't add funds.

Related connectors

• Stripe
• Gocardless
• Payfast