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.

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