PayPal Options

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

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

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

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',
    },
  },
}

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.

For complete style options, see the PayPal Button Style Guide.

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)

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:

paypal: {
  disableFunding: ['credit', 'paylater', 'card'],
}

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:

paypal: {
  enableFunding: ['venmo'],
}

disableFunding takes precedence. If a source appears in both arrays, it will be disabled.

Examples

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

checkout.options = {
  paypal: {
    vault: true,
  },
};

How It Works

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

Legacy SDK vaulting

If using legacy SDK (sdkCore: false), use paymentFlow instead:

checkout.options = {
  sdkCore: false,
  paypal: {
    paymentFlow: 'PREFER_VAULT',
  },
};

Testing

Sandbox Testing

Simulate different buyer locations in sandbox:

paypal: {
  buyerCountry: 'US',
}

buyerCountry only works in PayPal’s sandbox environment and is ignored in production.

Debug Mode

Enable PayPal debug logging:

paypal: {
  debug: true,
}

Integration Date

Specify your integration date (affects SDK behavior):

paypal: {
  integrationDate: '2024-01-15',
}

Troubleshooting

PayPal button not appearing

Possible causes:

PayPal not configured in Primer Dashboard
Browser blocks third-party scripts
Ad blocker interfering

Debug steps:

Check browser console for errors
Enable debug: true in PayPal options
Verify PayPal is in your enabledPaymentMethods (if specified)

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

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

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

Components

PayPal Options

Quick Reference

Button Styling

Layout

Color

Examples

Per-Funding-Source Styling

Funding Sources

Available Sources

Disable Funding

Enable Funding

Examples

Vaulting

Requirements Checklist

SDK Configuration

How It Works

Testing

Sandbox Testing

Debug Mode

Integration Date

Troubleshooting

Complete Example

See Also

Components

​Quick Reference

​Button Styling

​Layout

​Color

​Examples

​Per-Funding-Source Styling

​Funding Sources

​Available Sources

​Disable Funding

​Enable Funding

​Examples

​Vaulting

​Requirements Checklist

​SDK Configuration

​How It Works

​Testing

​Sandbox Testing

​Debug Mode

​Integration Date

​Troubleshooting

​Complete Example

​See Also

Quick Reference

Button Styling

Layout

Color

Examples

Per-Funding-Source Styling

Funding Sources

Available Sources

Disable Funding

Enable Funding

Examples

Vaulting

Requirements Checklist

SDK Configuration

How It Works

Testing

Sandbox Testing

Debug Mode

Integration Date

Troubleshooting

Complete Example

See Also