# PayPal onboarding

Connect your PayPal Business account to your site so you can accept PayPal payments in 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/checkout/components/activate).

## Step 1: Connect your PayPal account

Log in with an existing account
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/checkout/components/ios/paypal/payouts/troubleshooting) guide for more information.

Create a new account
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/checkout/components/ios/paypal/payouts/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

1. In your app settings, scroll to **Features**.
2. Ensure **Payouts** is enabled.
3. If not enabled, 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

1. Go to **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

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

- 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

1. In Developer Dashboard, go to **Sandbox > Accounts**.
2. Click **Create Account**.
3. Select **Business**the  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

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/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

- **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

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