On this page
No Headings
Get started
Last updated: June 4, 2026
DOCS
Your account structure is contingent upon the settlement model you select. There are two settlement models:
Merchant Settlement account: PayPal pays your merchants directly.
Partner Settlement account: PayPal issues payments to you, and you pay your merchants.
Be sure to create all accounts as PayPal business accounts. You'll create the same accounts in both sandbox and live environments.
You need certain accounts, such as API caller and Organization accounts, for both settlement models. Other accounts, such as partner fees and settlement accounts, are necessary only for a specific model.
Account types
The following table provides an overview of the different account types in Managed Path:
| Account | Purpose |
|---|---|
| API caller account | Use this account to run the PayPal APIs. Create a developer REST API app for this account and use the app to interact with the PayPal APIs. This account also has access to PayPal's SFTP server for reports. |
| Organization account | Acts as the parent for all non-loginable merchant accounts. All non-loginable merchant accounts that you create under this account inherit its settings. |
| Partner fee account | Use this account to settle partner or platform fees for transactions processed by non-loginable merchant accounts. This account requires a verified bank account attached to it for auto-sweep of fees. |
| Recoupment account | Use this account to recover costs from negative balances accumulated by merchants. This account does not require a bank account and pays fees through invoices. |
| Non-loginable merchant (NLM) account | This is the reference account you create for each merchant using the Managed Accounts API. A reference account is a non-loginable PayPal business account you manage fully through PayPal APIs. |
Configure your sandbox environment
After creating the accounts, use your sandbox accounts to test onboarding and transactions before going live. You'll need to create and configure accounts to support the testing process.
Create your sandbox accounts
-
Log in to your developer dashboard.
-
Select Testing Tools > Sandbox Accounts > Create accountfrom your developer dashboard.
-
For the customized account, select Create.
1. In Create Custom Sandbox Account, set Account type to Business.
2. Select the appropriate country in Country/Region.
3. In Account details, enter the account information.
4. In Payment methods, enter the PayPal balance as zero.
5. Select Create account.
-
Repeat Steps 2-3 for all the required PayPal accounts specific to your integration.
Create a REST API app in your sandbox account
- From your developer dashboard, select Apps & Credentials.
- Select Create App.
- Enter a name for your application.
- Under Type, select Merchant.
- Be sure to select your API caller account as the Sandbox Business Account.
- Select Create App.
Note: After you create your sandbox accounts and REST API app's Client ID, share them with your PayPal integration engineer (or Contact us), to configure the sandbox environment.
Set up webhooks
Webhooks are HTTP callbacks that receive notification messages for events. You can subscribe to webhooks through the developer portal or by making an API call.
To subscribe to webhooks from your developer portal:
- Log in to your developer dashboard. Select Apps & Credentials. In Production, this should be your API caller account.
- Select the name of your REST API app for your API caller account
- Scroll down to Sandbox Webhooks and select Add Webhook.
- Enter the URL for your listener.
- Add the event name by selecting the required checkboxes. Select Save.
For more information about onboarding webhooks, payment webhooks, and other types of webhooks, see webhooks.
To subscribe to webhooks by making an API call, see Webhooks for the sample requests and responses. Refer to the event names for details on the webhook type you want to subscribe to.
For successful onboarding, subscribe to the following webhooks:
CUSTOMER.MANAGED-ACCOUNT.ACCOUNT-CREATED, which indicates that an account is created.CUSTOMER.MANAGED-ACCOUNT.ACCOUNT-STATUS-CHANGED, which indicates that the verification status of an account has changed.CUSTOMER.MANAGED-ACCOUNT.ACCOUNT-UPDATED, which is returned in response to a request to edit the account data
For more information on these webhooks, see Create merchant accounts, Verify merchant accounts, and Update merchant accounts.
Configure your live environment
For configuring the applicable accounts in the Live environment, for your integration, work with your PayPal integration engineer (or Contact us) to ensure that the accounts are set up as expected.
Credentials reference
The following credentials are essential to integrate and use PayPal REST APIs in your Managed Path integration:
- Client ID: Used to generate the access token required to make PayPal API calls in sandbox and live environments.
- BN code: Build-notation code. Used to:
- Uniquely identify the entity placing the API call as a PayPal partner.
- Enable tracking all transactions that originate from the PayPal partner.
- Note: After configuring your sandbox and live accounts, your PayPal integration engineer will provide the BN code.
- Partner-merchant ID (Payer ID): Unique account ID assigned to every PayPal account. (remains constant for entire lifetime of the PayPal account).
Retrieve client ID
The procedure to retrieve the Client ID is the same for sandbox and live environments. In the developer dashboard, ensure that you toggle to the appropriate environment to retrieve the correct credentials.
- Navigate to the developer dashboard and select Apps & Credentials. The apps page is displayed.
- Select the appropriate app. The client ID is displayed at the top of the app settings page.
Information on BN code
For related information, see PayPal Partner attribution ID.
After configuring your sandbox and live accounts, your PayPal integration engineer will provide the BN code.
Retrieve partner-merchant ID
The procedure to retrieve the partner-merchant ID is the same for sandbox and live environments. In the developer dashboard, ensure that you toggle to the appropriate environment to retrieve the correct credentials.
- Navigate to the developer dashboard > Testing Tools > Sandbox Accounts. All configured accounts are displayed under Account Name.
- Click on the account whose ID you want to retrieve. The Account ID (partner-merchant ID) is displayed in the Account Infosection.