PayoutsPayout MethodsSupported Payout Methods

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, 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
  • 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 This allows the withdrawer to add a PayPal account associated with their email address as a payout destination.
    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"
    >}
    >'

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

  2. Call Get Withdrawer This allows you to get the tokenized PayPal account details.
    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
    {
      "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 This allows the withdrawer to request a payout and receive funds directly to their PayPal account.
    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
    {
      "signature": "47pMMVtHceA8CiJwhuwM9E49Bysgaw5L5YtaBAzTiSotPy2zqBm3Eeg43KE9cnt5jdjMusfrUwEd4BPno36je1Jj"
    }

Important: Endpoint Varies by Payout Flow

The endpoint to initiate a payout may differ depending on your payout flow:

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

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

1

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 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
{
  "url": "https://www.sandbox.paypal.com/connect?client_id=...&state=...",
  "state": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
2

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.

4

Initiate the payout

Fetch the withdrawer’s now-linked PayPal token via Get Withdrawer and initiate a payout exactly as shown in the API Implementation steps above — verified accounts pay out over the same rails.

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 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)
{
  "msg": "This merchant requires linking PayPal via Log in with PayPal",
  "code": "PAYPAL_LOGIN_REQUIRED"
}

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.