PayPal

The SDK provides two native PayPal providers that load the PayPal JS SDK directly — no PSP intermediary. Both providers use the same underlying PayPal script on the page.

PayPal JS SDK Singleton

The PayPal JS SDK (sdk.js) can only be loaded once per page. When using both PayPal:PayPalExpress and PayPal:PayLater together, both providers must have identical pspAutoCaptureEnabled, currencyCode, and merchantId/clientId values in their options.

Mixing different values causes a script-loading conflict and both buttons will fail to render.

PayPalExpress

Provider key: PayPal:PayPalExpress

Renders: the standard yellow PayPal button (funding source PAYPAL).

Options — PayPalOptions

Required

Field	Type	Description
merchantId	string	Preferred. Your PayPal merchant account ID, used in partner mode. The SDK resolves all credentials automatically — no PayPal developer app needed. Exactly one of merchantId or clientId must be set — see Authentication.
clientId	string	Your own PayPal client ID for direct authentication. Only use this if you are not onboarded via collana pay partner mode. Exactly one of merchantId or clientId must be set — see Authentication.
pspAutoCaptureEnabled	boolean	true → settle immediately (maps to intent=capture); false → authorize only (intent=authorize).
currencyCode	string	ISO 4217 currency code.

Style — PayPalStyle

Style options are purely cosmetic — they control how the PayPal button looks, not how it behaves. They are forwarded directly to paypal.Buttons({ style: ... }). Full reference: PayPal JS SDK — Buttons style object.

Field	Type	Description
color	'gold' | 'blue' | 'silver' | 'white' | 'black'	Button background color. Default: 'gold'.
shape	'rect' | 'pill' | 'sharp'	Button border shape. Default: 'rect'.
height	number	Button height in pixels (25–55).
borderRadius	number	Border radius in pixels (0–28). Only applies to shape: 'rect'.
label	'paypal' | 'checkout' | 'buynow' | 'pay' | 'installment' | 'subscribe' | 'donate'	Text displayed on the button. Default: 'paypal'.

Label notes:

• 'installment' is intended for Pay Later buttons.
• 'donate' requires nonprofit merchant configuration.
• 'subscribe' requires subscription product configuration.

PayLater

Provider key: PayPal:PayLater

Renders: the Pay Later installment button (funding source PAYLATER). The button is only displayed if the buyer is eligible for Pay Later in their region.

Options — PayPalPayLaterOptions

Required

Field	Type	Description
merchantId	string	Preferred. Must match the value used for PayPalExpress. Exactly one of merchantId or clientId must be set.
clientId	string	Must match the value used for PayPalExpress. Exactly one of merchantId or clientId must be set.
pspAutoCaptureEnabled	boolean	Must match the value used for PayPalExpress.
currencyCode	string	Must match the value used for PayPalExpress.

Important: If you use PayPal:PayLater alongside PayPal:PayPalExpress, clientId/merchantId, pspAutoCaptureEnabled, and currencyCode must be identical in both providers' options.

PayPal:PayLater shares the same PayPalStyle as PayPal:PayPalExpress — see the Style section above for all available fields.

Authentication

There are two ways to authenticate with PayPal. The mode is determined automatically by whether options.merchantId or options.clientId is set. Exactly one must be provided.

Onboarding mode — collana pay-managed credentials (recommended)

This is the preferred integration. collana pay acts as a PayPal partner and manages the SDK credentials on your behalf — you only need to provide your PayPal merchant account ID.

options: {
  merchantId: 'MERCHANT_PAYPAL_ACCOUNT_ID',
  currencyCode: 'EUR',
  pspAutoCaptureEnabled: true,
},

The SDK resolves the partner client ID and attribution ID automatically from its build-time configuration. Do not set options.clientId in this mode.

Don't know your merchantId? You can look it up in the 'Onboarding' section in COPAL once you have completed the onboarding setup for PayPal.

Direct mode — your own PayPal client ID

Use this only if you are not onboarded via collana pay partner mode and have your own PayPal developer app. Set options.clientId and omit options.merchantId:

options: {
  clientId: 'YOUR_PAYPAL_CLIENT_ID',
  currencyCode: 'EUR',
  pspAutoCaptureEnabled: true,
},

Note: In direct mode, collana pay partner attribution is not applied. Use partner mode whenever possible.

---

Example — PayPalExpress and PayLater Together

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

const buttons = CollanaPay.ExpressButtons({
  providers: [
    {
      providerProtocolType: 'PayPal',
      paymentMethodType: 'PayPalExpress',
      container: '#paypal-container',
      style: {
        color: 'gold',
        shape: 'rect',
        height: 45,
        label: 'paypal',
      },
      options: {
        // Onboarding mode: set merchantId, omit clientId
        merchantId: 'MERCHANT_PAYPAL_ACCOUNT_ID',
        currencyCode: 'EUR',
        pspAutoCaptureEnabled: true,
      },
    },
    {
      providerProtocolType: 'PayPal',
      paymentMethodType: 'PayLater',
      container: '#paylater-container',
      style: {
        color: 'gold',
        shape: 'rect',
        height: 45,
      },
      options: {
        // Must match PayPalExpress options exactly
        merchantId: 'MERCHANT_PAYPAL_ACCOUNT_ID',
        currencyCode: 'EUR',
        pspAutoCaptureEnabled: true,
      },
    },
  ],

  onClick: async (identity, options) => {
    const res = await fetch('/api/orders', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ provider: identity, options }),
    });
    const transaction = await res.json();
    // Return the checkoutData from your backend (collana pay API response).
    return transaction.checkoutData;
  },

  onCancel: (identity) => {
    console.log('PayPal payment cancelled', identity);
  },

  onError: (identity, error) => {
    console.error('PayPal error', error);
  },
});

buttons.render();