Peeap AI Integration Guide

This page is designed for AI coding assistants (v0, Cursor, Claude, ChatGPT, Copilot) to understand how to integrate Peeap payment widgets and APIs.

Quick Reference

Peeap Integration Summary

bash

"code-comment"># PEEAP INTEGRATION SUMMARY
"code-comment"># ========================

"code-comment"># Package: @peeap/widgets
"code-comment"># CDN: https://cdn.peeap.com/widgets.js
"code-comment"># Docs: https://docs.peeap.com
"code-comment"># Currency: Sierra Leone New Leones (NLe), ISO: SLE

"code-comment"># AVAILABLE WIDGETS:
"code-comment"># - POSTerminal: Point-of-sale system
"code-comment"># - InvoiceCreator: Invoice generation
"code-comment"># - EventTicketSales: Event ticket sales
"code-comment"># - TicketScanner: QR ticket validation
"code-comment"># - PaymentLinkCreator: Shareable payment links
"code-comment"># - PaymentLinkButton: One-click payment button

"code-comment"># PAYMENT CHANNELS (all use Peeap Pay):
"code-comment"># 1. QR Code Checkout - Mobile scan-to-pay
"code-comment"># 2. NFC/Tap to Pay - Contactless payments
"code-comment"># 3. Hosted Checkout - Web payment page
"code-comment"># 4. Mobile Money - Orange Money, Afrimoney
"code-comment"># 5. Card Payments - Visa, Mastercard

Installation

Install the Peeap widgets package using npm, yarn, or pnpm. Alternatively, use the CDN for quick integration.

Package Installation

bash

"code-comment"># Install the package
npm install @peeap/widgets

"code-comment"># Or use CDN in HTML
"code-comment"># <script src="https://cdn.peeap.com/widgets.js"></script>

API Response Format

All API responses follow a consistent format. Check the success field to determine if the request succeeded.

Response Examples

json

// Success response
{
  "success": true,
  "data": { ... },
  "timestamp": "2025-01-15T10: 30: 00.000Z"
}

// Paginated response
{
  "success": true,
  "data": [ ... ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "has_next_page": true
  }
}

// Error response
{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key"
  }
}

Widget Configurations

1. POS Terminal

Complete point-of-sale system with product catalog, cart, and payment processing. Supports QR code, NFC, and cash payments. Perfect for retail stores and restaurants.

POS Terminal Component

Import and configure the POSTerminal widget

tsx

class="code-keyword">import { POSTerminal } class="code-keyword">from class="code-keyword">class="code-string">'@peeap/widgets'

<class="code-component">POSTerminal
  apiKey=class="code-keyword">class="code-string">"pk_live_YOUR_API_KEY"      class="code-keyword">class=class="code-keyword">class="code-string">"code-comment">// Required: Public API key
  merchantId=class="code-keyword">class="code-string">"YOUR_MERCHANT_ID"       class="code-keyword">class=class="code-keyword">class="code-string">"code-comment">// Required: Merchant ID
  theme=class="code-keyword">class="code-string">"light"                       class="code-keyword">class=class="code-keyword">class="code-string">"code-comment">// class="code-keyword">class="code-string">"light" | class="code-keyword">class="code-string">"dark"
  currency=class="code-keyword">class="code-string">"SLE"                      class="code-keyword">class=class="code-keyword">class="code-string">"code-comment">// Currency class="code-function">code(class="code-keyword">default: SLE)
  taxRate={15}                        class="code-keyword">class=class="code-keyword">class="code-string">"code-comment">// Tax class="code-function">percentage(e.g., 15 for 15%)
  showCategories={class="code-keyword">true}               class="code-keyword">class=class="code-keyword">class="code-string">"code-comment">// Show category filter tabs
  showInventory={class="code-keyword">true}                class="code-keyword">class=class="code-keyword">class="code-string">"code-comment">// Show stock levels
  allowDiscounts={class="code-keyword">true}               class="code-keyword">class=class="code-keyword">class="code-string">"code-comment">// Enable discount input
  paymentMethods={[class="code-keyword">class="code-string">'qr', class="code-keyword">class="code-string">'nfc', class="code-keyword">class="code-string">'cash']} class="code-keyword">class=class="code-keyword">class="code-string">"code-comment">// Available payment methods
  onSaleComplete={(sale) => {
    class="code-keyword">class=class="code-keyword">class="code-string">"code-comment">// Handle completed sale
    console.class="code-function">log(class="code-keyword">class="code-string">'Sale ID:', sale.id)
    console.class="code-function">log(class="code-keyword">class="code-string">'Total:', sale.total)
    console.class="code-function">log(class="code-keyword">class="code-string">'Receipt:', sale.receipt_number)
  }}
  onError={(error) => console.class="code-function">error(error)}
/>

2. Invoice Creator

Create and send professional invoices with payment links and QR codes. Customers receive email with a link to pay online.

Invoice Creator Component

Create invoices with automatic payment QR codes

tsx

class="code-keyword">import { InvoiceCreator } class="code-keyword">from class="code-keyword">class="code-string">'@peeap/widgets'

<class="code-component">InvoiceCreator
  apiKey=class="code-keyword">class="code-string">"pk_live_YOUR_API_KEY"
  merchantId=class="code-keyword">class="code-string">"YOUR_MERCHANT_ID"
  currency=class="code-keyword">class="code-string">"SLE"
  taxRate={15}
  defaultDueDays={30}                 class="code-keyword">class=class="code-keyword">class="code-string">"code-comment">// Days until due
  companyInfo={{
    name: class="code-keyword">class="code-string">"Your Company Name",
    address: class="code-keyword">class="code-string">"123 Street, Freetown, Sierra Leone",
    email: class="code-keyword">class="code-string">"billing@company.sl",
    logo: class="code-keyword">class="code-string">"/logo.png"
  }}
  onInvoiceCreated={(invoice) => console.class="code-function">log(class="code-keyword">class="code-string">'Created:', invoice.id)}
  onInvoiceSent={(invoice) => console.class="code-function">log(class="code-keyword">class="code-string">'Sent to:', invoice.customer_email)}
/>

3. Event Ticket Sales

Sell event tickets with automatic QR code generation. Each ticket gets a unique scannable code for entry validation.

Event Ticket Sales Component

Sell tickets with QR codes for door scanning

tsx

class="code-keyword">import { EventTicketSales } class="code-keyword">from class="code-keyword">class="code-string">'@peeap/widgets'

<class="code-component">EventTicketSales
  apiKey=class="code-keyword">class="code-string">"pk_live_YOUR_API_KEY"
  eventId=class="code-keyword">class="code-string">"evt_YOUR_EVENT_ID"         class="code-keyword">class=class="code-keyword">class="code-string">"code-comment">// Required: Event ID
  showEventHeader={class="code-keyword">true}               class="code-keyword">class=class="code-keyword">class="code-string">"code-comment">// Show event name/date
  maxTicketsPerOrder={10}              class="code-keyword">class=class="code-keyword">class="code-string">"code-comment">// Max tickets per purchase
  onPurchaseComplete={(tickets) => {
    class="code-keyword">class=class="code-keyword">class="code-string">"code-comment">// Redirect to confirmation or show tickets
    console.class="code-function">log(class="code-keyword">class="code-string">'Tickets purchased:', tickets)
  }}
/>

4. Ticket Scanner

Scan and validate tickets at event entrance using camera or manual entry. Shows attendee info and prevents duplicate entries.

Ticket Scanner Component

Validate tickets at the door with camera or manual entry

tsx

class="code-keyword">import { TicketScanner } class="code-keyword">from class="code-keyword">class="code-string">'@peeap/widgets'

<class="code-component">TicketScanner
  apiKey=class="code-keyword">class="code-string">"pk_live_YOUR_API_KEY"
  eventId=class="code-keyword">class="code-string">"evt_YOUR_EVENT_ID"
  scanMode=class="code-keyword">class="code-string">"both"                      class="code-keyword">class=class="code-keyword">class="code-string">"code-comment">// class="code-keyword">class="code-string">"camera" | class="code-keyword">class="code-string">"manual" | class="code-keyword">class="code-string">"both"
  showStats={class="code-keyword">true}                     class="code-keyword">class=class="code-keyword">class="code-string">"code-comment">// Show scan statistics
  onScanSuccess={(ticket) => {
    class="code-function">playSuccessSound()
    console.class="code-function">log(class="code-keyword">class="code-string">'Valid ticket:', ticket.attendee_name)
  }}
  onScanError={(error) => {
    class="code-function">playErrorSound()
    console.class="code-function">log(class="code-keyword">class="code-string">'Invalid:', error.message)
  }}
/>

5. Payment Link Button

Simple button that opens a payment modal. Perfect for donations, one-time payments, or adding a "Pay Now" button to any page.

Payment Link Button Component

One-click payment button for quick integration

tsx

class="code-keyword">import { PaymentLinkButton } class="code-keyword">from class="code-keyword">class="code-string">'@peeap/widgets'

<class="code-component">PaymentLinkButton
  apiKey=class="code-keyword">class="code-string">"pk_live_YOUR_API_KEY"
  amount={100}                         class="code-keyword">class=class="code-keyword">class="code-string">"code-comment">// Amount in local currency
  currency=class="code-keyword">class="code-string">"SLE"
  description=class="code-keyword">class="code-string">"Premium Subscription"
  metadata={{ userId: user.id, plan: class="code-keyword">class="code-string">'premium' }}
  onSuccess={(payment) => {
    console.class="code-function">log(class="code-keyword">class="code-string">'Payment successful:', payment.id)
    class="code-keyword">class=class="code-keyword">class="code-string">"code-comment">// Upgrade user, unlock content, etc.
  }}
  onError={(error) => console.class="code-function">error(error)}
  className=class="code-keyword">class="code-string">"bg-blue-600 text-white px-6 py-3 rounded-lg"
>
  Pay NLe 100.00
</class="code-component">PaymentLinkButton>

Payment Channels

All Peeap widgets use Peeap Pay for processing. Choose the appropriate channel based on your use case:

QR Code Checkout

Customer scans QR with mobile banking app. Best for: POS, in-person payments.

paymentChannel: 'qr'

NFC/Tap to Pay

Contactless payment via card or phone. Best for: Fast checkout, retail.

paymentChannel: 'nfc'

Hosted Checkout

Redirect to Peeap payment page. Best for: E-commerce, online payments.

paymentChannel: 'hosted'

Mobile Money

Orange Money, Afrimoney integration. Best for: Mobile-first users.

paymentChannel: 'mobile_money'

Common Integration Patterns

Next.js App Router

For Next.js 13+ with App Router, add the 'use client' directive since widgets use browser APIs.

app/pos/page.tsx

tsx

class="code-keyword">class="code-string">'use client'

class="code-keyword">import { POSTerminal } class="code-keyword">from class="code-keyword">class="code-string">'@peeap/widgets'

class="code-keyword">export class="code-keyword">default class="code-keyword">function class="code-function">POSPage() {
  class="code-keyword">return (
    <class="code-component">POSTerminal
      apiKey={process.env.NEXT_PUBLIC_PEEAP_KEY!}
      merchantId={process.env.NEXT_PUBLIC_MERCHANT_ID!}
    />
  )
}

React + Vite

For Vite projects, use import.meta.env for environment variables.

src/components/Checkout.tsx

tsx

class="code-keyword">import { PaymentLinkButton } class="code-keyword">from class="code-keyword">class="code-string">'@peeap/widgets'

class="code-keyword">export class="code-keyword">function class="code-function">Checkout({ amount, onSuccess }) {
  class="code-keyword">return (
    <class="code-component">PaymentLinkButton
      apiKey={class="code-keyword">import.meta.env.VITE_PEEAP_KEY}
      amount={amount}
      onSuccess={onSuccess}
    >
      Pay Now
    </class="code-component">PaymentLinkButton>
  )
}

Vanilla JavaScript / HTML

Use the CDN script and render widgets to a container element.

index.html

javascript

<div id=class="code-keyword">class="code-string">"pos-terminal"></div>
<script src=class="code-keyword">class="code-string">"https:class="code-keyword">class="code-commentclass="code-keyword">class="code-string">">//cdn.peeap.com/widgets.js"></script>
<script>
  Peeap.class="code-function">render(class="code-keyword">class="code-string">'POSTerminal', {
    container: class="code-keyword">class="code-string">'#pos-terminal',
    apiKey: class="code-keyword">class="code-string">'pk_live_YOUR_API_KEY',
    merchantId: class="code-keyword">class="code-string">'YOUR_MERCHANT_ID',
    onSaleComplete: class="code-keyword">function(sale) {
      console.class="code-function">log(class="code-keyword">class="code-string">'Sale completed:', sale)
    }
  })
</script>

API Keys

Important: Use public keys (pk_*) for client-side widgets. Never expose secret keys (sk_*) in frontend code.

.env.local

Environment variables for your project

env

"code-comment"># Client-side (safe to expose)
"code-prop">NEXT_PUBLIC_PEEAP_KEY=pk_live_your_public_key
"code-prop">NEXT_PUBLIC_MERCHANT_ID=your_merchant_id

"code-comment"># Server-side only (keep secret!)
"code-prop">PEEAP_SECRET_KEY=sk_live_your_secret_key

Customization

Customize widget appearance using theme props, CSS variables, or translations.

Theme Customization

Match widgets to your brand colors

tsx

class="code-keyword">class=class="code-keyword">class="code-string">"code-comment">// Theme customization via props
<class="code-component">POSTerminal
  theme={{
    primaryColor: class="code-keyword">class="code-string">'#4F46E5',
    backgroundColor: class="code-keyword">class="code-string">'#FFFFFF',
    textColor: class="code-keyword">class="code-string">'#111827',
    borderRadius: class="code-keyword">class="code-string">'12px',
  }}
  className=class="code-keyword">class="code-string">"shadow-xl rounded-2xl"
/>

class="code-keyword">class=class="code-keyword">class="code-string">"code-comment">// Translations for localization
<class="code-component">POSTerminal
  translations={{
    cart: class="code-keyword">class="code-string">'Shopping Basket',
    checkout: class="code-keyword">class="code-string">'Complete Purchase',
    total: class="code-keyword">class="code-string">'Amount Due',
  }}
/>

CSS Variables

Global styling with CSS custom properties

css

.peeap-widget { --peeap-primary: #4F46E5; --peeap-radius: 12px; --peeap-font: 'Inter', sans-serif;
}

Instructions for AI Assistants

When user asks to integrate Peeap:

Determine which widget they need (POS, Invoice, Events, Payment Link)
Check their framework (Next.js, React, Vue, vanilla JS)
Install @peeap/widgets package
Add the appropriate component with required props (apiKey, merchantId/eventId)
Set up environment variables for API keys
Add event handlers for onSuccess/onError callbacks

Payment channel selection:

Physical store/POS → QR Code or NFC
Online/E-commerce → Hosted Checkout
Mobile app → Mobile Money or QR Code
Donations/Tips → Payment Link Button

Currency: Sierra Leone New Leones (NLe), ISO code: SLE