Express Docs

Appearance

Quick Start ​

Get a payment button live on your page in minutes — no npm, no bundler, no build step required.

Before You Start ​

Make sure you have:

  1. A collana pay account with at least one provider configured (e.g. PayPal sandbox credentials).
  2. A backend endpoint that creates orders and returns a checkoutData payload. See the Backend API docs.
  3. HTTPS on your page. Required for Apple Pay and Google Pay. For local development, use ngrok or a similar tunnel.

Step 1: Load the SDK ​

Add the <script> tag at the end of your <body>, just before the closing </body> tag:

html
<script src="https://js-test.collanapay.com/sdk/@VERSION/collana-pay.umd.js"
        integrity="sha384-..." crossorigin="anonymous"></script>

Note: Replace VERSION with the actual release tag and copy the SRI hash from the Releases page. Automated setups (CI, LLM agents) can resolve the current bundle URL and SRI hash from the machine-readable manifest at /versions.json.

Placing the script at the end of <body> ensures the DOM is ready when the SDK loads and avoids blocking page rendering. If you prefer loading it in <head>, add the defer attribute — but then wrap your initialization code in a DOMContentLoaded event listener.

The SDK is now available as window.CollanaPay.

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.

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

Step 3: Configure and Render ​

Call CollanaPay.ExpressButtons() with your configuration, then call .render().

html
<script>
  CollanaPay.ExpressButtons({
    providers: [
      {
        providerProtocolType: 'PayPal',
        paymentMethodType: 'PayPalExpress',
        container: '#paypal-button-container',
        options: {
          merchantId: 'YOUR_PAYPAL_MERCHANT_ID',
          pspAutoCaptureEnabled: true,
          currencyCode: 'EUR',
        },
      },
    ],

    // Called when the user clicks the button.
    // Call your own backend, which in turn calls the collana pay
    // Create Express Transaction endpoint (POST /api/v2/express)
    // and returns the resulting checkoutData to the client.
    onClick: async (identity, options) => {
      const response = await fetch('/your-backend/create-transaction', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ provider: identity, options }),
      });
      const transaction = await response.json();
      return transaction.checkoutData;
    },

    // Called when the user cancels the payment (optional).
    onCancel: (identity) => {
      console.log('Payment cancelled', identity);
    },

    // Called on any payment error (optional).
    onError: (identity, error) => {
      console.error('Payment error', error);
    },

  }).render();
</script>

What happens when the user clicks the button:

  1. onClick fires — your backend creates a transaction and returns the checkoutData string.
  2. The SDK opens the provider's payment sheet (PayPal popup, Google Pay sheet, etc.).
  3. The user confirms — the SDK finalizes the transaction and redirects to your confirmation page (UriSuccess). After the redirect, the collana pay backend asynchronously sends a server-to-server callback (Prepare Interaction or Reservation Interaction, depending on the provider) to confirm the payment.
  4. If the user cancels, onCancel fires and the collana pay backend sends a server-to-server cancel callback to your backend. On any error, onError fires.

The onClick callback receives a ProviderIdentity and optional options. It must return a Promise that resolves to the checkoutData string from your backend. The SDK handles this payload internally — no manual parsing needed on the frontend.

Step 4: Test It ​

Use sandbox credentials and click the button in your browser.

PayPal sandbox: Log in with a PayPal sandbox personal account and approve the payment. You should be redirected to your confirmation page. Shortly after, the collana pay backend sends a server-to-server callback (Prepare Interaction or Reservation Interaction) to your backend to confirm the payment.

Google Pay / Apple Pay: Use the browser's built-in test card when prompted.

Something not working? Check the browser console for errors — most issues come from a missing or mis-selected container element, wrong credentials, or HTTP instead of HTTPS.

Telemetry ​

Telemetry is enabled by default. To disable it, set disableTelemetry: true:

js
CollanaPay.ExpressButtons({
  disableTelemetry: true,
  providers: [ /* … */ ],
  onClick: async (identity) => { /* … */ },
}).render();

Next Steps ​

CollanaPay SDK Documentation

Copyright © CollanaPay