> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.coinflow.cash/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.coinflow.cash/_mcp/server.

# PayPal

## Overview

PayPal payouts allow users to receive instant payments directly to their PayPal account. This payout method is available for US-based users and provides a familiar, convenient payment experience.

## UI Implementation

If you're using Coinflow's [Bank Authentication UI](/guides/payouts/implementation-methods/bank-authentication-ui), PayPal support is automatically included once enabled on your merchant account.

**For Merchant-Initiated Payouts:**

* Users can link their PayPal account directly through the UI
* Retrieve the PayPal token using the [Get Withdrawer Endpoint](/api-reference/api-reference/withdraw/get-withdrawer)
* Pass the token to your payout endpoint just like bank account or card tokens

**For User-Initiated Payouts via SDKs:**

* No additional implementation required
* Contact your Coinflow integration specialist to enable PayPal for your account
* PayPal will automatically appear as a payout option in the SDK

## API Implementation

After following your usual KYC verification flow, follow these steps to allow linking a PayPal payout destination:

1. [Link PayPal Account](/api-reference/api-reference/withdraw/add-paypal)
   This allows the withdrawer to add a PayPal account associated with their email address as a payout destination.

   **`Request`**

   ```curl Request
   curl --request POST \
        --url https://api-sandbox.coinflow.cash/api/withdraw/paypal \
        --header 'Authorization: YOUR_API_KEY' \ # gitleaks:allow
        --header 'accept: application/json' \
        --header 'content-type: application/json' \
        --header 'x-coinflow-auth-user-id: user1234' \
        --data '
   {
     "email": "user@example.com"
   }
   '
   ```
   > **Info**
   >
   > A raw email or phone number is only as accurate as what the withdrawer types.
   > If they mistype their PayPal contact — or enter one they don't own — the payout
   > fails later at disbursement. To eliminate that failure mode, link a **verified**
   > PayPal account with [Log in with PayPal](#log-in-with-paypal-verified-linking)
   > instead.
2. [Call Get Withdrawer](/api-reference/api-reference/withdraw/get-withdrawer)
   This allows you to get the tokenized PayPal account details.

   **`Request`**

   ```curl Request
   curl --request GET \
        --url https://api-sandbox.coinflow.cash/api/withdraw \
        --header 'Authorization: YOUR_API_KEY' \ # gitleaks:allow
        --header 'accept: application/json' \
        --header 'x-coinflow-auth-user-id: user1234'
   ```

   **`Response`**

   ```Text Response
   {
     "withdrawer": {
       "_id": "68aa405463dc197a7d9410cc",
       "__v": 0,
       "availability": {
         "status": "Functional",
         "reason": "Initial",
         "editor": "system",
         "updatedAt": "2025-08-23T22:27:31.970Z"
       },
       "currency": "USD",
       "email": "shdhdj@gmail.com",
       "merchant": "6840bca9c7cb21ee5baaae76",
       "originalCurrency": "USD",
       "riskScoreOverride": false,
       "user": true,
       "verification": {
         "hash": "8279804db6754cd1bf3d21b81eea4fa630321e1a",
         "vendor": "persona",
         "reference": "ver_sjrs9QqtDujv9kv4oKdgP8zo81Nn",
         "status": "approved",
         "attested": false
       },
       "wallets": [
         {
           "wallet": "user1234",
           "blockchain": "user"
         }
       ],
       "watchlistExempt": "Unknown",
       "bankAccounts": [],
       "cards": [],
       "ibans": [],
       "pixes": [],
       "efts": [],
       "rtpDisabled": false,
       "cardDisabled": false,
       "paypal": {
         "type": "paypal",
         "alias": "user@example.com",
         "token": "b4c6d82c-9843-53c1-93ea-bgbe25g62464" // gitleaks:allow
       }
     }
   }
   ```
3. [Initiate Payout](/api-reference/api-reference/merchant/payout-from-delegated-settlement-wallet)
   This allows the withdrawer to request a payout and receive funds directly to their PayPal account.

   **`Request`**

   ```curl Request
   curl --request POST \
        --url https://api-sandbox.coinflow.cash/api/merchant/withdraws/payout/delegated \
        --header 'Authorization: YOUR_API_KEY' \ # gitleaks:allow
        --header 'accept: application/json' \
        --header 'content-type: application/json' \
        --data '
   {
     "amount": {
       "cents": 400
     },
     "speed": "paypal",
     "account": "b4c6d82c-9843-53c1-93ea-bgbe25g62464", // PayPal token (Get from calling get withdrawer)
     "userId": "user1234",
     "idempotencyKey": "123-abc-456-def" // gitleaks:allow
   }
   '
   ```

   **`Response`**

   ```Text Response
   {
     "signature": "47pMMVtHceA8CiJwhuwM9E49Bysgaw5L5YtaBAzTiSotPy2zqBm3Eeg43KE9cnt5jdjMusfrUwEd4BPno36je1Jj"
   }
   ```

> **Warning**
>
> **Important: Endpoint Varies by Payout Flow**
>
> The endpoint to initiate a payout may differ depending on your payout flow:
>
> * **Merchant-funded payouts:** Pass the PayPal token to the [do payout](/api-reference/api-reference/merchant/do-payout) endpoint
> * **User-initiated payouts:** Pass the PayPal token to the [get transaction endpoint](/api-reference/api-reference/withdraw/get-transaction)

## Log in with PayPal (Verified Linking)

Instead of trusting a raw email or phone number, you can have withdrawers **log in
to PayPal** and consent to sharing their identity. Coinflow then links the payout
account to the email PayPal has *confirmed* the user owns, so the payout target can
no longer be mistyped or point at an account the withdrawer doesn't control.

This uses PayPal's [Log in with PayPal](https://developer.paypal.com/docs/log-in-with-paypal/)
OAuth flow. Coinflow owns the PayPal integration end-to-end: **PayPal always returns to
Coinflow**, Coinflow links the verified account, and then redirects the withdrawer back
to a page on your site. You never register anything with PayPal and never handle the
authorization `code` yourself.

### Prerequisites

> **Info**
>
> Log in with PayPal must be enabled on your Coinflow merchant account — contact your
> Coinflow integration specialist. The `returnUrl` you supply below must be one of your
> merchant account's **whitelisted URLs**; the values shown here (`https://your-app.example.com/...`)
> are **examples only**.

### Integration Steps

#### Start the login flow

Call the start endpoint with a `returnUrl` — the page on **your** site to send the
withdrawer back to once linking finishes. Coinflow responds with a PayPal `url` to
redirect to (and a `state`, which you don't need to store — Coinflow handles it).

**`Request`**

```curl Request
curl --request POST \
     --url https://api-sandbox.coinflow.cash/api/withdraw/paypal/login \
     --header 'Authorization: YOUR_API_KEY' \ # gitleaks:allow
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'x-coinflow-auth-user-id: user1234' \
     --data '
{
  "returnUrl": "https://your-app.example.com/payouts/paypal-linked"
}
'
```

**`Response`**

```Text Response
{
  "url": "https://www.sandbox.paypal.com/connect?client_id=...&state=...",
  "state": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```

#### Redirect the withdrawer to PayPal

Send the withdrawer to the returned `url`. They log in to PayPal and consent to
sharing their name and email. PayPal then redirects them to **Coinflow's** hosted
return handler — not to your site. You don't configure or handle this URL.

#### Coinflow links the account and returns the withdrawer to you

Coinflow exchanges the `code`, verifies the identity, links the verified PayPal
payout account, and then redirects the withdrawer's browser back to your
`returnUrl` with a result flag appended:

**`Redirect back to your app`**

```Text Redirect back to your app
https://your-app.example.com/payouts/paypal-linked?paypalLinked=success
```

On failure the flag is `paypalLinked=error`. No callback request is required from
you — the account is already linked by the time the withdrawer lands back on your
page.

#### Initiate the payout

Fetch the withdrawer's now-linked PayPal token via
[Get Withdrawer](/api-reference/api-reference/withdraw/get-withdrawer) and initiate
a payout exactly as shown in the [API Implementation](#api-implementation) steps
above — verified accounts pay out over the same rails.

> **Info**
>
> Because PayPal always returns to Coinflow's own URL, you never register a redirect URL
> with PayPal and never see the authorization `code`. You only provide a `returnUrl` on
> your site, which must be one of your merchant account's whitelisted URLs.

### Requiring Verified Linking

Merchants can require that **all new** PayPal payout accounts be linked through Log in
with PayPal. When this is enabled on your account, the standard
[Link PayPal Account](#api-implementation) endpoint rejects raw email/phone adds with
a `403` and a machine-readable error code so you can route the withdrawer into the
login flow instead:

**`Response (403)`**

```Text Response (403)
{
  "msg": "This merchant requires linking PayPal via Log in with PayPal",
  "code": "PAYPAL_LOGIN_REQUIRED"
}
```

> **Info**
>
> This setting is **not retroactive** — PayPal accounts that were already linked by
> email or phone remain payable. It only affects *new* account adds. Contact your
> Coinflow integration specialist to enable it.