Customize the PayPal Checkout Button

Important: PayPal supports these Checkout integrations:

Smart Payment Buttons, which use the PayPal JavaScript SDK. Valid from February 2019 for new integrations.

Checkout with checkout.js. Valid before February 2019. Customers who use checkout.js can access reference and support material in this Checkout guide. However, PayPal does not update checkout.js with new features and enhancements.

PayPal Checkout offers several style options to customize the appearance and behavior of your smart payment button. You can also use options to display multiple funding sources to the buyer, when appropriate.

These topics describe how to customize your checkout button:

Customization example
Locales
Button styles
Multiple button layout
Interactive code demo

Customization example

This example shows customizations for the PayPal button's locale and style:

// Customize button (optional)
locale: 'en_US',
style: {
 size: 'small',
 color: 'gold',
 shape: 'pill',
 label: 'checkout',
 tagline: 'true'
}

To customize the button, use these parameters:

Option	Value	Type	Description
`locale`	Supported locales	String	OPTIONAL The locale code of the country and language to display on the button. Default: `en_US`
`style`	Button styles	Object	OPTIONAL Style options for the button, including color, shape, size, and label.

Supported locales

To specify the button language, set locale to a supported locale.

For example:

locale: 'en_US' displays PayPal Checkout
locale: 'de_DE' displays PayPal Zur Kasse

Button styles

To define the color, shape, size, and label of the button, use the button style parameters. These guidelines recommend certain styles.

Color

Set the style.color option to one of these values:

Value	Description	Button
`gold`	Recommended People around the world know us for the color gold and research confirms it. Extensive testing determined just the right shade and shape that help increase conversion. Use it on your website to leverage PayPal’s recognition and preference.
`blue`	First alternative If gold does not work for your site, try the PayPal `blue` button. Research shows that people know it is our brand color, which provides a halo of trust and security to your experience.
`silver` `white`	Second alternatives If gold or blue does not work for your site design or aesthetic, try the `silver` or `white` buttons. Because these colors are a bit recessive and less capable of drawing people’s attention, we recommend these button colors as a second alternative.
`black`	Third alternative If your website demands a monochromatic button, try the `black` button. Because black is a common website color and less capable of drawing people's attention, we recommend this button as a third alternative.

Shape

Set the style.shape option to one of these values:

Value	Description	Button
`pill`	Recommended Whenever possible, use the pill-shaped button. Its unique and powerful shape signifies PayPal in people’s minds.
`rect`	Use the rectangular button as an alternative for media such as mobile where pill-shaped buttons might pose design challenges.

Size

Set the style.size option to one of these values:

Value	Dimensions	Description
`small`	150 pixels by 25 pixels	Use to match the size of other small buttons on the page.
`medium`	250 pixels by 35 pixels	Use to match the size of other medium buttons on the page.
`large`	350 pixels by 40 pixels	Use to match the size of other large buttons on the page.
`responsive`	Dynamic	Recommended Matches the width of the container element, with the height decided dynamically based on width. Minimum width is `100px`, maximum width is `500px`.

Set the style.height option to one of these values:

Value	Dimensions	Description
`small`	25 to 55 pixels	Use to match the height of other small buttons on the page.
`medium`	35 to 55 pixels	Use to match the height of other medium buttons on the page.
`large`	30 to 55 pixels	Use to match the height of other large buttons on the page.

About responsive buttons

If you set style.size to 'responsive', the button matches the width of the container element, and auto-calculates an appropriate height based on the width.

This example creates a button that is 200 pixels wide:

<div id="paypal-button" style="width: 200px"></div>

<script>
paypal.Button.render({
 style: {
 size: 'responsive'
 }
});
</script>

This example creates a button that is 50 percent of the width of the parent element:

<div id="paypal-button" style="width: 50%"></div>

<script>
paypal.Button.render({
 style: {
 size: 'responsive'
 }
}, '#paypal-button-container');
</script>

Note: The minimum width of the button for this example is 100 pixels.

This example code shows a responsive button with a media query. The button displays:

100 percent on mobile
250 pixels wide on a desktop

<style>
@media screen and (max-width: 400px) {
 #paypal-button-container {
 width: 100%;
 }
}

@media screen and (min-width: 400px) {
 #paypal-button-container {
 width: 250px;
 }
}
</style>

<div id="paypal-button-container"></div>

<script>
paypal.Button.render({
 style: {
 size: 'responsive'
 }
}, '#paypal-button-container');
</script>

Label

Set the style.label option to one of these values:

Value	Description	Button
`checkout`	Displays the PayPal Checkout button. Default: `checkout`
`credit`	Displays the PayPal Credit button and initializes the credit flow. Cannot be used with any custom `color` option. (UK merchants) Credit is a regulated activity in the UK. Before integrating a PayPal Credit button, you must be authorized to act as a credit broker and have a credit agreement with PayPal. For more information, contact business customer support through paypal.com or by calling 0800 358 7929.
`pay`	Displays the Pay With PayPal button and initializes the checkout flow.
`buynow`	Displays the Buy Now button and initializes the checkout flow. The default Buy Now button is unbranded. To include PayPal branding, set `branding: true`.
`paypal`	Displays the generic PayPal button and initializes the checkout flow. This button contains only the PayPal brand logo.
`installment`	Displays the PayPal Installment button and offers a specified number of payments during a payment installment period. Note: The `installment` feature is available only in these locales: `en_MX`, `es_MX`, `en_BR`, `pt_BR` Set `style.installmentperiod` to set the number of payments during the installment period: `en_BR`, `pt_BR`: 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12 `en_MX`, `es_MX`: 3, 6, 9, 12

Tagline

Set the style.tagline to false to disable the tagline text:

Value	Description	Button
`true`	Display tagline text Default.
`false`	Disable tagline text.

Multiple button layout

By default, PayPal shows a single button. However, if additional funding sources are available to the buyer through PayPal, such as Venmo, then multiple buttons are displayed in the space provided. The style.layout option determines if the buttons are stacked horizontally (side-by-side) or vertically (top-to-bottom).

// Customize button (optional)
style: {
 layout: 'horizontal',
 fundingicons: 'true',
},
funding: {
 allowed: [ paypal.FUNDING.CARD ],
 disallowed: [ paypal.FUNDING.CREDIT ]
}

Layout

Set the style.layout option to determine the button layout when multiple buttons are available:

Value	Description	Layout
`vertical`	Default. Buttons are stacked vertically with a maximum of four buttons. Recommended when: Presenting a dynamic list of payment options on checkout and shopping cart pages. Leveraging Checkout as a full stack payments platform.	Mobile Venmo is available on mobile in U.S. markets only. PayPal Commerce Platform for Marketplaces and Platforms does not support Venmo. Web
`horizontal`	Buttons are stacked horizontally with a maximum of two buttons. Recommended when: Placing buttons on a product page, next to the product. Space on the page is limited. Alternative payment options are already provided.	Mobile Venmo is available on mobile in U.S. markets only. PayPal Commerce Platform for Marketplaces and Platforms does not support Venmo. Web

Funding methods

When multiple funding sources are available to the buyer, PayPal automatically determines which additional buttons are appropriate to display. However, you can choose to opt in or out of displaying specific funding sources in either the horizontal or vertical layout.

Set the funding option to one of these values:

Value	Description
`allowed`	Displays the specified funding methods, if the buyer is eligible.
`disallowed`	Hides the specified funding methods.

Then, specify one or more of these funding sources.

The Default column shows the default settings for each payment method type:

Value	Description	Default
`paypal.FUNDING.CREDIT`	Enable buyers to pay with PayPal Credit. Note: `paypal.FUNDING.CREDIT` should be set to `disallowed` for merchants that fall into these categories: Non-USD currency Real Money Gaming Existing PayPal Credit button integration	The default for U.S. buyers.
`paypal.FUNDING.CARD`	Allow buyers to pay with their credit or debit card (Visa, Mastercard, American Express, Discover, and so on).	The default for all buyers.
`paypal.FUNDING.VENMO`	Allow buyers to pay with Venmo.	The default for U.S. buyers.
`paypal.FUNDING.ELV`	Allow German buyers to pay with their bank account using Elektronisches Lastschriftverfahren.	The default for DE (German) buyers.

This example opts in to PayPal Credit:

funding: {
 allowed: [ paypal.FUNDING.CREDIT ]
}

Displays the PayPal Checkout and PayPal Credit buttons:

This example opts out of displaying the PayPal Credit button:

funding: {
 disallowed: [ paypal.FUNDING.CREDIT ]
}

Note: When you add a funding source to funding.allowed, the funding source appears to eligible buyers. For example, if you set the following value, the credit button is shown only to buyers in countries where PayPal Credit is offered:
allowed: [ paypal.FUNDING.CREDIT ]

Funding icons

When using the horizontal layout, you can set style.fundingicons to display or hide funding instrument icons beneath the payment button.

Set the style.fundingicons option to one of these values:

Value	Description	Icons
`true`	Displays funding instrument icons. Not valid for the `credit` button.
`false`	Hides funding instrument icons.

Interactive code demo

To create and test your PayPal button, use the interactive code demo.

You can edit the code in the demo to try out different button styles and optional button features.

PayPal Commerce Platform for Business

PayPal Commerce Platform for Marketplaces and Platforms

PayPal Commerce Platform for Enterprise

Docs Catalog

Reference

Developer Tools

Regional Codes