API Reference

Complete API documentation for the Drop-in Checkout SDK.

Installation

CDN

<!-- UMD (global Purse object) -->
<script src="https://cdn.purse-sandbox.com/dropin-checkout/latest/purse.umd.js"></script>

<!-- ES Module -->
<script type="module">
  import * as Purse from "https://cdn.purse-sandbox.com/dropin-checkout/latest/purse.esm.js";
</script>

npm

npm install @upstreampay/web-sdk

import { loadDropInCheckout } from "@upstreampay/web-sdk";

const Purse = await loadDropInCheckout("sandbox"); // or "production"

---

createDropinCheckout()

Creates and initializes a Drop-in Checkout instance.

Signature

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

Parameters

Property	Type	Required	Description
session	string | SessionConfig	Yes	Client session data or configuration object
eventListener	(event: DropinEvent) => void	No	Callback for lifecycle events
theme	DropinTheme	No	Theme customization
locale	LocaleCode	No	UI language

Returns

Promise<PurseDropin> — Resolves to a Drop-in instance.

Example

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

---

PurseDropin

The Drop-in instance returned by createDropinCheckout().

Properties

isPaymentFulfilled

A reactive store indicating whether the user has selected a valid payment method and the payment is ready to submit.

Type: Readable<boolean>

Use this to enable or disable your pay button:

const payButton = document.getElementById("pay-button");

dropin.isPaymentFulfilled.subscribe((isFulfilled) => {
  payButton.disabled = !isFulfilled;
});

---

Methods

mount(target)

Mounts the Drop-in UI to a DOM element.

mount(target: HTMLElement): Promise<void>

Parameter	Type	Description
target	HTMLElement	Container element

try {
  const container = document.getElementById("purse-dropin");
  await dropin.mount(container);
} catch (error) {
  console.error("Mount failed:", error.message);
}

---

unmount()

Removes the Drop-in UI from the DOM.

unmount(): Promise<void>

await dropin.unmount();

---

submitPayment()

Submits the payment with the currently selected payment method.

submitPayment(): Promise<void>

On success, the SDK handles redirection automatically. On failure, an error is thrown.

try {
  await dropin.submitPayment();
  // Success - SDK handles redirection
} catch (error) {
  console.error("Payment failed:", error.message);
}

Selection Required

The user must select a payment method before calling submitPayment().

---

setSession(session)

Updates the payment session after initialization.

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

Parameter	Type	Description
session	PaymentSession | string	New session data

Errors are handled internally and reported through the eventListener.

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

Use cases:

• Updating the cart amount
• Refreshing an expired session

---

setWalletSession(walletSession)

Sets a wallet session for digital wallet payments (OnePay).

setWalletSession(walletSession: WalletSession): Promise<void>

Parameter	Type	Description
walletSession	WalletSession	Wallet session data

try {
  await dropin.setWalletSession({
    session_id: "wallet-session-id",
    owner_reference: "customer-123",
    merchant: "MERCHANT_CODE"
  });
} catch (error) {
  console.error("Wallet session failed:", error.message);
}

---

Types

InitOptions

type InitOptions = {
  session: string | SessionConfig;
  eventListener?: (event: DropinEvent) => void;
  theme?: DropinTheme;
  locale?: LocaleCode;
};

SessionConfig (API V1)

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

DropinTheme

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";

DropinEvent

type DropinEvent = ReadyEvent | ErrorEvent;

interface ReadyEvent {
  code: "ready";
  payload: undefined;
}

interface ErrorEvent {
  code: "error";
  payload: {
    message: string;
    code?: string;
  };
}

LocaleCode

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";

---

Quick Reference

Function / Method	Description
createDropinCheckout(options)	Initialize a Drop-in instance
dropin.mount(element)	Render the payment form
dropin.unmount()	Remove the payment form
dropin.submitPayment()	Submit the payment
dropin.setSession(session)	Update the session
dropin.setWalletSession(session)	Set wallet session
dropin.isPaymentFulfilled	Payment completion status

---

Next Steps

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