Connecting PayPal lets wxrks send vendor payouts directly from the Payables list and, once webhooks are configured, update each payable to Paid or Error automatically as PayPal confirms the transfer. This guide covers both sides of the integration: what you create in the PayPal Developer Dashboard, and what you configure in wxrks.
Prerequisites & Permissions
Plan: The Payment Integrations tab is available on Business and Enterprise plans.
Role & Permission: Requires the Account Admin role. Paying a payable additionally requires the Payable mark as paid and make payment permission.
PayPal account: A PayPal Business account, verified and enabled for Payouts, with a balance held in the currency you will pay in.
Vendors: Each vendor you intend to pay through PayPal must have Payment Method set to PayPal on their user profile, under People > Users > [User] > Billing & Languages. Selecting it reveals the PayPal Account field, where the vendor's PayPal e-mail address goes. A payout cannot be sent to a vendor without it.
Keep both tabs open: You will move back and forth between the PayPal Developer Dashboard and wxrks throughout the wizard.
NOTE: wxrks in production connects to the **Live** PayPal environment, so the credentials you create must be **Live** credentials. Sandbox credentials only work on wxrks test environments.
Key Concepts
Term | Description |
Client ID / Client Secret | The API credentials of the PayPal app you create. wxrks uses them to authenticate every payout request on behalf of your account. |
Payouts | The PayPal feature that sends money to multiple recipients in one batch. This is the feature wxrks uses to pay vendors. |
Webhook | A callback URL you register in PayPal. PayPal calls it whenever the state of a payout changes, so wxrks can move the payable forward without anyone re-checking it manually. |
Webhook ID | The identifier PayPal assigns to the webhook you created. wxrks stores it and uses it to verify that incoming notifications genuinely came from PayPal. |
Payable status | The lifecycle of a vendor invoice in wxrks: Ready to Processing to Paid, or Error when PayPal rejects the transfer. |
Part 1 — Create your app in PayPal
Step 1: Open the PayPal Developer Dashboard
Go to
https://developer.paypal.com/dashboard/and log in with your PayPal Business account.Switch the environment selector at the top of the page from Sandbox to Live.
WARNING: Sandbox and Live are completely separate. Credentials, apps, and webhooks created in one environment never work in the other.
Step 2: Create a REST API app
Open the Apps & Credentials tab.
Click Create App.
Enter a name that identifies the integration, for example
wxrks, and confirm.
PayPal generates the app and displays its Client ID and Client Secret.
Step 3: Copy the Client ID and Client Secret
Copy the Client ID.
Click Show next to Secret and copy the Client Secret.
WARNING: The Client Secret is a private credential. Never send it by e-mail, in a support ticket, in a chat, or commit it to a repository. If it leaks, revoke it in PayPal and generate a new one.
Step 4: Confirm the Payouts permission
On the same app page, scroll down to the Features section.
Confirm that Payouts is enabled for the app.
wxrks sends money through the PayPal Payouts API. Without this feature enabled, the credentials authenticate correctly but every payment attempt fails.
NOTE: Payouts may require PayPal to review and approve your business account before it can be enabled. If the feature is unavailable or shows as pending, request access with PayPal before continuing.
Part 2 — Configure PayPal in wxrks
Step 5: Open the Payment Integrations tab
In wxrks, go to Settings > Account Settings > Finance.
Open the Payment Integrations tab.
Leave Payment Method set to Paypal.
The PayPal setup wizard opens on step 1 of 5. Steps 1 and 3 are read-only instructions that mirror what you already did in Part 1, so you can move through them with Next.
Step 6: Enter and test your credentials
Click Next until you reach step 2, Set Your paypal Credentials.
Paste your Client ID into the first field and your Client Secret into the second. Both fields are masked; use the eye icon to reveal what you pasted and confirm there are no leading or trailing spaces.
Click Test credentials.
wxrks calls PayPal with the credentials and shows Credentials checked! when the authentication succeeds.
NOTE: The **Next** button stays disabled until the test passes. Editing either field after a successful test clears the result, so you have to test again — this prevents saving a credential pair that was never validated.
Step 7: Register the webhook in PayPal
Step 4 of the wizard, Configure PayPal Webhook, is what turns automatic status updates on. wxrks displays the exact URL PayPal must call.
In wxrks, copy the webhook URL using the Copy button next to it. If both a US / Global and an EU URL are shown, pick the one matching where your PayPal business account is registered.
Back in the PayPal Developer Dashboard, open your app and scroll to the Webhooks section.
Click Add Webhook and paste the URL into the webhook URL field.
Subscribe the webhook to the Payments & Payouts events.
Save the webhook. PayPal then displays a Webhook ID.
NOTE: The webhook URL is unique to your wxrks account — it identifies which account the incoming events belong to. Do not reuse another account's URL.
Step 8: Save the Webhook ID and finish
Copy the Webhook ID from PayPal.
Paste it into the Paste PayPal Webhook ID here field in wxrks.
Click Save.
The wizard advances to the confirmation step, which states that PayPal was successfully configured on your account.
WARNING: Saving without a Webhook ID still enables payouts, but disables automatic reconciliation. Payables paid that way land in **Awaiting reconciliation** and stay there until someone closes them manually. Fill in the Webhook ID unless your finance team reconciles payments in an external accounting tool.
What happens after a payment
Once the integration is saved, select payables in Ready status from the Payables list and pay them. The status then follows PayPal:
Event in PayPal | Status in wxrks | Who is notified |
Payout batch accepted and processing | Processing | — |
Payout batch completed successfully | Paid | The vendor receives a payment confirmation |
Payout denied, failed, blocked, held, returned, refunded, unclaimed, or canceled | Error | The vendor and the account admin who triggered the payment |
When a payable moves to Error, hover over its status badge in the Payables list to read the reason returned by PayPal.
NOTE: wxrks only acts on payout events for payouts it started, and verifies every notification's signature with PayPal before changing a status. Notifications that fail verification are ignored.
Changing or removing the credentials
To update credentials or the Webhook ID: return to the Payment Integrations tab and walk through the wizard again. Also update the corresponding app or webhook in PayPal so both sides stay in sync.
To disconnect PayPal: click the red trash button next to the Payment Method selector and confirm. Payouts through PayPal stop immediately; existing payables keep their current status.
Troubleshooting & Common Errors
Issue / Error | Cause | Solution |
"Credentials not valid!" after clicking Test credentials | Wrong environment, a typo, or an extra space in the Client ID or Secret. | Reveal both fields and re-paste them from the PayPal app page. Confirm both values come from the same app in the Live environment. |
Next is greyed out on step 2 | The credentials have not been validated yet, or a field was edited after the last successful test. | Click Test credentials again and wait for Credentials checked!. |
"As your PayPal balance is not held in this currency, you'll not be able to send Payouts." | Your PayPal account holds no balance in the payable's currency. | Add a balance in that currency in PayPal, or change the payable's currency. |
"Currency is not supported by PayPal. Please check the currency." | The payable's currency is outside PayPal's supported list. | Check PayPal's supported currencies and set a supported currency on the payable. |
Payable stays in Processing | PayPal has not sent a final event yet, or the webhook is misconfigured. | Confirm in PayPal that the webhook URL matches the one shown in wxrks, that it is subscribed to the Payments & Payouts events, and that the Webhook ID saved in wxrks belongs to that webhook. |
Payable goes to Awaiting reconciliation instead of Processing | No Webhook ID is saved in wxrks. | Complete step 4 of the wizard with the Webhook ID from PayPal. |
Payment fails for one vendor only | That vendor's Payment Method is not PayPal, or the PayPal Account e-mail is missing or wrong. | Open People > Users > [User] > Billing & Languages, set Payment Method to PayPal, fill in the PayPal Account e-mail, then retry the payment. |
Everything works in a test environment but not in production | Test environments talk to PayPal Sandbox; production talks to PayPal Live. | Create a Live app and Live webhook, and save the Live credentials in production. |
Quick Reference
Item | Value |
Where to configure | Settings > Account Settings > Finance > Payment Integrations |
Required role | Account Admin |
Permission to pay a payable | Payable mark as paid and make payment |
Wizard steps | 5 (instructions, credentials, payouts permission, webhook, confirmation) |
Required PayPal feature | Payouts |
Webhook event group | Payments & Payouts |
Payment method options | Paypal, QuickBooks (when enabled for your account) |
Status with webhook configured | Ready, Processing, Paid or Error |
Status without webhook configured | Ready, Awaiting reconciliation |
PayPal environment used in production | Live |