API Reference

This page provides complete API documentation for the Drop-in Checkout SDK, including all methods, types, and configuration options.

Installation

CDN

<script src="https://cdn.purse-sandbox.com/dropin-checkout/latest/purse.umd.js"></script>

npm

npm install @purse-eu/web-sdk

See @purse-eu/web-sdk on npm.

createDropinCheckout

Creates and initializes a Drop-in Checkout instance.

Signature

function createDropinCheckout(options: InitOptions): Promise<PurseDropin>

Parameters

InitOptions

Property	Type	Required	Description
session	string | SessionConfig	Yes	Client session data or configuration object
eventListener	(event: DropinEvent) => void	No	Callback for Drop-in lifecycle events
theme	DropinTheme	No	Theme customization options
locale	LocaleCode	No	Locale for UI translations
hooks	DropinHooks	No	Lifecycle hook callbacks

hooks

Optional lifecycle callbacks.

hooks.onRefreshSession

Called when the user clicks the Refresh session button on the expired-session overlay. Your callback must fetch or create a new session and return it; the Drop-in reinitializes automatically.

Type:

onRefreshSession?: () =>
  | string
  | PaymentSession
  | void
  | Promise<string | PaymentSession | void>

The refresh button is only displayed when this hook is provided. If the callback returns void or throws, the overlay stays in its error state and the user can attempt another refresh.

Example:

const dropin = await Purse.createDropinCheckout({
  session: clientSession.widget.data,
  hooks: {
    async onRefreshSession() {
      const newSession = await fetchNewCheckoutSession();
      return newSession.widget.data;
    }
  }
});

---

Session Types

API V2 Session (Recommended)

Pass the widget.data string from your client session:

const dropin = await Purse.createDropinCheckout({
  session: clientSession.widget.data // string
});

API V1 Session (Legacy)

Pass a configuration object:

type SessionConfig = {
  apiKey: string;
  entityId: string;
  environment: 'sandbox' | 'production' | 'test';
  paymentSession: PaymentSession;
};

Returns

Returns a Promise<PurseDropin> that resolves to a Drop-in instance.

Example

const dropin = await Purse.createDropinCheckout({
  session: clientSession.widget.data,
  theme: {
    accentColor: '#7c3aed'
  },
  eventListener: (event) => {
    console.log(event);
  },
  locale: 'fr-FR'
});

---

PurseDropin

The Drop-in instance returned by createDropinCheckout.

Properties

isPaymentFulfilled

A reactive readable store indicating whether the payment has been completed.

Type: Readable<boolean>

dropin.isPaymentFulfilled.subscribe((isFulfilled) => {
  if (isFulfilled) {
    console.log('Payment completed!');
  }
});

---

Methods

mount(target)

Mounts the Drop-in UI to a DOM element.

Signature:

mount(target: HTMLElement): Promise<void | Error>

Parameters:

Parameter	Type	Description
target	HTMLElement	The DOM element to mount the Drop-in into

Returns:

• void on success
• Error object if mounting fails

Example:

const container = document.getElementById('purse-dropin');
const result = await dropin.mount(container);

if (result instanceof Error) {
  console.error('Mount failed:', result.message);
}

---

unmount()

Removes the Drop-in UI from the DOM.

Signature:

unmount(): Promise<void>

Example:

await dropin.unmount();

---

submitPayment()

Submits the payment with the currently selected payment method.

Signature:

submitPayment(): Promise<void | Error>

Returns:

• void on success (SDK handles redirection automatically)
• Error object if payment submission fails

Example:

const result = await dropin.submitPayment();

if (result instanceof Error) {
  console.error('Payment failed:', result.message);
  // Handle error - show message to user
} else {
  // Payment successful - SDK handles redirection
  console.log('Payment submitted!');
}

User Selection Required

Ensure the user has selected a payment method before calling submitPayment(). The method will fail if no payment method is selected.

---

setSession(session)

Updates the payment session after initialization.

Signature:

setSession(session: PaymentSession | string): Promise<void>

Parameters:

Parameter	Type	Description
session	PaymentSession | string	New session data

Example:

await dropin.setSession(newClientSession.widget.data);

Use cases:

• Updating the cart amount
• Refreshing an expired session
• Changing payment configuration

---

setWalletSession(walletSession)

Sets a wallet session for digital wallet payments.

Signature:

setWalletSession(walletSession: WalletSession): Promise<void | Error>

Parameters:

Parameter	Type	Description
walletSession	WalletSession	Wallet session configuration

Returns:

• void on success
• Error object if setting the wallet session fails

Example:

const result = await dropin.setWalletSession({
  session_id: 'wallet-session-id',
  owner_reference: 'customer-123',
  merchant: 'MERCHANT_CODE'
});

if (result instanceof Error) {
  console.error('Failed to set wallet session:', result.message);
}

---

Types

DropinTheme

Theme configuration for customizing the Drop-in appearance.

type DropinTheme = {
  fontFamily?:
    | 'Roboto'
    | 'Montserrat'
    | 'Raleway'
    | 'Inter'
    | 'Noto Sans'
    | 'Open Sans'
    | 'Lato'
    | 'Nunito'
    | 'Work Sans';
  borderRadius?: string;
  accentColor?: string;
  text?: {
    primaryColor?: string;
    secondaryColor?: string;
    fontSize?: string;
    fontWeight?: FontWeight;
  };
  title?: {
    fontSize?: string;
    fontWeight?: FontWeight;
  };
};

type FontWeight =
  | 'normal'
  | 'bold'
  | 'bolder'
  | 'lighter'
  | '100' | '200' | '300' | '400' | '500' | '600' | '700' | '800' | '900';

See Theming for detailed documentation.

---

DropinEvent

Event object passed to the eventListener callback.

// Ready event
interface ReadyEvent {
  code: 'ready';
  payload: undefined;
}

// Error event
interface ErrorEvent {
  code: 'error';
  payload: {
    code?: string;
    message: string;
  };
}

type DropinEvent = ReadyEvent | ErrorEvent;

See Events for detailed documentation.

---

LocaleCode

Supported locale codes for UI translations.

type LocaleCode =
  | 'de-AT'
  | 'de-CH'
  | 'de-DE'
  | 'en-GB'
  | 'en-US'
  | 'es-ES'
  | 'fr-FR'
  | 'it-CH'
  | 'it-IT'
  | 'nl-BE'
  | 'nl-NL'
  | 'pt-BR'
  | 'pt-PT';

---

Error Codes

INTERNAL_ERROR

An unexpected error occurred.

Property	Value
Code	INTERNAL_ERROR
Message	An unexpected error occurred. Please contact support.

Resolution: Contact Purse support with error details.

---

Quick Reference

Method	Description
createDropinCheckout(options)	Initialize a Drop-in instance
dropin.mount(element)	Mount the Drop-in UI
dropin.unmount()	Remove the Drop-in UI
dropin.submitPayment()	Submit the payment
dropin.setSession(session)	Update the session
dropin.setWalletSession(session)	Set wallet session
dropin.isPaymentFulfilled	Payment status store
hooks.onRefreshSession	Hook to refresh an expired session

Next Steps

• Getting Started – Integration tutorial
• Theming – Customize appearance
• Events – Handle lifecycle events