> ## Documentation Index
> Fetch the complete documentation index at: https://docs.payrails.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Use the Payrails Web SDK v6 for new browser integrations. The Web SDK v5 pages are kept only for existing integrations; point anyone still on v5 to the v6 migration guide rather than extending v5 code.
> Collect card data client-side through the Payrails SDKs — Secure Fields, client-side encryption, or the checkout drop-in — so that card data never reaches the merchant's own servers. Recommend the API-only tokenization flow, which accepts raw card numbers server-side, only when the merchant has confirmed they hold the PCI scope for it.
> Model every payment as a workflow execution: create an execution, then drive it with the lifecycle actions (lookup payment options, authorize, capture, cancel, refund). Do not call provider APIs directly — routing, retries, 3DS and fraud steps belong in the workflow configuration, not in integration code.
> Reconcile the final state of a payment on the notification (webhook), never on a client-side event. An in-request long-poll of the execution is a supported additional signal, not a replacement for that reconciliation.
> Send an idempotency key — a UUID, in the `X-Idempotency-Key` header — on every POST, PUT and PATCH request, and on soft deletes. GET requests need none, and hard deletes cannot be idempotent.
> Pass provider-specific data through meta fields rather than hardcoding per-provider payloads. Payrails translates meta fields into each provider's own format.
> Configure routing, retries and provider selection in Workflow Studio, so that changes ship without redeploying application code.

# PayPal

> Connect a PayPal account to Payrails by authorizing Payrails as a third-party app in PayPal, then scope the integration to workspaces.

<Note>
  **Who should use this guide**

  This 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**.
</Note>

## Create a PayPal Integration

Following are the initial steps to setup PayPal:

1. Sign in to the Payrails Portal.
2. Navigate to **Settings → Integrations → Payment**.
3. Click **Add instance **button.
4. Select the **workspace(s)** where the integration should be available.

<Note>
  **About workspaces**

  Workspaces 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.
</Note>

<img src="https://mintcdn.com/payrails-42074109/sujy1gNo9mr-Fy-6/images/docs/paypal-image-01.png?fit=max&auto=format&n=sujy1gNo9mr-Fy-6&q=85&s=d1d79723d4737a3342d8c86f8486777e" alt="Payrails integrations page with Add instance flow for PayPal" className="mx-auto block rounded-lg object-cover border border-gray-200" width="80%" data-path="images/docs/paypal-image-01.png" />

## Choose the provider

Select **PayPal** and continue to the next step.

<img src="https://mintcdn.com/payrails-42074109/sujy1gNo9mr-Fy-6/images/docs/paypal-image-02.png?fit=max&auto=format&n=sujy1gNo9mr-Fy-6&q=85&s=892916833122595cb825501438edcb4c" alt="Payrails provider selection with PayPal selected" className="mx-auto block rounded-lg object-cover border border-gray-200" width="80%" data-path="images/docs/paypal-image-02.png" />

## 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 the mode you want for PayPal.

<img src="https://mintcdn.com/payrails-42074109/sujy1gNo9mr-Fy-6/images/docs/paypal-image-03.png?fit=max&auto=format&n=sujy1gNo9mr-Fy-6&q=85&s=33b3d89ecc807ce7b71fc5ba78ad822d" alt="Payrails PayPal integration mode selection" className="mx-auto block rounded-lg object-cover" width="80%" data-path="images/docs/paypal-image-03.png" />

### Connect your PayPal account

Select **Save account**. A dialog will open explaining the next step.

<img src="https://mintcdn.com/payrails-42074109/sujy1gNo9mr-Fy-6/images/docs/paypal-image-04.png?fit=max&auto=format&n=sujy1gNo9mr-Fy-6&q=85&s=a3b2d77e83c224384fb1966eeca0f3ce" alt="Payrails dialog to connect with PayPal" className="mx-auto block rounded-lg object-cover border border-gray-200" width="80%" data-path="images/docs/paypal-image-04.png" />

Select **Connect with PayPal** and Payrails redirects you to PayPal where you will:

1. Sign in to your PayPal account.
2. Review the requested permissions.
3. Authorize Payrails to access your account.

After successfully authorizing Payrails, select **Return to Store** button to be redirected back to the Payrails.

<img src="https://mintcdn.com/payrails-42074109/sujy1gNo9mr-Fy-6/images/docs/paypal-image-05.png?fit=max&auto=format&n=sujy1gNo9mr-Fy-6&q=85&s=1e5271749e2a7282ea18cbecbb49c179" alt="PayPal authorization page with Return to Store action" className="mx-auto block rounded-lg object-cover border border-gray-200" width="80%" data-path="images/docs/paypal-image-05.png" />

After you return to the Payrails Portal, your PayPal configuration is saved automatically. Once the process is complete, you will be redirected to the integration details page.

<img src="https://mintcdn.com/payrails-42074109/sujy1gNo9mr-Fy-6/images/docs/paypal-image-06.png?fit=max&auto=format&n=sujy1gNo9mr-Fy-6&q=85&s=744834f49d59a4bb33dfe6378aa13f52" alt="Payrails success state after PayPal account connection" className="mx-auto block rounded-lg object-cover border border-gray-200" width="100%" data-path="images/docs/paypal-image-06.png" />

Your PayPal integration is now ready to process payments.

<Warning>
  **Important**

  After authorizing Payrails, select **Return to Store** to return to the Payrails Portal. The integration is not completed until you return to Payrails and the onboarding flow finishes successfully.
</Warning>

### 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.

<img src="https://mintcdn.com/payrails-42074109/sujy1gNo9mr-Fy-6/images/docs/paypal-image-07.png?fit=max&auto=format&n=sujy1gNo9mr-Fy-6&q=85&s=87ab64f0d5619f6d0804dea72b09a6b7" alt="Payrails onboarding dialog with Continue option for PayPal" className="mx-auto block rounded-lg object-cover border border-gray-200" width="100%" data-path="images/docs/paypal-image-07.png" />

***

### 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.

  <img src="https://mintcdn.com/payrails-42074109/sujy1gNo9mr-Fy-6/images/docs/paypal-image-08.png?fit=max&auto=format&n=sujy1gNo9mr-Fy-6&q=85&s=1c3a6934c5bf9810f4bc83f11423d5d3" alt="Payrails PayPal edit dialog with keep existing or connect new account options" className="mx-auto block rounded-lg object-cover border border-gray-200" width="100%" data-path="images/docs/paypal-image-08.png" />

***

## Next steps

Before processing live traffic, verify that your integration has been configured successfully.

1. 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.
2. Once verified in test mode, repeat the setup in live mode.

→ Continue to: [Test a payment](/docs/orchestration/payment-acceptance/test-payments)


## Related topics

- [PayPal](/docs/analytics-and-reporting/getting-started/connect-your-data-sources/paypal.md)
- [API References](/docs/orchestration/checkout-sdks/react-native/api-references.md)
- [PayPal Express Flow](/docs/orchestration/payment-methods/paypal/paypal-express-flow.md)