Quick Start

Get your first CollanaPay Express Button on screen in four steps.

Step 1: Install

Option A — Script Tag (UMD)

Add the following <script> tag to your HTML. No build tool required.

<script src="https://cdn.example.com/collana-pay@VERSION/collana-pay.umd.js"
        integrity="sha384-..." crossorigin="anonymous"></script>

Note: Replace VERSION with the actual release tag and copy the SRI hash from dist/sri-hashes.json (generated by running npm run build:sri).

The SDK is now available as window.CollanaPay.ExpressButtons.

Option B — npm (ESM)

npm install collana-pay-js

import { ExpressButtons } from 'collana-pay-js';

Step 2: Add Container Elements

Add one empty <div> per payment button to your HTML. The id (or any CSS selector) is referenced in the provider configuration.

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

Step 3: Configure and Render

Create an ExpressButtonsConfig, call ExpressButtons(), and then call .render().

const buttons = ExpressButtons({
  providers: [
    {
      providerProtocolType: 'PayPal',
      paymentMethodType: 'PayPalExpress',
      container: '#paypal-button-container',
      options: {
        intent: 'capture',
        currencyCode: 'EUR',
      },
    },
    {
      providerProtocolType: 'Google',
      paymentMethodType: 'GooglePay',
      container: '#googlepay-button-container',
      options: {
        environment: 'TEST',
        merchantId: 'YOUR_GOOGLE_MERCHANT_ID',
        merchantName: 'My Shop',
        totalAmount: 19300,        // €193.00 in minor units
        currencyCode: 'EUR',
        countryCode: 'DE',
        gateway: 'example',
        gatewayMerchantId: 'exampleMerchantId',
      },
    },
  ],

  // Called when the user clicks a button — create the order on your backend.
  onClick: async (identity, paymentMethodData) => {
    // See the Backend API docs for the expected request/response shape:
    // https://sandbox.collanapay.com/redoc/index.html
    const response = await fetch('/api/orders', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ provider: identity, paymentMethodData }),
    });
    const order = await response.json();
    return { orderId: order.id };
  },

  onApprove: (data) => {
    console.log('Payment approved', data);
    window.location.href = '/order/success';
  },

  onCancel: (identity) => {
    console.log('Payment cancelled by user', identity);
  },

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

buttons.render();

The onClick callback receives a ProviderIdentity and optional paymentMethodData. It must return a Promise that resolves to an OrderResult containing at minimum { orderId: string }.

Step 4: Next Steps

• Callback Lifecycle — understand the full payment flow in detail
• Provider Reference — provider-specific options and copy-pastable examples
• Known Constraints — important limitations when combining providers
• API Reference — complete TypeScript type documentation