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

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

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

Next Steps

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