# Amacorp Account And Crediting System

Last updated: 2026-06-30

This file is a machine-readable implementation plan and current-state note for the Amacorp account, crediting, onboarding, and payment system. The live site has account signup and login, a session-protected review workspace, provider-hosted review checkout and top-up handoff records where enabled, and an internal USD buying-power ledger that can be updated only after signed provider confirmation or protected admin action. It does not create a wallet, brokerage account, custody account, investment application, issuer-affiliated workflow, allocation, offer, recommendation, or guaranteed private-share access.

## Current State

The live site collects limited access review requests and lets protected admins assign review status, account/follow-up status, priority, owner initials, next step, and internal notes. The `/account`, `/dashboard`, `/checkout`, and `/top-up` flows are session-protected review surfaces. Admin fields, checkout records, top-up records, and ledger records are coordination and reconciliation metadata only until a separate manual review process is complete.

The live site has:

- First-party account signup and login.
- Session-protected review workspace pages.
- Passkey and social-provider hooks where enabled by the server configuration.
- Stripe-hosted review checkout and USD top-up handoff records where provider gates are enabled.
- Signed-webhook reconciliation for Stripe events.
- Internal USD buying-power ledger records such as `topup_requested`, `topup_link_created`, `topup_returned_pending_webhook`, `topup_confirmed`, and `purchase_debit`.
- Manual allocation-required purchase request records after eligible USD buying power is debited.
- Non-executable crypto USD estimates for admin triage only.
- Yield-interest intake for future review only.

The live site does not provide:

- Brokerage accounts.
- Investment checkout.
- Public order entry.
- Issuer affiliation.
- Guaranteed allocation.
- Apple Pay.
- Wallets.
- KYC.
- Accreditation verification.
- Document signing.
- Bank or wallet funding instructions.
- Executable private-share prices.
- Executed securities orders.
- Stock balances.
- Crypto custody.
- Crypto conversion.
- Yield accrual.
- APY, promised returns, or yield balances.

The live `/account` page lets a logged-in visitor see review workspace records and submit review-only account, top-up, or purchase-review activity. It states that no wallet funding, crypto custody, crypto conversion, yield product, investment access, executed order, allocation, or stock balance is active.

## Live Account Intent Funnel

The current account funnel records these actions:

- `account_create_intent`: asks admin to review whether account access should be expanded later.
- `deposit_intent`: records an indicative USD amount and preferred future rail, without creating funding instructions.
- `topup_requested`: records a USD top-up request before any provider checkout is created.
- `topup_link_created`: records that a Stripe-hosted checkout handoff was created.
- `topup_returned_pending_webhook`: records that a browser return happened before signed provider confirmation.
- `topup_confirmed`: records provider-confirmed USD buying power after signed provider confirmation and amount checks.
- `purchase_debit`: debits confirmed USD buying power for a manual-allocation-required purchase request.
- `purchase_review_intent`: records named-company interest such as SpaceX, OpenAI, Anthropic, or Neuralink, without creating an order.
- `crypto_deposit_intent`: records asset, network, indicative crypto amount, and an optional admin-only USD estimate, without showing a wallet address, accepting crypto, converting crypto, crediting a balance, or creating an executable quote.
- `yield_interest`: records interest in a future USD yield product, without quoting APY, accepting funds, or crediting yield.

Review-intent forms post to `/api/inquiries` and appear in `/admin`, `/admin.csv`, `/admin.json`, `/admin/redacted.csv`, and `/admin/redacted.json`. Top-up records are stored in the append-only balance ledger. Provider events are stored in the provider-event log. Crypto quote fields use `crypto_quote_*` names and remain non-executable admin metadata.

## Recommended Stack

### Authentication

The current implementation uses first-party account/session handling with passkey and social-provider hooks where enabled. Privy or a similar auth provider can still be considered later for:

- Email login.
- Passkeys or social login if approved.
- Session management.
- Account linking.
- Optional wallet connection only if needed later.

Do not use Privy wallet features as proof of investor identity, accreditation, suitability, custody, or payment approval.

### Payments

Use Stripe first only after the exact use case is approved by Stripe and counsel. The current code can create Stripe Checkout Sessions for review checkout and USD top-up handoff only when `CHECKOUT_PROVIDER=stripe`, `STRIPE_CHECKOUT_ENABLED=1`, a server-side secret key, and a webhook secret are installed. Buying power must not be credited from browser return alone; it requires signed provider confirmation and amount checks.

Use Polar only for clearly allowed software, membership, subscription, or non-investment products. Do not use Polar as a shortcut for investment funding, securities purchase, or issuer access.

Use Square only for an approved payment type such as a review fee, membership, or other non-investment product. Keep Square sandbox-only until the product, refund policy, webhook verification, ledger mapping, and counsel-approved copy exist.

Do not add Apple Pay to the public landing page until the flow is approved. The safe future framing is:

```text
Approved account -> approved product or fee -> compliant checkout
```

The unsafe framing is:

```text
Payment button -> named private-company stock
```

## Account Status Model

Use account-level status separate from lead status:

- `account_created`
- `email_verified`
- `profile_started`
- `profile_completed`
- `admin_review_pending`
- `admin_reviewed`
- `identity_required`
- `identity_started`
- `identity_passed`
- `identity_failed`
- `accreditation_required`
- `accreditation_pending`
- `accreditation_passed`
- `accreditation_failed`
- `documents_required`
- `documents_sent`
- `documents_signed`
- `funding_not_enabled`
- `funding_pending`
- `funding_received`
- `partner_review`
- `approved`
- `rejected`
- `withdrawn`
- `closed`

Each status change should store:

- Timestamp.
- Actor: user, admin, system, provider webhook.
- Source: admin panel, webhook, import, migration.
- Previous status.
- New status.
- Notes.
- Idempotency key.

## USD Buying-Power Ledger

Use an append-only ledger for USD buying-power reconciliation. Do not overwrite balances directly and do not label ledger rows as securities ownership.

Ledger entry fields:

- `entry_id`
- `topup_id`
- `related_order_id`
- `account_id`
- `user_id`
- `lead_id`
- `provider`
- `provider_event_id`
- `checkout_session_id`
- `payment_intent`
- `entry_type`
- `amount`
- `amount_cents`
- `currency`
- `status`
- `created_at`
- `updated_at`
- `effective_at`
- `reversed_at`
- `memo`
- `note`

Allowed `entry_type` values:

- `topup_requested`
- `topup_link_created`
- `topup_returned_pending_webhook`
- `topup_confirmed`
- `topup_failed`
- `topup_review_required`
- `purchase_debit`
- `review_fee_authorized`
- `review_fee_captured`
- `review_fee_refunded`
- `membership_fee_captured`
- `admin_credit`
- `admin_debit`
- `partner_allocation_recorded`
- `partner_allocation_reversed`

Do not use these labels without legal approval:

- `stock_balance`
- `shares_owned`
- `OpenAI shares`
- `Anthropic shares`
- `Neuralink shares`
- `guaranteed allocation`
- `confirmed allocation`

## Integration Gates

Before enabling auth:

1. Project-owned app account.
2. Project-owned email domain.
3. Privacy policy updated for account data.
4. Admin access policy updated.
5. Data retention and deletion workflow defined.

Before enabling payments:

1. Stripe, Polar, or payment provider account approved for the exact use case.
2. Counsel-approved checkout wording.
3. Refund/cancellation policy.
4. Webhook signature verification.
5. Idempotency keys.
6. Audit log.
7. No public investment checkout.

Before enabling credits:

1. Ledger schema.
2. Admin review permissions.
3. Reversal flow.
4. Export flow.
5. Reconciliation with provider events.
6. Clear user-facing labels that do not imply stock ownership.
7. No balance credit from unsigned webhooks, browser returns, or user-submitted provider ids.

## Provider Event Mapping

Map provider webhooks into internal events:

- `auth.user.created` -> `account_created`
- `auth.email.verified` -> `email_verified`
- `checkout.session.completed` -> `topup_confirmed` or `review_fee_captured` only if the matched payment type is approved, signed, amount-checked, and idempotent.
- `checkout.session.expired` -> `review_checkout_expired`
- `payment_intent.succeeded` -> `topup_confirmed` or `funding_received` only if the funding path is approved, signed, amount-checked, and idempotent.
- `payment_intent.payment_failed` -> `funding_pending` or `rejected`
- `charge.refunded` / `charge.dispute.created` -> reconciliation review only.
- `customer.subscription.updated` -> membership status only, not investment status.
- `order.paid` -> paid non-investment product only, unless Polar has approved the exact use case.
- Square `payment.created` / `payment.updated` -> neutral payment status only after webhook signature verification and only for an approved payment type.

Provider event names may vary. Confirm exact webhook names in the provider dashboard and docs before implementation.

## Admin Panel Requirements

The admin panel should eventually show:

- Account status.
- Lead status.
- Lead score and score reasons.
- Account invite readiness.
- Account invite queue.
- Recommended admin action.
- Main interest.
- Eligibility signal.
- Identity status.
- Accreditation status.
- Document status.
- Payment status.
- Ledger summary.
- Last provider event.
- Next required action.

## User Portal Requirements

The user portal should show:

- Profile status.
- Review status.
- Required next action.
- Documents requested only through approved provider links.
- Payment or top-up actions only after approval and server-side provider gates.
- Ledger entries with conservative labels.

Do not show:

- Stock balances.
- Guaranteed allocations.
- Issuer logos suggesting affiliation.
- Trading UI.
- Public order entry.
- Wallet deposit address.

## Current Admin Account Queue

The protected admin panel now includes an account invite queue. It is a triage view only. It does not create accounts, send invites, verify identity, verify accreditation, approve suitability, approve payments, or approve investment access.

Readiness labels:

- `Ready`: admin-marked lead that may receive an invite later after project email and compliance gates clear.
- `Candidate`: strong lead that still needs an admin status decision.
- `Hold`: sensitive-data, identity, accreditation, or provider workflow issue must be handled first.
- `Review`: keep in manual review.
- `Blocked`: spam, closed, rejected, or not-fit lead.

The admin panel also includes reply SLA and duplicate email fields. These help decide when a reviewed lead may need a project-owned inbox reply before any future invite-only account step.

## Reference Links

- Privy docs: https://docs.privy.io/welcome
- Privy React quickstart: https://docs.privy.io/basics/react/quickstart
- Stripe Checkout Sessions: https://docs.stripe.com/api/checkout/sessions
- Stripe webhooks and events: https://docs.stripe.com/api/events/types
- Stripe Financial Connections: https://docs.stripe.com/financial-connections
- Stripe Customer Portal: https://docs.stripe.com/customer-management
- Stripe restricted businesses: https://stripe.com/legal/restricted-businesses
- Polar docs: https://polar.sh/docs/introduction
- Polar webhooks: https://polar.sh/docs/integrate/webhooks
- Polar acceptable use: https://polar.sh/docs/merchant-of-record/acceptable-use
- Square Web Payments SDK: https://developer.squareup.com/docs/web-payments/overview
- Square access tokens: https://developer.squareup.com/docs/build-basics/access-tokens
- Square webhook validation: https://developer.squareup.com/docs/webhooks/step3validate
- Square sandbox payments: https://developer.squareup.com/docs/devtools/sandbox/payments