Known Constraints

Some provider combinations have technical limitations you must be aware of before integrating.

1. PayPal JS SDK Singleton

The PayPal JS SDK (sdk.js) can only be loaded once per page. If you use both PayPal:PayPalExpress and PayPal:PayLater together, they must share the same intent and currencyCode values in their options.

Mixing different values (e.g. intent: 'capture' on one and intent: 'authorize' on the other) causes a script-loading conflict and both buttons will fail to render.

Rule: When combining PayPal:PayPalExpress and PayPal:PayLater, set identical intent and currencyCode in both providers' options.

2. Adyen + Native PayPal Mutual Exclusion

Adyen:PayPalExpress and any native PayPal provider (PayPal:PayPalExpress, PayPal:PayLater) cannot be used on the same page.

Both load the PayPal JS SDK independently, but with different configuration parameters set by their respective Adyen and native PayPal integrations. This causes an unresolvable singleton conflict.

Rule: Choose either Adyen-managed PayPal or native PayPal — never both on the same page.

3. Braintree Shared Tokenization Key

All Braintree providers on the same page (Braintree:PayPalExpress, Braintree:PayLater) must use the same tokenizationKey.

The Braintree client SDK is initialised once per page with the first tokenization key it sees. Using different keys across Braintree providers results in an authentication error for any provider that uses a different key.

Rule: Set the same tokenizationKey value in every Braintree provider's options.

4. Apple Pay Requires HTTPS

Apple Pay will not render on pages served over plain HTTP. Requirements:

• The page must be served over HTTPS with a valid TLS certificate.
• Your domain must be registered and validated with Apple through the Apple Developer Program (via Merchant Identity Certificate or Domain Verification).

This applies to all Apple Pay providers: Apple:ApplePay, Adyen:ApplePay, Computop:ApplePay, and Mollie:ApplePay.

Rule: Only enable Apple Pay providers on HTTPS origins with a verified Apple Pay merchant domain.

5. Container Must Exist in DOM Before render()

The CSS selector specified in a ProviderButtonConfigcontainer field must resolve to an existing DOM element before .render() is called.

If the element is not found at render time, that provider will fail silently — no button is rendered and no error is thrown. The onError callback is not guaranteed to fire in this case.

Rule: Ensure all container elements are present in the DOM before calling buttons.render(). If you are using a framework, call render() inside onMounted / componentDidMount / after the DOM is ready.