> ## 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 PayPal through the REST API, SFTP, or both, to ingest transaction, settlement, dispute, and fee data.

This guide will help you obtain your PayPal credentials and connect PayPal as a data source in Payrails to ingest transaction, settlement, dispute and fee data. With the self-serve flow you configure the integration yourself in the Payrails portal.

PayPal offers two integration types, and you can add either or both depending on which reports you need:

* **PayPal API** — ingests transaction data via PayPal's Transaction Search API.
* **PayPal SFTP** — ingests the full report set (transaction details, settlement, disputes/chargebacks, fees, PayPal advantage) via PayPal's reporting SFTP server.

***

## PayPal API

### Prerequisites

* An active PayPal business account.
* Access to the PayPal Developer Dashboard.

### Step-by-step instructions

#### Step 1: Create a REST API app in the PayPal Developer Dashboard

1. Log in to the PayPal Developer Dashboard and go to **Apps & Credentials**.
2. Select **Create App**, give it a name (e.g. `Payrails Reporting`), and click **Create App**.
3. On the app details page, copy and store the **Client ID** and **Client Secret**.
4. Use the **Sandbox / Live** toggle to generate credentials for each environment you need. Create a separate set of credentials for Live (production) and, if needed, Sandbox.

#### Step 2: Add the PayPal API integration in the Payrails portal (self-serve)

1. Log in to the Payrails dashboard and open **Settings → Integrations → Data**.
2. Click **Add instance** (top-right).
3. In New instance, select provider: **PayPal (API)** and click **Continue**.
4. On the **Configure account** screen, fill in:
   * **Integration instance name** — a unique label.
   * **Start Date** — the date of today or tomorrow (currently we can not backfill over the self-serve capability. In the need of backfilling, please reach out to your Payrails account manager).
   * **Client ID** and **Client Secret** — from the app created in Step 1.
   * *(Optional)* **Additional data**.
5. Click **Save account**. The instance appears in the Data integrations list and Payrails begins ingesting data.

***

## PayPal SFTP

### Prerequisites

* An active PayPal business account.
* Ability to contact PayPal Customer Service to enable report access (this is not self-service on PayPal's side).

### Step-by-step instructions

#### Step 1: Request SFTP report access from PayPal

1. Contact PayPal Customer Service (or your PayPal account manager) and ask to have your account enabled for **report access**. This is required before an SFTP user can be created.
2. Allow up to 48 hours for PayPal to enable this. PayPal sends an email to your account's primary address once it's ready.

#### Step 2: Create an SFTP user

1. Log in to your PayPal account and go to **Account Settings → Reports → Secure FTP Users**.
2. Click **Add** to create a new SFTP user, and verify your identity when prompted.
3. Choose and store a **username** and **password** for the SFTP account.
4. Note the connection details:
   * **Host**: `reports.paypal.com`
   * **Port**: `22` (default)

<Warning>
  PayPal provisions SFTP access **per region**. If you operate in multiple regions, repeat these steps for each region and create one Payrails integration instance per region.
</Warning>

#### Step 3: Add the PayPal SFTP integration in the Payrails portal (self-serve)

1. Log in to the Payrails dashboard and open **Settings → Integrations → Data**.
2. Click **Add instance** (top-right).
3. In New instance, select provider: **PayPal (SFTP)** and click **Continue**.
4. On the **Configure account** screen, fill in:
   * **Integration instance name** — a unique label (mention the region if adding more than one).
   * **Start Date** — the date of today or tomorrow (currently we can not backfill over the self-serve capability. In the need of backfilling, please reach out to your Payrails account manager).
   * **SFTP Host**, **SFTP Username**, **SFTP Password** — from the SFTP user created in Step 2.
   * **SFTP Port** — leave blank to use the default (`22`).
5. Click **Save account**. The instance appears in the Data integrations list and Payrails begins ingesting data.


## Related topics

- [PayPal](/docs/orchestration/payment-methods/paypal/index.md)
- [API References](/docs/orchestration/checkout-sdks/react-native/api-references.md)
- [PayPal Express Flow](/docs/orchestration/payment-methods/paypal/paypal-express-flow.md)