PayPal Payment Gateway Integration (API Setup via PayPal Braintree)

Schedule a call

Schedule a call

PayPal API Integration (PayPal Braintree Payment Gateway)

OctopusPro integrates with PayPal through PayPal Braintree (PayPal’s payment gateway platform). This lets you accept PayPal payments online and keep invoice/payment statuses tracked inside OctopusPro—helping you get paid faster, reduce manual reconciliation, and offer customers a familiar checkout option.

PayPal payment gateway integration with OctopusPro - daily operations and payment flows

On this page

Overview

To connect PayPal to OctopusPro, you will:

  • Create (or access) a Braintree account (Sandbox for testing and Production for live payments).
  • Create (or upgrade to) a verified PayPal Business account.
  • Enable PayPal inside the Braintree Control Panel (Payment Methods).
  • Copy your Braintree API credentials (Merchant ID, Public Key, Private Key).
  • Paste those credentials into OctopusPro → Settings → Financial Settings → Payment Integration.
  • Enable PayPal as a checkout method in the Customer Portal (so customers can actually see it).

Braintree acts as the secure bridge between OctopusPro and PayPal—processing transactions and returning payment status updates back to OctopusPro.

PayPal payment integration architecture with OctopusPro via Braintree

Before you start (requirements)

  • Braintree account: You need a compatible Braintree account (Sandbox for testing, Production for live).
  • PayPal Business account: You need a verified PayPal Business account (linked bank account, verified business details where required).
  • Admin access in OctopusPro: You need access to Financial Settings to connect gateways.

Tip: For the smoothest setup, use the same business/admin email consistently across PayPal and Braintree wherever possible.

Step-by-step setup

Step 1: Apply for a Braintree account (or create a Sandbox)
  1. Apply for a Braintree account from the Braintree sign-up page (a representative may contact you to finalize activation).
  2. For testing first, create a Braintree Sandbox account.
Step 2: Understand Sandbox vs Production (important)

Braintree provides separate environments:

  • Sandbox: testing only (no real funds).
  • Production: live payments (real funds).

IMPORTANT: Sandbox and Production are completely separate. Settings, users, Merchant ID, and API keys do not carry across. Use Sandbox keys for testing and Production keys for live payments.

Note: Braintree sandboxes are region-specific—choose the country where your business is domiciled.

Step 3: Create or upgrade to a PayPal Business account
  1. Create a PayPal Business account, or upgrade an existing PayPal account to Business.
  2. Complete PayPal verification steps (commonly confirming your linked bank account).
Step 4: Enable (and link) PayPal inside Braintree

In the Braintree Control Panel:

  1. Open Settings (gear icon), then go to Processing.
  2. Scroll to Payment Methods.
  3. Find PayPal and enable it.
  4. Click Log in with PayPal and sign in using your PayPal Business account.
  5. When prompted, enter your website URLs (e.g., Privacy Policy and Terms & Conditions), then submit.

Important: To accept PayPal payments through Braintree, your Braintree account must support PayPal processing (commonly referred to as enabling PayPal via the appropriate Braintree setup).

Step 5: (Optional) Switch your Braintree environment to Live (Production)

When you’re ready to accept real payments:

  1. Log in to the Braintree Control Panel.
  2. Open Settings → Processing.
  3. Locate Live Transactions and switch from Sandbox to Production (if applicable for your account flow).
  4. Save your changes.
Step 6: Copy your Braintree API credentials

In the Braintree Control Panel, go to the API/Credentials section and copy the following values:

  • Merchant ID
  • Public Key
  • Private Key
Step 7: Connect PayPal (Braintree) inside OctopusPro
  1. Log in to OctopusPro as an admin.
  2. Go to Settings → Financial Settings → Payment Integration.

OctopusPro Payment Integration - select PayPal from payment gateway list

  1. Select PayPal.
  2. Enter your Braintree credentials:
    • Merchant ID
    • Public Key
    • Private Key
  3. (Optional) Enable Mark as default payment if PayPal should be your default online gateway.
  4. (Optional) Enable Add surcharge if you charge a processing fee (ensure this aligns with your local regulations and your payment policy).
  5. Click Save.

OctopusPro PayPal Payment Integration popup - Merchant ID, Public Key, Private Key, Save button

Show PayPal at Customer Portal checkout (two-step activation)

Connecting PayPal in Payment Integration enables the gateway, but customers will only see PayPal at checkout if you also enable it in your Customer Portal payment methods.

Follow this guide to complete the second step: Customer Portal Payment Methods (Checkout Options for Online Bookings)

Customer Portal payment methods configuration flow

Sandbox testing checklist

  • Confirm OctopusPro is using Sandbox Braintree credentials (if you’re testing).
  • Run a test booking in the Customer Portal and confirm PayPal appears as a payment option (once enabled in Customer Portal settings).
  • Confirm the payment outcome updates the booking/invoice payment status correctly.
  • If your workflow includes invoice payment links, send a test invoice and confirm the customer can pay from the link.

Go live checklist

  • Switch to (or log into) your Braintree Production environment.
  • Copy the Production Merchant ID / Public Key / Private Key.
  • Replace the Sandbox credentials in OctopusPro with Production credentials.
  • Run a small live transaction to confirm end-to-end processing and settlement.

Troubleshooting & common issues

PayPal doesn’t appear at checkout
  • Make sure PayPal is enabled in Customer Portal Payment Methods (this is separate from Payment Integration).
  • Confirm online payments are enabled for your portal/booking flow (and that your services/booking settings require payment at checkout if that’s your intent).
Integration won’t save / credentials rejected
  • Re-copy Merchant ID/Public Key/Private Key from Braintree (avoid extra spaces).
  • Confirm you didn’t mix Sandbox and Production credentials.
  • If you rotated keys in Braintree, update OctopusPro immediately.
Payments failing / declining
  • Check transaction logs in Braintree/PayPal for the decline reason (configuration vs payer/bank decline).
  • Confirm PayPal is enabled and shows as Active under Braintree Payment Methods.
Invoice payment links / payment workflows

Invoice Payment and Reconciliation Workflow

Security best practices

  • Treat your Private Key like a password. Only trusted admins should have access.
  • Never share API credentials in tickets, chat threads, or screenshots.
  • Rotate credentials if you suspect exposure, then update OctopusPro immediately.
  • Use least-privilege access for staff accounts where possible.

To stay updated, please subscribe to our YouTube channel.

Scroll to top