Multi-Gateway Card Checkout: PapelPOS, Stripe, PayPal, WeePay, Cash App, and the POS Fee Collection System

1. POS Provider Registry Architecture#

PapelShip implements a modular POS provider system where each payment gateway is a self-contained module with its own credential schema, validation logic, and test connection method. The central registry currently includes 6 active providers:

Each provider module exports a standardized interface:

• fields[]: Credential schema with type definitions, placeholders, sensitivity flags, and validation hints.
• validate(creds): Synchronous credential format validation.
• testConnection(creds): Async connection test to verify API credentials are valid.
• sanitize(creds): Clean and normalize saved credential values.

Store owners toggle payment methods on/off and enter API credentials through the unified PapelShip payment settings dashboard.

2. POS Fee Collection Model#

Unlike crypto payments (which carry 0% platform fee), POS card payments are subject to a POS fee that covers PapelShip's payment orchestration overhead.

Fee Structure:

• Default POS Fee: 1.89% per transaction (configurable per store).
• Default Platform Fee: 2.69% per transaction (configurable per store).
• Crypto Flat Fee: $0.50 per crypto withdrawal (configurable per store).

How POS Fees Work:

When a card payment completes, the system records a fee entry in vs_pos_fees:

vs_pos_fees:
├── store_id: 15
├── invoice_id: 4892
├── payment_method: "STRIPE"
├── invoice_total_cents: 2500  ($25.00)
├── fee_percent: 1.89
├── fee_amount_cents: 47  ($0.47)
├── fee_amount_usd: 0.47
├── status: "pending"
├── due_date: "2026-08-04"  (21 days from creation)
└── created_at: "2026-07-14T12:00:00Z"

21-Day Payment Window

Store owners have 21 days to pay their accumulated POS fees. The fee summary dashboard shows:

• Pending: Unpaid fees within the 21-day window.
• Paid: Settled fees.
• Overdue: Fees past the due date.

Automatic Store Disabling

When a store has overdue POS fees (status = pending and due_date < NOW()), the system automatically:

1. Updates fee status from pending to overdue.

2. Disables all products for that store (UPDATE vs_products SET active = 0).

3. Products remain disabled until all overdue fees are settled.

This ensures platform sustainability while giving store owners a generous 21-day grace period.

3. Crypto Payment Methods (Zero POS Fee)#

The following payment methods are classified as crypto and are exempt from POS fees:

BITCOIN, ETHEREUM, LITECOIN, USDT, USDC, USDC_NATIVE, TRON, BINANCE_COIN, POLYGON, MONERO, BITCOIN_CASH, DOGECOIN, DASH.

Crypto payments go through the non-custodial wallet engine with 0% platform commission.

4. Supported Financial Payment Methods#

The full list of supported financial (fiat/card) payment methods:

Explore PapelShip Payment Options.