Who should use this guideThis guide is intended for merchants who:
- Use Payrails as a payment orchestrator
- Want to connect their PayPal account to Payrails.
- Have permission to authorize third party applications within PayPal.
Create a PayPal Integration
Following are the initial steps to setup PayPal:- Sign in to the Payrails Portal.
- Navigate to Settings → Integrations → Payment.
- Click Add instance button.
- Select the workspace(s) where the integration should be available.
About workspacesWorkspaces determine where this integration is available. They let you isolate provider setups by region or business line, or share the same configuration across multiple workspaces.
Choose the provider
Select PayPal and continue to the next step.
Configure your PayPal integration
This path uses PayPal’s OAuth flow to connect your PayPal account to Payrails. You don’t need to manually copy API credentials or webhook secrets.Integration instance name
Enter an Instance name for your integration. An integration instance is a specific payment provider setup in Payrails. You can create multiple instances for each provider based on region, currency, or business needs. Choose a clear, consistent name, as it is used in routing.Select integration mode
Under Integration Mode, select how the PayPal checkout behaves for your customers.
The mode applies to one-off PayPal payments. Payments with a saved PayPal account work the same in both modes.
Connect your PayPal account
Select Save account. A dialog will open explaining the next step.
- Sign in to your PayPal account.
- Review the requested permissions.
- Authorize Payrails to access your account.
Continue onboarding
If the onboarding process is interrupted after you authorize PayPal—for example, if the browser is closed or the redirect back to Payrails does not complete—return to the original Payrails Portal tab. If the onboarding wasn’t completed, the dialog will display a Continue button. Select Continue to resume and complete the onboarding process.
Editing an existing PayPal integration
In edit mode, when you re-open PayPal integration, the configuration screen identifies the currently connected PayPal account and lets you choose between keeping the existing connection or connecting a different PayPal account. When you select Save account, a dialog offers two options:- Save Changes — It will preserve the current connection.
-
Connect new account — start a fresh OAuth flow with a different PayPal account.
Request fields for PayPal
Send these fields in the authorize request, in addition to the standard authorize fields. Required fields must be present for the payment to succeed. Payrails sends Optional fields to PayPal when you include them. For more about meta fields, refer to Meta fields.Configure PayPal settings
Some PayPal integration settings change how Payrails processes your payments. The portal shows the same description when you hover over each setting.Fetch payer details on decline
When PayPal declines an authorize or capture, the declined response normally carries no details about the buyer. Turn on Fetch payer details on decline to have Payrails look the order up again, so the failed operation still returns the buyer’s PayPal email, payer ID, billing country and postal code. Use it when you need these details after a decline, for example for post-authorization fraud scoring.Partner Referral Onboarded
Payrails turns on Partner Referral Onboarded when you connect your PayPal account. The setting shows that Payrails manages your PayPal credentials and account IDs. You can’t change it by hand.Next steps
Before processing live traffic, verify that your integration has been configured successfully.- We recommend confirming that:
- The PayPal account is connected successfully.
- The integration status is healthy.
- The correct workspace is selected.
- A test payment completed successfully.
- Once verified in test mode, repeat the setup in live mode.