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

# PayPal options

> Configuration options for PayPal payment integration

PayPal enables customers to pay using their PayPal account, credit/debit cards, Venmo, PayPal Credit, and other funding sources.

## Quick reference

| Option | Type | Default | Description |
| - | - | - | - |
| `style.layout` | `string` | `'vertical'` | `'vertical'` or `'horizontal'` (max 2 buttons) |
| `style.color` | `string` | `'gold'` | `'gold'`, `'blue'`, `'silver'`, `'white'`, `'black'` |
| `style.shape` | `string` | `'rect'` | `'rect'` or `'pill'` |
| `style.height` | `number` | — | Button height (25-55 pixels) |
| `style.label` | `string` | `'paypal'` | `'paypal'`, `'checkout'`, `'buynow'`, `'pay'`, `'installment'`, `'subscribe'`, `'donate'` |
| `disableFunding` | `string[]` | `[]` | Funding sources to hide (cannot disable `'paypal'`) |
| `enableFunding` | `string[]` | `[]` | Funding sources to explicitly enable |
| `vault` | `boolean` | `false` | Enable payment method saving |

```javascript theme={"dark"}
checkout.options = {
  paypal: {
    style: {
      layout: 'vertical',
      color: 'gold',
      shape: 'rect',
      height: 40,
    },
    disableFunding: ['credit', 'card'],
    vault: false,
  },
};
```

***

## Button styling

Customize PayPal button appearance using the `style` object.

| Option | Type | Default | Description |
| - | - | - | - |
| `style.layout` | `string` | `'vertical'` | `'vertical'` for stacked buttons, `'horizontal'` for side-by-side (max 2 buttons) |
| `style.color` | `string` | `'gold'` | Button background color (see [values](#color) below) |
| `style.shape` | `string` | `'rect'` | `'rect'` for rectangular with slight rounding, `'pill'` for fully rounded ends |
| `style.height` | `number` | — | Button height in pixels (25–55). If not set, PayPal uses its default. |
| `style.label` | `string` | `'paypal'` | Button text: `'paypal'`, `'checkout'`, `'buynow'`, `'pay'`, `'installment'`, `'subscribe'`, `'donate'` |
| `style.tagline` | `boolean` | `false` | Show tagline. When `true`, layout defaults to `'horizontal'`. |
| `style.borderRadius` | `number` | — | Corner radius in pixels (0–55). If not set, PayPal uses its default. |
| `style.disableMaxWidth` | `boolean` | `false` | Remove max width constraint |

### Layout

**Horizontal layout** displays buttons side-by-side but is limited to **maximum 2 buttons**. When more funding sources are eligible, the SDK prioritizes PayPal and Pay Later by default. Use `enableFunding` and `disableFunding` to control which buttons appear.

### Color

Set `style.color` to change the button background. PayPal recommends gold for the strongest brand recognition.

| Value | Description |
| - | - |
| `'gold'` | Gold background (default, recommended) |
| `'blue'` | Blue background |
| `'silver'` | Silver background |
| `'white'` | White background |
| `'black'` | Black background |

### Examples

```javascript theme={"dark"}
// Horizontal blue pill buttons
paypal: {
  style: {
    layout: 'horizontal',
    color: 'blue',
    shape: 'pill',
    height: 45,
    label: 'checkout',
  },
}

// Vertical silver with custom radius
paypal: {
  style: {
    layout: 'vertical',
    color: 'silver',
    shape: 'rect',
    height: 50,
    borderRadius: 8,
  },
}
```

### Per-funding-source styling

Override styles for specific funding sources:

```javascript theme={"dark"}
paypal: {
  style: {
    layout: 'horizontal',
    color: 'blue',
    shape: 'pill',
    // Override for Pay Later button only
    paylater: {
      color: 'white',
    },
    // Card button only supports black or white
    card: {
      color: 'black',
    },
  },
}
```

> [!WARNING]
>
> **Card button color restriction:** The `card` funding source only supports `'black'` or `'white'` colors. Other colors will fall back to `'black'` with a console warning.

> [!TIP]
>
> For complete style options, see the [PayPal Button Style Guide](https://developer.paypal.com/sdk/js/reference/#style).

***

## Funding sources

Control which PayPal funding options are available. All sources are enabled by default.

### Available sources

| Source | Description |
| - | - |
| `'card'` | Guest card payments (no PayPal account) |
| `'credit'` | PayPal Credit (US, UK) |
| `'paylater'` | PayPal Pay Later |
| `'venmo'` | Venmo (US) |

> [accordion] Regional funding sources
>
> PayPal supports additional regional sources:
>
> | Source | Region |
> | - | - |
> | `'bancontact'` | Belgium |
> | `'blik'` | Poland |
> | `'eps'` | Austria |
> | `'giropay'` | Germany |
> | `'ideal'` | Netherlands |
> | `'mybank'` | Italy |
> | `'p24'` | Poland |
> | `'sepa'` | EU |
> | `'sofort'` | Germany, Austria |
> | `'mercadopago'` | Latin America |

### Disable funding

Hide specific payment options:

```javascript theme={"dark"}
paypal: {
  disableFunding: ['credit', 'paylater', 'card'],
}
```

> [!NOTE]
>
> The `'paypal'` funding source cannot be disabled — it is always available. Attempting to include `'paypal'` in `disableFunding` will be ignored with a console warning.

### Enable funding

Explicitly enable specific sources:

```javascript theme={"dark"}
paypal: {
  enableFunding: ['venmo'],
}
```

> [!NOTE]
>
> `disableFunding` takes precedence. If a source appears in both arrays, it will be disabled.

### Examples

```javascript theme={"dark"}
// PayPal account only (no cards, credit, or alternatives)
paypal: {
  disableFunding: ['card', 'credit', 'paylater', 'venmo'],
}

// PayPal + Venmo only
paypal: {
  disableFunding: ['card', 'credit', 'paylater'],
  enableFunding: ['venmo'],
}
```

***

## Vaulting

Enable vaulting to save PayPal accounts for future payments.

### Requirements checklist

| Requirement | Where | Details |
| - | - | - |
| `vault: true` | SDK options | Enables vaulting in the checkout |
| `vaultOnSuccess: true` | Client session (server) | Tells Primer to vault the payment method |
| `customerId` | Client session (server) | Identifies the customer in your system |

### SDK configuration

```javascript theme={"dark"}
checkout.options = {
  paypal: {
    vault: true,
  },
};
```

### How it works

1. Customer authenticates with PayPal
2. PayPal creates a Billing Agreement for recurring access
3. Primer stores the vaulted payment method
4. Future payments use the saved method without re-authentication

> [accordion] Legacy SDK vaulting
>
> If using legacy SDK (`sdkCore: false`), use `paymentFlow` instead:
>
> ```javascript theme={"dark"}
> checkout.options = {
>   sdkCore: false,
>   paypal: {
>     paymentFlow: 'PREFER_VAULT',
>   },
> };
> ```

***

## Testing

### Sandbox testing

Simulate different buyer locations in sandbox:

```javascript theme={"dark"}
paypal: {
  buyerCountry: 'US',
}
```

> [!NOTE]
>
> `buyerCountry` only works in PayPal's sandbox environment and is ignored in production.

### Debug mode

Enable PayPal debug logging:

```javascript theme={"dark"}
paypal: {
  debug: true,
}
```

### Integration date

Specify your integration date (affects SDK behavior):

```javascript theme={"dark"}
paypal: {
  integrationDate: '2024-01-15',
}
```

***

## Troubleshooting

> [accordion] PayPal button not appearing
>
> **Possible causes:**
>
> * PayPal not configured in Primer Dashboard
> * Browser blocks third-party scripts
> * Ad blocker interfering
>
> **Debug steps:**
>
> 1. Check browser console for errors
> 2. Enable `debug: true` in PayPal options
> 3. Verify PayPal is in your `enabledPaymentMethods` (if specified)

> [accordion] Vaulting not working
>
> **Checklist:**
>
> * [ ] `vault: true` in SDK options
> * [ ] `vaultOnSuccess: true` in client session
> * [ ] `customerId` provided in client session
> * [ ] PayPal Billing Agreements enabled in your PayPal account

> [accordion] Funding source not showing
>
> **Possible causes:**
>
> * Source not available in buyer's region
> * Source in `disableFunding` array
> * Buyer's PayPal account doesn't support it
>
> **Note:** Some sources (Venmo, regional options) are region-locked and won't appear for buyers outside supported areas.

***

## Complete example

```html theme={"dark"}
<primer-checkout client-token="your-client-token"></primer-checkout>

<script type="module">
  import { loadPrimer } from '@primer-io/primer-js';

  loadPrimer();

  const checkout = document.querySelector('primer-checkout');
  checkout.options = {
    paypal: {
      // Styling
      style: {
        layout: 'vertical',
        color: 'gold',
        shape: 'pill',
        height: 45,
        label: 'checkout',
      },

      // Funding control
      disableFunding: ['credit', 'card'],

      // Vaulting
      vault: true,
    },
  };
</script>
```

***

## See also

> [card] [SDK options reference](https://primer.io/docs/sdk/primer-checkout-web/sdk-options-reference.md)
>
> All configuration options

> [card] [PayPal JS SDK configuration](https://developer.paypal.com/sdk/js/configuration/)
>
> Official PayPal documentation

> [card] [PayPal button style guide](https://developer.paypal.com/sdk/js/reference/#style)
>
> Complete style reference


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