> ## 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.
</Warning>

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

***

## 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 title="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    |
</Accordion>

### 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.
</Note>

### 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.
</Note>

### 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 title="Legacy SDK vaulting">
  If using legacy SDK (`sdkCore: false`), use `paymentFlow` instead:

  ```javascript theme={"dark"}
  checkout.options = {
    sdkCore: false,
    paypal: {
      paymentFlow: 'PREFER_VAULT',
    },
  };
  ```
</Accordion>

***

## 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.
</Note>

### 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 title="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>

<Accordion title="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>

<Accordion title="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.
</Accordion>

***

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

<CardGroup cols={2}>
  <Card title="SDK options reference" icon="gear" href="/sdk/primer-checkout-web/sdk-options-reference">
    All configuration options
  </Card>

  <Card title="PayPal JS SDK configuration" icon="arrow-up-right-from-square" href="https://developer.paypal.com/sdk/js/configuration/">
    Official PayPal documentation
  </Card>

  <Card title="PayPal button style guide" icon="arrow-up-right-from-square" href="https://developer.paypal.com/sdk/js/reference/#style">
    Complete style reference
  </Card>
</CardGroup>