@apex/payment-widget

Web3 payment widget component built with Wagmi, Reown AppKit, and Viem. A simple, ready-to-use React component for accepting crypto payments.

Installation

Production Installation

npm install @apex/payment-widget

Local Development (Testing Before Deployment)

To test the widget in your local project before deploying, you can use one of two methods:

Method 1: npm link (Recommended)

1. Create a link in the widget directory:

cd /path/to/apex-payment-widget
npm run build
npm link

2. Use the link in your project:

cd /path/to/your-project
npm link @rudiq/payment-widget

3. Usage:

import { RudiqPaymentWidget } from '@rudiq/payment-widget'

4. When you make changes, rebuild in the widget directory:

cd /path/to/apex-payment-widget
npm run build
# or for watch mode:
npm run dev

5. To remove the link:

cd /path/to/your-project
npm unlink @rudiq/payment-widget

Method 2: Local Path (Alternative)

Specify the path directly in your package.json:

{
  "dependencies": {
    "@rudiq/payment-widget": "file:../apex-payment-widget"
  }
}

Then:

npm install

Quick Start

React

import { RudiqPaymentWidget } from '@rudiq/payment-widget'
import { useState } from 'react'

function App() {
  const [isOpen, setIsOpen] = useState(false)

  return (
    <>
      <button onClick={() => setIsOpen(true)}>Open Payment Widget</button>
      <RudiqPaymentWidget
        host="https://api.example.com"
        paymentId="your-payment-id"
        token="your-bearer-token"
        isOpen={isOpen}
        onClose={() => setIsOpen(false)}
      />
    </>
  )
}

Vue

<template>
  <div>
    <button @click="isOpen = true">Open Payment Widget</button>
    <RudiqPaymentWidget
      host="https://api.example.com"
      :paymentId="'your-payment-id'"
      :token="'your-bearer-token'"
      :isOpen="isOpen"
      @close="isOpen = false"
    />
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import RudiqPaymentWidget from '@rudiq/payment-widget/vue'

const isOpen = ref(false)
</script>

Props

RudiqPaymentWidget

• host (string, required): Base URL for the payment widget (e.g., "https://api.example.com")
• paymentId (string, required): Payment ID for the payment
• token (string, required): Bearer token for API authentication
• isOpen (boolean, required): Controls the visibility of the widget modal
• onClose (function, required): Callback function called when the widget is closed
• clientId (string, optional): Client ID for the payment
• className (string, optional): Additional CSS classes
• width (string | number, optional): Modal width. Default: "90%"
• height (string | number, optional): Modal height. Default: "90%"
• title (string, optional): Modal title. Default: "Ödeme"
• zIndex (number, optional): Modal z-index. Default: 9999

Features

• 📦 Iframe-based payment widget (all payment logic handled in iframe)
• 🔒 Secure token-based authentication
• 📱 Responsive modal design
• 🎨 Customizable appearance (width, height, title, z-index)
• ⌨️ ESC key support for closing
• 🖱️ Click outside to close
• ⚡ Lightweight and easy to integrate
• 🔄 Loading states

Widget URL

The widget creates an iframe URL by appending /widget to the host URL:

• Host: https://api.example.com → Widget URL: https://api.example.com/widget?paymentId=...&token=...
• Host: https://api.example.com/ → Widget URL: https://api.example.com/widget?paymentId=...&token=...

The iframe URL includes the following query parameters:

• paymentId: Payment identifier
• token: Bearer token for authentication
• clientId: (optional) Client identifier

Requirements

• React 18+ or 19+ (for React component)
• Vue 3+ (for Vue component)
• Backend API endpoint that serves the payment widget at /widget path

License

MIT