PayPal Configuration

This guide will help you correctly configure PayPal integration in the Filament Tenancy package.

Prerequisites
Initial Configuration
Migrations
Configuration from Filament
Webhook Configuration in PayPal
Environment Variables
Service Usage
Supported Events and Webhooks
Troubleshooting
Usage Examples

Prerequisites

Before starting, make sure you have:

A PayPal Business account (not personal)
Access to the PayPal Developer Dashboard
Laravel with the filament-tenancy package installed
Database configured and migrations executed

Initial Configuration

1. Create a PayPal Application

Go to PayPal Developer Dashboard
Sign in with your PayPal Business account
Navigate to My Apps & Credentials
Click Create App
Complete the form:
- App Name: Your application name (e.g., “My Application”)
- Merchant: Select your business account
- Features: Select the features you need
Click Create App

2. Get Credentials

After creating the application, you’ll see two sets of credentials:

Sandbox Credentials: For testing
Live Credentials: For production

Each set includes:

Client ID: Public identifier for your application
Client Secret: Secret key (keep it secure)

Migrations

The necessary migrations are already included in the package. Run migrations if you haven’t already:

php artisan migrate

The relevant migrations for PayPal are:

2024_01_01_000017_create_paypal_settings_table.php - Creates PayPal configuration table
2024_01_01_000015_add_paypal_fields_to_subscriptions_table.php - Adds PayPal fields to subscriptions

Configuration from Filament

Access Configuration

Access the Filament administration panel (Landlord Panel)
In the sidebar menu, look for PayPal Settings in the Administration group
Click to open the configuration page

Step-by-Step Configuration

1. Enable PayPal

Activate the Is Enabled toggle to enable PayPal
Once activated, other fields will be displayed

2. Configure Credentials

Mode:

Sandbox: For testing and development
Live: For production

Client ID:

Enter the Client ID obtained from PayPal Developer Dashboard
For testing, use Sandbox Client ID
For production, use Live Client ID

Client Secret:

Enter the corresponding Client Secret
This field is hidden for security (password type)

Currency:

ISO 4217 currency code (e.g., USD, EUR, MXN)
Default: USD

3. Configure Webhooks

Webhook Secret:

Obtained after configuring the webhook in PayPal (see next section)
Used to verify authenticity of PayPal notifications

Return URL:

URL where PayPal redirects after successful payment
Default: /paypal/success
You can customize it according to your needs

Cancel URL:

URL where PayPal redirects if user cancels payment
Default: /paypal/cancel
You can customize it according to your needs

Environment Variables

Although configuration is mainly done from Filament, you can also use environment variables as backup:

# PayPal Configuration
PAYPAL_MODE=sandbox
PAYPAL_CLIENT_ID=your_client_id_here
PAYPAL_CLIENT_SECRET=your_client_secret_here
PAYPAL_CURRENCY=USD
PAYPAL_WEBHOOK_SECRET=your_webhook_secret_here
PAYPAL_RETURN_URL=/paypal/success
PAYPAL_CANCEL_URL=/paypal/cancel

Note: Configuration from Filament takes priority over environment variables. Environment variables are only used if PayPal is not enabled in the database or if there’s an error loading the configuration.

Service Usage

Create a Payment Order

use AngelitoSystems\FilamentTenancy\Support\PayPalService;
use AngelitoSystems\FilamentTenancy\Models\Subscription;

$paypalService = app(PayPalService::class);
$subscription = Subscription::find(1);

// Create one-time payment order
$order = $paypalService->createOrder($subscription);

if ($order) {
    // Get approval URL
    $approveUrl = collect($order['links'])->firstWhere('rel', 'approve')['href'];

    // Redirect user to PayPal
    return redirect($approveUrl);
}

Create a Recurring Subscription

use AngelitoSystems\FilamentTenancy\Support\PayPalService;
use AngelitoSystems\FilamentTenancy\Models\Subscription;

$paypalService = app(PayPalService::class);
$subscription = Subscription::find(1);

// Create recurring subscription in PayPal
$paypalSubscription = $paypalService->createSubscription($subscription);

if ($paypalSubscription) {
    // Get approval URL
    $approveUrl = collect($paypalSubscription['links'])->firstWhere('rel', 'approve')['href'];

    // Redirect user to PayPal
    return redirect($approveUrl);
}

Supported Events and Webhooks

The system automatically handles the following PayPal events:

Payment Events

PAYMENT.CAPTURE.COMPLETED:
- Activates subscription
- Creates invoice
- Calculates commissions if there’s an associated seller
PAYMENT.CAPTURE.DENIED:
- Marks subscription as pending
- Records failure reason
PAYMENT.CAPTURE.REFUNDED:
- Marks subscription as pending
- Records refund

Subscription Events

BILLING.SUBSCRIPTION.CREATED:
- Records subscription creation in PayPal
BILLING.SUBSCRIPTION.ACTIVATED:
- Activates subscription in system
- Creates initial invoice
- Calculates commissions
BILLING.SUBSCRIPTION.CANCELLED:
- Cancels subscription in system
- Records cancellation reason
BILLING.SUBSCRIPTION.EXPIRED:
- Marks subscription as expired
BILLING.SUBSCRIPTION.PAYMENT.FAILED:
- Marks subscription as pending
- Records payment failure
BILLING.SUBSCRIPTION.UPDATED:
- Updates subscription status

Troubleshooting

Error: “PayPal: Service is not enabled”

Cause: PayPal is not enabled in configuration.

Solution:

Go to Filament > PayPal Settings
Activate the “Is Enabled” toggle
Save changes

Error: “PayPal: Failed to get access token”

Cause: Incorrect credentials or connection issues.

Solutions:

Verify that Client ID and Client Secret are correct
Make sure you’re using the correct credentials (Sandbox vs Live)
Check your internet connection
Use the “Test Connection” button in Filament to diagnose

Error: “PayPal: Webhook signature verification failed”

Cause: Webhook Secret is not configured correctly.