# PayPal

:::tip Available
This integration is active and ready to use in Frihet.
:::

Connect your PayPal Business account to Frihet. Import transactions, view balances, and automatically reconcile international payments with your invoices. Supports sandbox mode for testing.

## What is it for?

With PayPal integrated:

- **Import transactions** — Automatically bring PayPal payments into Frihet as invoices
- **Full pagination** — Import all transactions without limit (automatic pagination)
- **Smart history** — First import: 1 year of history. Afterwards: only new transactions since the last synchronization
- **Refunds** — Refunds are imported with `[Refund]` prefix and negative amount for clear accounting
- **View balances** — View your PayPal balance directly from the Frihet dashboard
- **Reconcile payments** — Associate PayPal transactions with existing invoices
- **Multi-currency** — Handles payments in EUR, USD, GBP, and other currencies
- **Deduplication** — Already imported transactions are not duplicated (`PP-` prefix)
- **Sandbox mode** — Test the integration without affecting real data

## Requirements

- **PayPal Business Account** — Personal accounts do not have API access
- **Application in PayPal Developer** — To obtain Client ID and Client Secret
- **Frihet Pro or higher**

## Connect PayPal with Frihet

### Step 1: Create an application in PayPal Developer

1. Go to [developer.paypal.com](https://developer.paypal.com)
2. Log in with your PayPal Business account
3. In the dashboard, go to **Apps & Credentials**
4. Select **Live** mode (or **Sandbox** for testing)
5. Click on **Create App**
6. Give it a name (e.g.: "Frihet ERP")
7. Click on **Create App**

Once created, you will see:

- **Client ID** — A public identifier (e.g.: `AaBbCcDdEe...`)
- **Client Secret** — A private key (click "Show" to view it)

:::caution Save the Secret
The Client Secret is only shown once. Copy it and save it in a secure place before continuing.
:::

### Step 2: Configure in Frihet

1. Go to **Settings** → **Integrations**
2. Search for **PayPal**
3. Click on **Connect**
4. Enter your **Client ID** and **Client Secret**
5. Select the mode:
   - **Live** — For real transactions
   - **Sandbox** — For testing with fictitious data
6. Click on **Verify connection**
7. If correct, you will see "Connected"

### Step 3: Verify connection

1. Frihet automatically obtains an OAuth2 token using your credentials
2. If the verification is successful, you will see your PayPal balance in the dashboard
3. You can perform a test import with the latest transactions

## How it works

Frihet uses the **PayPal REST API v2** with OAuth2 authentication (client credentials flow):

1. You provide Client ID and Client Secret
2. Frihet automatically requests an access token from PayPal
3. With that token, Frihet queries transactions and balances
4. The credentials are stored encrypted (AES-256-GCM) in Frihet
5. The token is automatically renewed when it expires

At no point do you need to manage tokens manually.

## Synchronized data

| Data | Direction | Frequency |
|------|-----------|------------|
| Received transactions | PayPal → Frihet | On demand / periodic |
| Account balance | PayPal → Frihet | On each query |
| Payer data | PayPal → Frihet | With each transaction |
| Currency and exchange rate | PayPal → Frihet | With each transaction |

## Use cases

### Freelancer with international clients

You charge clients in USD and EUR via PayPal. Frihet imports each payment, associates it with the corresponding invoice, and converts the amount to your base currency.

### Online store with PayPal as payment method

You receive payments from clients via PayPal Checkout. Transactions are imported into Frihet, and you can reconcile them with invoiced orders.

### Verify balance before paying vendors

Check your PayPal balance from the Frihet dashboard without leaving the application. Decide if you have available funds before issuing transfers.

## Sandbox Mode

To test the integration without affecting real data:

1. On [developer.paypal.com](https://developer.paypal.com), create an app in **Sandbox** mode
2. Use the Sandbox credentials in Frihet (select "Sandbox" mode)
3. PayPal provides test accounts with a fictitious balance
4. Verify that transactions are imported correctly
5. When you are ready, switch to **Live** mode with production credentials

## Troubleshooting

### "Authentication error"

- Verify that the Client ID and Client Secret are correct
- Make sure to use **Live** credentials in Live mode and **Sandbox** credentials in Sandbox mode
- Check that your PayPal Business account is active and verified

### "No transactions are imported"

- Verify that there are transactions in the consulted period (1 year in first import, since last synchronization in subsequent ones)
- In Sandbox mode, generate test transactions from the PayPal Developer dashboard
- Check that your application in PayPal has the necessary permissions activated
- If the toast shows "No new transactions to import", all transactions are already in Frihet

### "API permissions error"

- When creating the app in PayPal Developer, make sure it includes the transactions scope
- If you changed permissions, generate a new Client Secret and update it in Frihet

### "I want to switch from Sandbox to Live"

1. Go to **Settings** → **Integrations** → **PayPal**
2. Click on **Disconnect**
3. Reconnect with the production (Live) credentials

## Next steps

- [Connect Stripe for card payments](./stripe)
- [Connect GoCardless for SEPA direct debits](./gocardless)
- [Automate workflows with n8n](./n8n)