💸 stellar-payment-widgets

Zero-dependency, framework-agnostic Web Component payment widgets for Stellar — add a <stellar-pay> button to any website in under 5 minutes and accept XLM or any Stellar asset instantly.

---

Overview

stellar-payment-widgets makes accepting Stellar payments as simple as embedding a YouTube video. Built on the Web Components standard, the widgets work in React, Vue, Angular, Svelte, or plain HTML — no framework lock-in, no build step required for basic usage.

Widget catalogue:

Widget	Tag	Purpose
Pay Button	<stellar-pay>	One-click payment trigger with amount + asset
QR Code	<stellar-qr>	SEP-7 URI QR for mobile wallet scanning
TX Status	<stellar-tx-status>	Real-time confirmation tracker
Asset Picker	<stellar-asset-picker>	Dropdown of accepted assets
Address Display	<stellar-address>	Formatted, copyable Stellar address

---

Technical Architecture

Stack Overview

Layer	Technology
Component Model	Web Components (Custom Elements v1)
Component Library	Lit 3 (reactive + shadow DOM)
Language	TypeScript
Stellar SDK	@stellar/stellar-sdk
Payment URI	SEP-7 (stellar: URI scheme)
Bundler	Rollup (ESM + IIFE CDN bundle)
React Adapter	@lit-labs/react
Vue Adapter	Custom Vue 3 plugin
Testing	Web Test Runner + Playwright

Widget Anatomy

<stellar-pay
  destination="G..."
  amount="10"
  asset="XLM"
  memo="order-123"
  network="mainnet"
  theme="dark"
/>
  └── Internally:
        ├── Builds SEP-7 URI
        ├── Opens wallet deep-link or QR modal
        └── Streams Horizon SSE for confirmation
              └── Fires `stellar-payment-confirmed` CustomEvent

Event API

widget.addEventListener('stellar-payment-confirmed', (e: CustomEvent) => {
  console.log(e.detail.txHash);   // confirmed transaction hash
  console.log(e.detail.amount);   // actual amount received
});

widget.addEventListener('stellar-payment-failed', (e: CustomEvent) => {
  console.log(e.detail.error);
});

---

🌊 Drips Wave Program

This repository is a participant in the Drips Wave Program — earn real crypto rewards by solving scoped issues in this open-source project.

How to Contribute & Earn Rewards

Step 1 — Connect to Drips Visit drips.network and connect your Ethereum wallet. Bounties are streamed to this address upon PR merge.

Step 2 — Find This Project Search stellar-payment-widgets on Drips or use the GitHub About link.

Step 3 — Browse Funded Issues Issues are tagged by complexity:

Label	Complexity	Typical Reward Range
drips:trivial	Trivial	$10 – $50
drips:medium	Medium	$51 – $200
drips:high	High	$201 – $500+

Examples in this repo:

• Trivial: Add a theme="light" CSS variable set to <stellar-pay>
• Medium: Build the <stellar-asset-picker> Web Component
• High: Implement the full React adapter package with TypeScript props

Step 4 — Claim Comment /claim on the issue. One claim per contributor at a time.

Step 5 — PR Reference the issue (Closes #XX). New widgets need a Playwright browser test and a matching example in /examples/vanilla-html.

Step 6 — Get Paid Drips streams your reward automatically on merge. No invoices needed.

---

Quick Start (CDN)

<!-- Drop this anywhere in your HTML -->
<script type="module"
  src="https://cdn.jsdelivr.net/npm/stellar-payment-widgets/dist/index.js">
</script>

<stellar-pay
  destination="GCEZWKCA5VLDNRLN3RPRJMRZOX3Z6G5CHCGQKIKI25INCOPABLE"
  amount="5"
  asset="XLM"
  network="mainnet"
  theme="dark">
</stellar-pay>

Quick Start (NPM)

npm install stellar-payment-widgets

// React (auto-wrapped)
import { StellarPay } from 'stellar-payment-widgets/react';

<StellarPay
  destination="G..."
  amount={5}
  asset="XLM"
  onPaymentConfirmed={(e) => console.log(e.txHash)}
/>

---

Project Structure

stellar-payment-widgets/
├── src/
│   ├── components/         # Individual Lit Web Components
│   ├── core/               # SEP-7 builder, Horizon SSE monitor
│   ├── utils/              # Address format, asset helpers
│   └── styles/             # CSS custom property theme tokens
├── tests/
│   ├── unit/               # Logic unit tests
│   └── browser/            # Playwright Web Component tests
├── examples/
│   ├── vanilla-html/       # Plain HTML CDN usage example
│   ├── react-app/          # React adapter usage example
│   └── vue-app/            # Vue 3 plugin usage example
├── dist/                   # Rollup build output (gitignored)
├── scripts/                # Build & publish scripts
├── .github/
│   └── workflows/          # CI: typecheck, build, Playwright
├── package.json
└── README.md

---

Contributing

See CONTRIBUTING.md. Every new widget must ship with a vanilla HTML example, a Playwright browser test, and CSS custom property theming support before it will be merged.

---

License

MIT © stellar-payment-widgets contributors