# PayPal onboarding

Connect your PayPal Business account to your site so you can send PayPal payouts from your iOS app.

## Before you start

If you haven't already, make sure that you have activated the Components and PayPal services in the Unity Portal. For more information, see [Activation](/guides/payout/components/activation).

## Step 1: Connect your PayPal account

Log in with an existing account
To connect an existing PayPal account, follow these steps.

1. In the Unity Portal, go to **Merchant setup > Sites**.
2. Select a site.
3. In the **Services** tab, find the *PayPal service* and click **Edit**.
4. Click **PayPal account**.
5. Click **Connect PayPal account**. A PayPal pop-up opens.
6. Enter your credentials, then click **Next**.
7. Click **Agree and Continue**. A confirmation message is displayed.
8. Click **Return to PXP** to go back to the Unity Portal.


If your connection is successful, a success message is displayed and your connection details are visible. You're now ready to proceed with configuring PayPal for iOS payouts.

If your connection is unsuccessful, a warning is displayed. See the [Troubleshooting](/guides/payout/components/ios/paypal/troubleshooting) guide for more information.

Create a new account
To create a new PayPal account and connect it, follow these steps.

1. In the Unity Portal, go to **Merchant setup > Sites**.
2. Select a site.
3. In the **Services** tab, find the *PayPal service* and click **Edit**.
4. Click **PayPal account**.
5. Click **Connect PayPal account**. A PayPal pop-up opens.
6. Click **Create An Account**.
7. Enter your legal name, email address, and a password, then click **Create Account** to confirm.
8. Add your business and personal information, then click **Submit**. A confirmation message is displayed.
9. Click **Return to PXP** to go back to the Unity Portal.


If your connection is successful, a success message is displayed and your connection details are visible. You're now ready to proceed with configuring PayPal for iOS payouts.

If your connection is unsuccessful, a warning is displayed. See the [Troubleshooting](/guides/payout/components/ios/paypal/troubleshooting) guide for more information.

## Step 2: Create a PayPal app

Now configure your PayPal Developer account for backend API integration:

1. Log in to the PayPal Developer Dashboard.
2. Go to **Apps & Credentials**.
3. Select the environment:
  - **Sandbox:** For development and testing
  - **Live:** For production
4. Click **Create App**.
5. Enter an **App Name** (e.g., "My App Payouts").
6. Select **Merchant** as the app type.
7. Click **Create App**.


## Step 3: Enable the Payouts API

To enable the Payouts API for your app, follow these steps.

1. In your app settings, scroll to **Features**.
2. Ensure **Payouts** is enabled. If it isn't, click **Enable** next to Payouts.


If you don't see the Payouts option, your PayPal Business account may need additional verification. Contact PayPal Support for assistance.

## Step 4: Copy your credentials

You'll need these credentials for your backend integration.

### Sandbox credentials

To copy your sandbox credentials, follow these steps.

1. Go to the **Sandbox** environment.
2. Select your app.
3. Copy the following:
  - **Client ID:** Used for backend API authentication.
  - **Secret:** Used for backend API authentication.


### Live credentials

To copy your live credentials, follow these steps.

1. Go to the **Live** environment.
2. Select your app.
3. Copy the following:
  - **Client ID:** For production backend API authentication.
  - **Secret:** For production backend API authentication.


#### Security best practices

Follow these practices to keep your credentials secure:

- Never commit credentials to version control.
- Store secrets in environment variables or secure vaults.
- Use different credentials for sandbox and live environments.
- Rotate secrets regularly.


## Step 5: Create sandbox test accounts

For testing, you'll need to create several sandbox accounts.

### Create a payout sender account

To create the account that sends payouts in your tests, follow these steps.

1. In Developer Dashboard, go to **Sandbox > Accounts**.
2. Click **Create Account**.
3. Select the **Business** account type.
4. Set **Account Balance** (e.g., $10,000 for testing).
5. Click **Create Account**.


Note the email and password for testing.

### Create payout receiver accounts

To create the accounts that receive your test payouts, follow these steps.

1. Create additional **Personal** sandbox accounts.
2. These will receive test payouts.
3. Create multiple accounts to test different scenarios.


## Step 6: Configure webhook settings (optional)

To receive real-time notifications about the payout status:

1. In your app settings, scroll to **Webhooks**.
2. Click **Add Webhook**.
3. Enter your webhook URL:

```
https://yourdomain.com/api/webhooks/paypal
```
4. Select the following event types:
  - `PAYMENT.PAYOUTSBATCH.SUCCESS`: Payout batch completed
  - `PAYMENT.PAYOUTSBATCH.DENIED`: Payout batch denied
  - `PAYMENT.PAYOUTS-ITEM.SUCCEEDED`: Individual payout succeeded
  - `PAYMENT.PAYOUTS-ITEM.FAILED`: Individual payout failed
  - `PAYMENT.PAYOUTS-ITEM.BLOCKED`: Payout blocked by PayPal
  - `PAYMENT.PAYOUTS-ITEM.RETURNED`: Payout returned or refunded
5. Click **Save**.


Webhooks are recommended for production but not required. You can also poll the PayPal API for payout status.

## Step 7: Verify your setup

### Test payout API access

Run a test API call to verify payout permissions:

```bash
curl -X POST https://api-m.sandbox.paypal.com/v1/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -u "YOUR_CLIENT_ID:YOUR_SECRET" \
  -d "grant_type=client_credentials"
```

If successful, you'll receive an access token response.

## Environment configuration

### Sandbox environment

Use the following values in the sandbox environment:

- **API base URL:** `https://api-m.sandbox.paypal.com`
- **Web URL:** `https://www.sandbox.paypal.com`
- **Use for:** Development and testing
- **Test accounts:** Use sandbox accounts created in Step 5


### Live environment

Use the following values in the live environment:

- **API base URL:** `https://api-m.paypal.com`
- **Web URL:** `https://www.paypal.com`
- **Use for:** Production only
- **Real accounts:** Actual PayPal user accounts