CWPay Documentation

1. Overview

CWPay is a self-hosted payment link and collection system. Install it on your own server, connect your payment gateway accounts, and start generating payment links to share with customers via WhatsApp, email, or SMS. The customer clicks the link, selects a payment method, pays, and receives an automatic receipt email. The transaction is logged in your dashboard in real time.

CWPay is not an invoicing system and not accounting software. It is the collection layer — the bridge between "I need to collect money from this person" and "money is confirmed received." Pair it with CWInvoice for professional invoicing or CWFMS for full business finance management.

2. System Requirements

• PHP: 7.4 or higher (8.x supported). Extensions required: json, curl, openssl, session
• Web server: Apache or LiteSpeed with mod_rewrite enabled
• SSL certificate: Mandatory — all payment gateways reject HTTP redirect URLs. Free via Let's Encrypt in cPanel.
• Hosting: Any standard cPanel shared hosting account. No root access required.
• Disk space: ~1 MB for the application. Transaction data grows with use.
• Gateway accounts: A separate merchant account is required for each gateway you enable (WiPay, PayPal, Stripe etc.). These are independent of your CWPay license.

3. Installation

1. 1Download — cwpay.zip is emailed immediately after purchase. Also available under My Purchases.
2. 2Upload — via cPanel File Manager or FTP. Place the ZIP in your chosen directory, e.g. public_html/pay/ or public_html/payments/.
3. 3Extract — in File Manager right-click the ZIP → Extract. Once extracted, delete the ZIP file.
4. 4Permissions — the data/ directory must be writable. In File Manager select it → Change Permissions → set to 755.
5. 5Open your URL — visit https://yourdomain.com/pay/ (or wherever you installed it). CWPay detects no installation and redirects to the setup wizard automatically.
6. 6Complete setup — enter your business name, default currency, country, admin name, email address, password (minimum 8 characters) and your CWPAY-XXXX-XXXX-XXXX-XXXX license key.
7. 7Configure a gateway — go to Settings → Payment Gateways and set up at least one gateway before creating your first payment link.

4. First-Time Setup

The setup wizard runs on first visit and collects the information needed to initialise CWPay. Once complete, you are logged in as Admin and taken to the dashboard.

After the wizard — immediate next steps

• Settings → Company — add your phone number, address and website. These appear in receipt emails.
• Settings → Payment Page Branding — upload your logo and set your brand colour. Customers will see this on every payment page.
• Settings → Payment Gateways — configure at least one gateway. See Sections 10–16 for gateway-specific instructions.
• Settings → Email / SMTP — configure outgoing email so receipt emails reach your customers. See Section 19.

5. Payment Links

Creating a Payment Link

Go to Payment Links → New Link. Fill in the following fields:

• Title — shown prominently on the customer's payment page. Be descriptive: "Invoice INV-2026-0012 Payment", "Event Registration Deposit", "Consultation Fee".
• Description — optional secondary text shown below the title on the payment page.
• Invoice / Reference — if you enter a CWInvoice invoice number (e.g. INV-2026-0012), CWPay will automatically mark that invoice as paid when the customer completes payment. Leave blank for standalone collections with no linked invoice.
• Fixed Amount — when ticked, the customer sees the amount and cannot change it. When unticked, the customer enters any amount — useful for open donations, tips or "pay what you owe" scenarios.
• Amount — the collection amount. Leave at 0 if allowing open-amount.
• Currency — JMD, USD, TTD, BBD, XCD, GBP, EUR, CAD, NGN, GHS etc.
• Gateway — Auto (CWPay selects the best available gateway for the currency) or a specific gateway. Auto is recommended unless you need to force a particular payment method.
• Expiry Date — optional. After this date and time the link shows an "unavailable" page. Leave blank for no expiry.
• Max Uses — 0 for unlimited payments. Set to 1 for a single-use link that deactivates immediately after the first successful payment.

Link Statuses

• Active — currently accepting payments.
• Paused — temporarily disabled. Use the Pause/Activate toggle on the link detail page. The URL still works but shows an unavailable message until reactivated.
• Expired — the expiry date has passed. Auto-set by CWPay. Cannot be reversed — create a new link if needed.
• Cancelled — manually cancelled, or a single-use link that has received one payment and auto-cancelled.

Editing a Link

Payment links cannot be edited after creation to maintain transaction integrity. If you need to change the amount or description, pause the existing link and create a new one.

6. Sharing & QR Codes

Every payment link has a unique secure URL: https://yourdomain.com/pay/{token}. The token is a 32-character cryptographically random string — it cannot be guessed.

Share buttons

From the link detail page, use the one-click share buttons:

• WhatsApp — opens WhatsApp with the payment URL pre-filled in the message. Works on mobile and WhatsApp Web.
• Email — opens your email client with subject "Payment Request" and the URL in the body.
• Copy — copies the URL to clipboard. Paste into any message, invoice PDF, or social post.

QR Code

The link detail page displays a QR code for the payment URL. Use cases:

• Print it on paper invoices — client scans and pays
• Display on a tablet or screen at point of sale
• Add to WhatsApp status, Instagram story or business card
• Include in a PDF sent by email for easy mobile payment

7. Transactions & Refunds

Transaction records

Every payment attempt creates a transaction record with the following data: payer name, payer email, amount, currency, gateway used, gateway reference ID, link number, timestamp, and status (Pending / Paid / Failed / Refunded).

• Pending — customer started checkout but payment not yet confirmed via webhook.
• Paid — gateway webhook confirmed payment. Receipt email sent to payer.
• Failed — gateway reported a failed or declined payment.
• Refunded — refund processed via CWPay or logged for manual portal action.

Refunds

Admin users can issue a refund from the transaction detail page. Refund behaviour depends on the gateway:

• PayPal, Stripe, Volet — refund processed via API immediately. Transaction status updates to Refunded.
• Flutterwave, Square — refund API call made. Processing time depends on the gateway.
• WiPay — CWPay logs the refund request in the Audit Log and directs you to process it manually in the WiPay merchant portal. WiPay does not currently expose a public refund API.

8. Payment Page Branding

The payment page is what your customer sees when they click the link. It shows your business identity — not a generic CWPay page. Configure under Settings → Payment Page Branding.

Brand fields

• Brand Name — your business trading name. Displayed in the payment page header. Defaults to the company name entered during setup.
• Tagline — short subtitle under your name, e.g. "Secure Payment Portal" or "Kingston Digital Solutions".
• Logo — upload PNG, JPG, SVG or WebP. Displayed as a 48×48 rounded square in the header. Recommended size: 200×200px or square at any size.
• Brand Colour — hex colour (e.g. #0066ff) applied to the Pay button, amount text, and accent elements. Use your primary brand colour.
• Powered by CWPay — controls the small "Powered by CWPay" attribution in the payment page footer. Toggle off to remove it.

9. Gateway Overview

CWPay ships with 6 live gateway connectors and 2 stubs for upcoming integrations. Configure each gateway under Settings → Payment Gateways. Each gateway card expands when clicked to reveal its credential fields. Enable the gateway and save — CWPay validates the credentials on save.

Auto-select logic

When a link's gateway is set to Auto, CWPay selects from your enabled gateways using this priority order:

• JMD, TTD, BBD, XCD, GYD, BZD → WiPay (if enabled)
• USD, GBP, EUR, CAD, AUD, NZD, SGD → Stripe (if enabled)
• Everything else → PayPal (if enabled)
• If none of the above are enabled → first enabled gateway in the list

10. WiPay Setup

WiPay is the primary gateway for Caribbean businesses. Apply for a merchant account at wipayfinancial.com. WiPay serves Jamaica, Trinidad & Tobago, Barbados, Grenada, St. Lucia and the broader Eastern Caribbean.

Credentials needed

11. PayPal Setup

PayPal is available in most Caribbean countries and handles USD, GBP, EUR, CAD and 15+ other currencies. Ideal for collecting payment from international clients.

Step 1 — Create a developer app

1. 1Log in at developer.paypal.com with your PayPal Business account.
2. 2Go to My Apps & Credentials → Create App. Name it "CWPay".
3. 3Copy the Client ID and Client Secret.
4. 4Set Mode to Sandbox for testing, Live when ready to accept real payments.

Step 2 — Register webhook

In PayPal Developer → your app → Webhooks → Add Webhook. Enter your webhook URL:

Subscribe to the event: PAYMENT.CAPTURE.COMPLETED

12. Stripe Setup

Stripe supports 135+ currencies and enables Apple Pay and Google Pay automatically on compatible devices. Available in Trinidad & Tobago, Bahamas and other territories. For other Caribbean countries, Stripe Atlas (US incorporation) provides access.

Credentials needed

Adding the webhook endpoint

1. 1Stripe Dashboard → Developers → Webhooks → Add Endpoint
2. 2Endpoint URL: https://yourdomain.com/webhook/stripe
3. 3Select event: checkout.session.completed
4. 4Click Reveal Signing Secret and copy the whsec_... value into Settings → Stripe → Webhook Secret

13. Volet Setup

Volet supports international card payments and cryptocurrency (USDT, BTC, ETH). Good option for businesses with international clients or those needing crypto payment acceptance.

Credentials needed

Webhook URL to register: https://yourdomain.com/webhook/volet

14. Flutterwave Setup

Flutterwave is the leading pan-African payment gateway. Supports cards, bank transfers, mobile money (M-Pesa, Airtel etc.) and USSD across Nigeria, Ghana, Kenya, South Africa, Uganda and more. Useful for Caribbean businesses with African customers or partners.

Credentials needed

Webhook setup

1. 1Flutterwave Dashboard → Settings → Webhooks
2. 2URL: https://yourdomain.com/webhook/flutterwave
3. 3Set a Secret Hash — any string you choose. Enter the same value in Settings → Flutterwave → Webhook Hash in CWPay.

15. Square Setup

Square is popular in the United States, Canada, United Kingdom and Australia. Supports card payments and Square's own Checkout Links system.

Credentials needed

Webhook URL: https://yourdomain.com/webhook/square
Subscribe to event: payment.completed

16. Wise Setup

Wise (formerly TransferWise) is ideal for international bank transfers with low fees. It supports 50+ currencies and 170+ countries. Best for collecting from international clients who prefer bank-to-bank transfers over card payments.

Credentials needed

17. Manual Bank Transfer Setup

The Manual Bank Transfer gateway displays your bank account details on the payment page. The customer copies your account number and makes the transfer from their own bank. No API, no merchant account required — works with any bank in any country.

Credentials / Bank Details

Payment flow

When a customer clicks the payment link and Manual Bank Transfer is selected as the gateway, they are shown a branded page with your bank details. Each detail has a click-to-copy function. The customer completes the transfer in their own bank app or branch.

Confirming payment

Because there is no electronic confirmation from a bank, CWPay cannot auto-confirm manual bank transfers. After verifying the transfer in your bank account:

1. 1Go to Transactions in your CWPay dashboard
2. 2Find the pending transaction for the payment link
3. 3Use the Mark as Paid action to confirm receipt
4. 4CWPay fires the integration webhook — CWInvoice or CWFMS marks the invoice paid automatically

16. CWInvoice Integration

When a CWPay payment is received, CWPay can automatically notify your CWInvoice installation to mark the linked invoice as paid — with no manual action needed on your part.

How it works

1. 1Customer clicks payment link → pays → gateway confirms via webhook → CWPay records the transaction.
2. 2CWPay sends a signed POST webhook to your CWInvoice installation with the payment details.
3. 3CWInvoice verifies the signature using the shared secret and marks the matching invoice as paid.

Setup — CWPay side

In Settings → Integrations → CWInvoice:

• Enable the CWInvoice integration toggle
• Webhook URL — enter the URL of your CWInvoice installation followed by /webhook/cwpay:
  https://your-cwinvoice-install.com/webhook/cwpay
• Shared Secret — a secret string used to sign and verify webhook payloads. You choose this value. Enter the same string in both CWPay and CWInvoice settings.

Setup — CWInvoice side

In your CWInvoice installation, go to Settings → Integrations and enter the same Shared Secret. CWInvoice uses it to verify that the webhook is genuinely from your CWPay installation.

Linking a payment link to an invoice

When creating a payment link, enter the CWInvoice invoice number in the Invoice / Reference field (e.g. INV-2026-0012). When payment is received, CWPay sends the invoice number in the webhook and CWInvoice finds and marks it paid automatically.

17. CWFMS Integration

CWPay can notify CWFMS on payment, triggering a journal entry in the Accounts Receivable module. This closes the AR loop — invoice raised in CWFMS, payment link sent via CWPay, payment confirmed automatically back into CWFMS with no manual reconciliation.

Setup

In Settings → Integrations → CWFMS:

• Enable the CWFMS integration
• Webhook URL — your CWFMS installation's CWPay webhook endpoint:
  https://your-cwfms-install.com/webhook/cwpay
• Shared Secret — same pattern as CWInvoice. Set a secret string in both CWPay and CWFMS settings.
• AR Journal Account ID — the account ID from your CWFMS Chart of Accounts that represents Accounts Receivable. CWPay passes this in the webhook so CWFMS can post the Debit (Cash/Bank) and Credit (AR) entries to the correct accounts.

18. Users & Staff Access

CWPay supports multiple user accounts. The primary admin account is set during installation. Additional staff accounts can be created under Admin → Users → New User.

Roles

• Admin — full access to all features including gateway credentials, integrations, refunds, webhook log, audit log and user management.
• Staff (User) — can create payment links and view transactions. Cannot access Settings, Webhook Log, Audit Log or refund transactions.

19. Webhook Log

Every inbound webhook received from a payment gateway is logged under Webhook Log (Admin only). Each entry records the gateway name, received timestamp, source IP address, and the full raw payload.

This is the first place to check if a payment is not recording — if the webhook log shows the event arriving but no transaction was created, the issue is in the payload parsing. If the webhook log is empty, the gateway is not reaching your server (check the URL registered in the gateway dashboard and verify HTTPS is working).

20. Email / SMTP

Configure outgoing email under Settings → Email / SMTP. CWPay uses SMTP to send receipt emails to payers after each successful payment. No email is sent for failed or pending transactions. If SMTP is not configured, payments still record correctly — email is the only thing that stops working.

Settings

21. License

CWPay requires a CWPAY-XXXX-XXXX-XXXX-XXXX license key, validated against cwfms.com and cached on your server for 48 hours. The license gate applies to the admin dashboard only — the public payment pages (/pay/...) and gateway webhook endpoints (/webhook/...) are always accessible regardless of license status. Customer payments are never blocked.

Your license key is shown once in your purchase confirmation email and under My Purchases. To update or replace your key, go to Settings → License.

24. Troubleshooting

Payment Issues

• Gateway redirect fails / blank page after clicking Pay — check gateway credentials in Settings. Verify the gateway account is fully approved and active in the gateway's portal (some require a manual review period after signup).
• Payment not recording after customer pays — open Webhook Log. If the webhook is there but no transaction was created, the payload format may have changed — contact support. If no webhook is logged, the gateway cannot reach your URL — check your webhook URL registration in the gateway dashboard and confirm HTTPS is working.
• WiPay not redirecting — confirm the Account Number and API Key match exactly as shown in your WiPay merchant portal. Check that Mode (Sandbox/Live) matches your account status.
• Stripe webhook signature fails — the Signing Secret must be copied from the specific webhook endpoint in Stripe Developers → Webhooks, not from the API Keys page. They are different values.
• PayPal webhook not firing — verify that PAYMENT.CAPTURE.COMPLETED is selected as a subscribed event in your PayPal app's webhook settings. Both Sandbox and Live need separate webhook registrations.

Technical Issues

• CSS not loading / plain HTML display — add RewriteEngine Off to public/.htaccess. LiteSpeed servers sometimes need this.
• 500 error on install or login — check PHP version is 7.4+; verify data/ is writable (chmod 755); check cPanel → Errors for the PHP error log.
• Install wizard reappears after setup — data/settings.json is missing or empty. Ensure the data/ directory was not excluded during upload and is writable.
• License validation fails — cwfms.com must be reachable via curl from your server. Ask your host to allow outbound HTTPS connections if blocked.
• Receipt emails not sending — confirm SMTP credentials are correct. Check cPanel → Errors. Verify your host allows outbound SMTP on port 587.

Still stuck? Email admin@cwfms.com

25. Production Checklist

• ☐SSL/HTTPS active — payment gateways require it. Test at ssllabs.com/ssltest
• ☐Strong admin password — 12+ characters, mix of letters, numbers and symbols
• ☐data/ directory protected — visiting yourdomain.com/pay/data/ should return 403 Forbidden
• ☐At least one gateway configured — credentials saved and enabled in Settings
• ☐Webhook URL registered — in each enabled gateway's dashboard, pointing to https://yourdomain.com/webhook/{gateway}
• ☐End-to-end sandbox test done — created a test link, completed a sandbox payment, verified transaction recorded in dashboard
• ☐Gateway switched to Live mode — Live credentials entered, sandbox credentials replaced
• ☐Brand logo and colour configured — customers see your identity on payment pages
• ☐SMTP configured and tested — sent a test receipt email and confirmed delivery
• ☐CWInvoice / CWFMS integration tested — if using integrations, verified invoice is marked paid after test payment
• ☐License key validated — no license error on admin login