> ## 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 how the PayPal checkout behaves for your customers.

| Mode | How it works |
| :- | :- |
| **Normal** | You collect the buyer's details in your own checkout. The buyer completes your checkout steps, then approves the payment on PayPal with **Pay Now**. PayPal doesn't ask for a shipping address. |
| **Express** | The buyer goes to PayPal early, for example from a product or cart page. PayPal returns the buyer's name, email and shipping address, so they type less. The shipping address comes from the buyer's PayPal account unless you set `meta.order.deliveryAddressPreference`. |

The mode applies to one-off PayPal payments. Payments with a saved PayPal account work the same in both modes.

<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" />

***

## Request fields for PayPal

Send these fields in the [authorize request](/reference/authorizeaction), 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](/docs/orchestration/meta-fields).

| Field | Status | Description |
| :- | :- | :- |
| `amount` | Required | Sent to PayPal as the purchase unit amount. |
| `merchantReference` | Optional | Sent as the purchase unit reference and invoice ID. |
| `meta.customer.language` | Optional | Sent as the checkout locale. |
| `meta.order.description`, `meta.order.softDescriptor` | Optional | Sent as the purchase description and soft descriptor. |
| `meta.order.lines` | Optional | Sent as items. Each line item needs `name` and `unitPrice`. The lines and shipping must add up to `amount`. |
| `meta.order.shipping` | Optional | Sent as the shipping total. |
| `meta.order.deliveryAddress` | Optional | Sent as the shipping address when PayPal collects one. Include `country.code`. |
| `meta.customer.name`, `meta.customer.lastName` | Optional | Sent as the shipping name. |
| `meta.order.deliveryAddressPreference` | Optional | Express mode only. `noShipping`, `userPreSpecified` or `allowProviderOverride`. Refer to [Select integration mode](#select-integration-mode). |

***

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

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 via Braintree](/docs/orchestration/payment-methods/paypal/braintree.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.