Connecting PayPal

Where each PayPal connector field lives in the PayPal Developer Dashboard, which fields to leave blank, and which credentials each environment uses.

The PayPal connector asks for five values and two checkboxes. Only Client ID and Client secret are required. This page shows where each one comes from and which ones a merchant connecting their own PayPal account should leave empty.

A one-click connection, where you sign in to PayPal, authorize Throttle, and paste nothing, is planned. Until it ships, this is the path.

Before you start

You need a PayPal Business account. A personal account cannot create the REST app the connector uses. If you do not have one yet, upgrade at paypal.com under Account settings before continuing.

You also need to decide which Throttle environment you are connecting. Connections are per environment, and PayPal issues separate credentials for its sandbox and its live system:

Throttle environmentPayPal credentials to use
Any non-production environment (for example test)Sandbox tab in the Developer Dashboard
productionLive tab in the Developer Dashboard

Sandbox credentials in production, or live credentials in a test environment, fail to authenticate. Match the tab to the environment.

1. Create a REST app

  1. Sign in at developer.paypal.com with your business account.
  2. Open Apps & Credentials.
  3. Choose the Sandbox or Live tab to match the table above.
  4. Choose Create App, give it a name such as “Throttle”, and create it.

You can reuse an existing app if you already have one for another integration. The credentials are the same either way.

2. Client ID and Client secret

Both are on the app’s page you just created or opened.

  • Client ID is shown in full. Copy it into the connector’s Client ID field.
  • Client secret is hidden behind Show. Reveal it and copy it into the Client secret field.

Throttle stores the secret encrypted and never displays it again. If you lose it, generate a new secret in PayPal and update the connection.

3. Webhook ID (optional, leave blank for now)

A webhook lets PayPal tell Throttle about things that happen inside PayPal, such as a refund or a dispute a buyer opens there. Registering one requires a webhook URL to point PayPal at.

Throttle does not yet display that URL after a connection is created, so there is nothing to register. Leave the field blank. Payments, captures, and refunds started from Throttle work without it.

4. BN Code (leave blank)

A BN code is a partner attribution code that PayPal issues to platforms which integrate on behalf of other merchants. It is not something a merchant is given for their own account. Leave it blank.

5. Merchant ID (leave blank)

This field exists for partner setups, where the Client ID belongs to a platform acting for your account and PayPal needs to know which merchant to act as. When you connect with your own app’s credentials, the Client ID already identifies your account, so leave it blank.

If you are told to fill it in by someone operating a PayPal partner integration on your behalf, the value is your PayPal Merchant ID, found in PayPal under Account settings → Business information. It is not your Throttle workspace or application id.

6. Ingest billing and shipping details

Two checkboxes. When enabled, the address PayPal holds for the buyer is used on the payment record for that side (billing or shipping). Leave them off unless you want PayPal’s stored address to take precedence over what the buyer entered at checkout.

7. Save and activate

Choose the accepted countries and currencies, then save. The connection appears on the Connectors page. Activate it there, and if more than one connector is active, check the routing rules so PayPal is offered where you expect.

To confirm it works in a sandbox environment, run a checkout with a PayPal sandbox buyer account and look for the payment on the Payments page.

If it does not authenticate

  • Wrong tab. Sandbox credentials in production or live credentials in a test environment both fail. Check the table at the top.
  • Personal account. The REST app must belong to a business account.
  • Regenerated secret. If someone generated a new secret in PayPal, the one Throttle holds is dead. Update the connection with the new value.
  • Payment connectors — Connecting a processor per environment, why sandbox and production are separate connections, and what happens to live payments if billing lapses.
  • Going live — What switching from a sandbox environment to production invalidates, in what order to change it, and the checks that gate the switch.

Last updated September 14, 2026