Customer Payments — Gateway Setup & Reports Guide

Overview

Customer Payments is a multi-gateway processor for one-time charges. Each tenant brings their own Stripe / Square / Authorize.Net / NMI / Braintree / PayPal account. Card data is tokenized on the client (via Stripe Elements or the equivalent gateway SDK); the server only ever sees a token. Successful charges, declines, and refunds are logged to payment_attempts with the customer, agent, gateway, amount, and result.

V2 is a security + reporting hardening pass on top of an already-shipped charge flow. The processing pipeline itself is unchanged — only the credential storage, the report tooling, and the audit trail.

What's new in V2

Credential encryption

Algorithm: AES-256-GCM. Master key from .env (ENCRYPTION_KEY). Per-record 12-byte random IV. 16-byte GCM authentication tag. Tenant_id mixed into the additional-authenticated-data (AAD) so a ciphertext leaked from tenant A cannot be relabeled and replayed as tenant B's credentials.

Storage format on payment_gateway_configs.credentials_encrypted:

ENCv1:base64( IV (12 bytes) ‖ TAG (16 bytes) ‖ CIPHERTEXT )

Backward-compat: CredentialsCipher::decrypt() detects the ENCv1: prefix. If absent, it falls through to json_decode and returns the legacy plaintext as an array — V1 tenants keep working unchanged. The next time that tenant edits their gateway in the settings page, V2 saves in the modern format. State viewer's "Plaintext creds" stat counts how many rows still need this lazy upgrade.

Charge flow

1. Agent opens customer profile → Payments tab → clicks Charge Payment.
2. Modal renders with card fields (Stripe Elements iframe) or a manual-entry tab (cash / check / wire / etc.).
3. For card: the customer's card is tokenized client-side. The CRM never sees a PAN.
4. POST to /crm/api/payments/process.php?action=charge with the token + amount + customer_id.
5. Server creates a payment_attempts row with status='pending' BEFORE calling the gateway (idempotency).
6. Server decrypts the tenant's gateway credentials via CredentialsCipher::decrypt() and dispatches to the matching PaymentGatewayFactory implementation.
7. Gateway returns succeeded / declined / failed. Server marks the attempt row accordingly.
8. On success: writes an interactions row so the customer Activity tab shows the payment.

Refunds

Every succeeded gateway charge in the customer's Payments history shows a Refund button (admin or agent role). Clicking it:

1. Confirms the refund amount with the agent (defaults to full).
2. Prompts for an optional reason (recorded on both the attempt and the interaction row).
3. POSTs action=refund&transaction_id=....
4. Server creates a NEW payment_attempts row with negative amount + payment_method='refund'.
5. Server calls the gateway's refund API. On success, marks the new row succeeded and writes a refund row to interactions.
6. Customer's running balance increments back by the refunded amount.

Manual payments (cash / check / wire) don't get a Refund button — to reverse a manual payment, record a new manual entry with negative amount instead. Different audit trail, same attempt log.

Reports

Tenant admins open /tenant-admin/modules/customer-payments-reports.php:

• Filters: date range (default last 30 days), agent (who processed), status, payment method, customer search (name / email / id)
• Top stats: attempts, collected, refunded, net, declined / failed
• By agent: one row per agent with attempts / succeeded / declined / collected
• By method: one row per payment method with attempts + collected
• Detail list: paginated 50/page with date, customer, agent, method, status, amount, transaction ID, failure reason
• CSV export: streams the entire filtered set as CSV — no pagination cap

Common use: end-of-month reconciliation against the gateway's own dashboard, agent commission calculations, dispute / chargeback investigation.

Mac-app contract preservation

Rubi's macOS app reads payment data through /api/v2/payments.php with 7 actions: customer_history, summary, detail, gateways, recent, stats, record_manual. V2 made zero changes to that file. The schema columns the Mac app reads (payment_attempts.*) are unchanged.

The encryption is transparent to the Mac because that v2 endpoint never returns gateway credentials — it only returns attempt history (where credentials don't appear) and accepts manual-payment records (which never touch credentials). Apple App Review can proceed unblocked.

Quick start ≈ 15 minutes

1. Activate the module at RubiMine. Free.
2. Sysadmin verifies schema + cipher at /admin/run-payments-v2-migration.php. All 3 tables ✅, cipher round-trip ✅.
3. Plug in your gateway credentials at customer-payments-settings.php. Pick Stripe (recommended), paste your publishable + secret key, click Save → V2 encrypts before write.
4. Test connection on the saved gateway. Confirms the credentials work.
5. Mark it default if it's the only one, or pick which gateway to default to.
6. Take a test payment from any customer's Payments tab. Use Stripe's 4242 4242 4242 4242 test card if your gateway is in sandbox mode.
7. Confirm the Activity tab shows the payment row.
8. Open the reports page at /tenant-admin/modules/customer-payments-reports.php — filter by today, see your test payment, export CSV.

Known limitations (V2)

• No recurring billing — by design. One-time charges only. Use your gateway's native subscription tools for recurring schedules.
• No card vaulting — every charge requires a fresh tokenize. Cards aren't saved on Rubi for re-use.
• Receipt emailing isn't wired — the payment_receipts schema exists but no mailer integration. V2.1.
• Partial-refund tracking — refunds are recorded as separate negative-amount rows; the original attempt's status doesn't flip to partially_refunded until V2.1.
• Webhook idempotency — Stripe webhooks land at /api/stripe-webhook.php (separate file). Receipt processing for off-session events (chargebacks, disputes) needs explicit handling — not yet ingested into payment_attempts.
• Manual refund of manual payment — no UI button; record a negative-amount manual entry instead.
• Encryption key rotation — no automated rotation. Manual key change requires a re-encrypt migration.

Frequently asked questions