@patalink/html-payment-modal

v1.0.8

Published

2 days ago

Payment Modal as Native HTML Web Component - Just add <payment-modal> tag to any HTML page

0High
0Medium
0Low

patalink

payment modal web-component html-tag mtn airtel pesapal custom-element

Here's a professional, detailed documentation for your @patlink/html-payment-modal package:

# `<payment-modal>` - HTML Web Component

**Accept payments on any website with a single HTML tag. No React, no build tools, no complexity.**

[![npm version](https://badge.fury.io/js/@patlink%2Fhtml-payment-modal.svg)](https://badge.fury.io/js/@patlink%2Fhtml-payment-modal)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Bundle Size](https://img.badgesize.io/https://esm.sh/@patlink/html-payment-modal/dist/payment-modal.esm.js?label=size)](https://esm.sh/@patlink/html-payment-modal)

---

## 📖 Table of Contents

- [Quick Start](#rocket-quick-start)
- [Installation](#package-installation)
- [Attributes](#attributes-所有属性)
- [Usage Examples](#usage-examples)
- [Events](#events-事件监听)
- [JavaScript API](#javascript-api)
- [Styling](#styling-自定义样式)
- [Browser Support](#browser-support)
- [FAQ](#faq)

---

## 🚀 Quick Start

Add payment acceptance to your website in 3 simple steps:

### Step 1: Add the script

```html
<script type="module">
    import 'https://esm.sh/@patlink/html-payment-modal';
</script>

Step 2: Add the component

<payment-modal
    base-url="https://api.yourdomain.com"
    api-key="your_api_key_here"
    encryption-key="your_encryption_key_here"
></payment-modal>

Step 3: That's it! 🎉

The payment button will appear on your page. Your users can now pay via:

💳 Credit/Debit Cards (PesaPal)
📱 MTN Mobile Money
📱 Airtel Money

📦 Installation

Method 1: CDN (Recommended - No Installation)

Add this single line to your HTML:

<script type="module">
    import 'https://esm.sh/@patlink/html-payment-modal';
</script>

Method 2: npm (For build systems)

npm install @patlink/html-payment-modal

// In your JavaScript
import '@patlink/html-payment-modal';

Method 3: Local download

# Download the latest release
curl -O https://unpkg.com/@patlink/html-payment-modal/dist/payment-modal.esm.js

<script type="module" src="./payment-modal.esm.js"></script>

📋 Attributes

Required Attributes

| Attribute | Type | Description | Example | |-----------|------|-------------|---------| | base-url | string | Your API endpoint URL | https://patalink.me | | api-key | string | Your API key from dashboard | pk_live_abc123... | | encryption-key | string | Your encryption key from dashboard | xK8j3Hd9Fq2Wm5R... |

Optional Attributes

| Attribute | Type | Default | Description | Example | |-----------|------|---------|-------------|---------| | amounts | string | "[2000,5000,10000]" | Preset amount options (JSON array or comma-separated) | "[1000,5000,10000]" | | fixed-amount | number | undefined | Fixed amount (skips amount selection) | 25000 | | custom-text | string | "Support Me" | Button text | "Donate Now" | | custom-color | string | "#16a34a" | Button background color (hex or color name) | "#EF4444" or "red" | | custom-text-color | string | "#ffffff" | Button text color | "#000000" | | button-roundness | string | "rounded-xl" | Button border radius | "rounded-full", "rounded-lg", "rounded-none" | | font | string | "inherit" | Font family for modal | "'Poppins', sans-serif" | | theme-color | string | "#16a34a" | Modal theme/accent color | "#8B5CF6" | | theme-text-color | string | "#ffffff" | Modal text on theme color | "#000000" | | creator-name | string | "Creator" | Name displayed on success screen | "Hope for Children" | | logo-url | string | undefined | Logo image URL (displayed in modal) | "https://example.com/logo.png" | | company-name | string | undefined | Company name displayed in modal | "Hope for Children" | | modal-background-color | string | "#ffffff" | Modal background color | "#1A1A1A" or "black" | | hide-amount-selector | boolean | false | Hide amount selector (when using amounts) | (add as attribute) |

Amounts Format Examples

<!-- JSON array format (recommended) -->
<payment-modal amounts="[1000, 5000, 10000, 25000]"></payment-modal>

<!-- Comma-separated format -->
<payment-modal amounts="1000,5000,10000,25000"></payment-modal>

<!-- Single value -->
<payment-modal amounts="[5000]"></payment-modal>

Fixed Amount vs Amounts

<!-- Shows amount selection screen -->
<payment-modal amounts="[1000,5000,10000]"></payment-modal>

<!-- Skips amount selection, goes directly to payment -->
<payment-modal fixed-amount="25000" custom-text="Pay 25,000 RWF"></payment-modal>

💡 Usage Examples

Basic Donation Button

<payment-modal
    base-url="https://patalink.me"
    api-key="pk_live_abc123"
    encryption-key="xK8j3Hd9Fq2Wm5R..."
    amounts="[1000,5000,10000,25000,50000]"
    custom-text="Donate Now"
    custom-color="#EF4444"
    theme-color="#EF4444"
    creator-name="Hope for Children"
></payment-modal>

Event Ticket (Fixed Amount)

<payment-modal
    base-url="https://patalink.me"
    api-key="pk_live_xyz789"
    encryption-key="GKRy2jlusn3uAzhrU87qKH9SbQi+26ni8rg7PXnToyg="
    fixed-amount="25000"
    custom-text="Buy Ticket - 25,000 RWF"
    custom-color="#8B5CF6"
    theme-color="#8B5CF6"
    creator-name="Summer Music Festival"
    logo-url="https://example.com/festival-logo.png"
    company-name="VIBEHUB"
></payment-modal>

Premium Product (Multiple Price Tiers)

<payment-modal
    base-url="https://patalink.me"
    api-key="pk_live_def456"
    encryption-key="HjF8dK2lMx7nQw9rTy3uVb6cXz1aSw4eRg5tYh7uJk9lP="
    amounts="[50000,100000,250000,500000]"
    custom-text="Purchase"
    custom-color="#10B981"
    theme-color="#10B981"
    creator-name="Premium Store"
    modal-background-color="#1A1A1A"
    theme-text-color="#FFFFFF"
></payment-modal>

Dark Mode Integration

<payment-modal
    base-url="https://patalink.me"
    api-key="pk_live_ghi789"
    encryption-key="Lp9kMx2nQw4rly7uVb9cXz1aSw3eRg5tYh7uJk9lP="
    amounts="[5000,10000,25000]"
    custom-text="Support"
    custom-color="#6366F1"
    theme-color="#6366F1"
    modal-background-color="#0F0F0F"
    theme-text-color="#FFFFFF"
    custom-text-color="#FFFFFF"
    creator-name="Dark Mode Creator"
></payment-modal>

Minimal Configuration

<payment-modal
    base-url="https://patalink.me"
    api-key="pk_live_minimal"
    encryption-key="SimpleKey123"
></payment-modal>

🎯 Events (JavaScript Listeners)

Listen for payment events to trigger custom actions.

Payment Success Event

const modal = document.querySelector('payment-modal');

modal.addEventListener('payment-success', (event) => {
    const { data, error } = event.detail;
    
    if (error) {
        console.error('Payment failed:', error.message);
        alert('Payment failed. Please try again.');
    } else {
        console.log('Payment successful:', data);
        alert(`Thank you! Transaction ID: ${data.transactionId}`);
        
        // Custom actions:
        // - Redirect to thank you page
        // - Send analytics event
        // - Update UI
        // - Send email confirmation
    }
});

Payment Error Event

modal.addEventListener('payment-error', (event) => {
    const { error } = event.detail;
    console.error('Payment error:', error);
    
    // Show error message to user
    document.getElementById('error-message').textContent = error.message;
});

Payment Complete Event (Success Only)

modal.addEventListener('payment-complete', (event) => {
    const { data } = event.detail;
    
    // Redirect to confirmation page
    window.location.href = `/thank-you?txn=${data.transactionId}`;
});

Complete Event Handling Example

<script>
    const modal = document.getElementById('my-payment-modal');
    
    modal.addEventListener('payment-success', (e) => {
        const { data, error } = e.detail;
        
        if (error) {
            showToast('Payment failed: ' + error.message, 'error');
        } else {
            showToast('Payment successful! Thank you for your support.', 'success');
            // Send to Google Analytics
            gtag('event', 'purchase', {
                transaction_id: data.transactionId,
                value: data.amount,
                currency: 'RWF'
            });
        }
    });
    
    function showToast(message, type) {
        const toast = document.createElement('div');
        toast.className = `toast toast-${type}`;
        toast.textContent = message;
        document.body.appendChild(toast);
        setTimeout(() => toast.remove(), 5000);
    }
</script>

🔧 JavaScript API

Get Payment Result Programmatically

const modal = document.querySelector('payment-modal');
const result = modal.getPaymentResult();

if (result) {
    console.log('Last payment:', result.data);
    console.log('Error:', result.error);
    console.log('Time:', result.timestamp);
}

Update Attributes Dynamically

const modal = document.querySelector('payment-modal');

// Change donation amounts
modal.setAttribute('amounts', '[1000, 5000, 10000, 50000]');

// Change to fixed amount
modal.setAttribute('fixed-amount', '25000');
modal.setAttribute('custom-text', 'Pay 25,000 RWF');

// Remove fixed amount to show selection
modal.removeAttribute('fixed-amount');

// Change button color
modal.setAttribute('custom-color', '#EF4444');

// Update theme
modal.setAttribute('theme-color', '#8B5CF6');
modal.setAttribute('modal-background-color', '#0A0A0A');

Check if Component is Ready

// Wait for component to load
customElements.whenDefined('payment-modal').then(() => {
    console.log('Payment modal is ready!');
    const modal = document.querySelector('payment-modal');
    // Do something with modal
});

🎨 Styling (Custom CSS)

Center the Button

/* Center the payment button */
payment-modal {
    display: flex;
    justify-content: center;
    width: 100%;
}

payment-modal button {
    width: auto !important;
    min-width: 200px;
}

Custom Button Styles

/* Style the payment button directly */
payment-modal button {
    font-size: 18px !important;
    font-weight: 600 !important;
    padding: 14px 32px !important;
    box-shadow: 0 4px 15px rgba(0,0,0,0.2) !important;
    transition: transform 0.2s !important;
}

payment-modal button:hover {
    transform: scale(1.02) !important;
}

Responsive Button

payment-modal {
    display: block;
    width: 100%;
}

payment-modal button {
    width: 100% !important;
    max-width: 400px;
    margin: 0 auto;
    display: block !important;
}

🌐 Browser Support

| Browser | Version | Support | |---------|---------|---------| | Chrome | 67+ | ✅ Full | | Firefox | 63+ | ✅ Full | | Safari | 10.1+ | ✅ Full | | Edge | 79+ | ✅ Full | | Opera | 54+ | ✅ Full | | iOS Safari | 10.3+ | ✅ Full | | Android Chrome | 80+ | ✅ Full |

❓ FAQ

Do I need React to use this?

No. This is a pure HTML web component. It works on any website, even static HTML pages.

How do I get my API and encryption keys?

Sign up at dashboard.patalink.me
Go to Settings → API Keys
Click "Generate API Key" and "Generate Encryption Key"
Copy both keys into your HTML

What payment methods are supported?

MTN Mobile Money
Airtel Money
Credit/Debit Cards (via PesaPal)

Is my encryption key secure?

Yes. Your encryption key never leaves your server. All encryption happens in the browser before the request is sent.

Can I use this in WordPress/Wix/Squarespace?

Yes. Add the script tag and component to any page that accepts custom HTML.

What's the difference between `api-key` and `encryption-key`?

api-key: Identifies your account (authentication)
encryption-key: Encrypts payment data (security)

Both are required for secure transactions.

Can I test without real payments?

Yes! Use your test keys from the dashboard (they start with pk_test_).

What happens on payment success?

The modal shows a success screen and fires the payment-success event. You can listen to this event to redirect users or update your UI.

Can I customize the look and feel?

Absolutely! Use the styling attributes (custom-color, theme-color, modal-background-color, etc.) or override CSS.

Is this GDPR compliant?

Yes. We don't store personal data without consent. All payments are PCI compliant through our payment partners.

📞 Support

📄 License

MIT © PataLink

Start accepting payments today. Add one HTML tag. 🚀


This professional documentation includes:

1. **Clear quick start** - 3 steps to get working
2. **Complete attribute table** - All attributes with descriptions and examples
3. **Multiple usage examples** - Donation, tickets, products, dark mode
4. **Event handling** - JavaScript events with real examples
5. **JavaScript API** - Dynamic updates and programmatic access
6. **Styling guide** - CSS customization examples
7. **Browser support** - Compatibility matrix
8. **FAQ section** - Common questions answered
9. **Professional formatting** - Clean, scannable, well-organized
10. **Corrected attributes** - `base-url`, `encryption-key`, no `creator-id` required