Onboarding Part 3 – Payment Activation & Stripe Connect

At a glance

1. Step 1 – Payment Activation Screen (UX Layer)
   Screen header displays Ready to accept payments when you are. Primary CTA: Enable payments. Secondary action: Skip for now. Informational bullets explain: user controls when to accept payments, payments link directly to agreements, Happ charges a fee only on successful transactions, no fixed fees, supports cards, bank transfers and digital wallets, fully secure payments. At this point stripe_account_id is null and payment_activation_status = disabled.
2. Step 2 – Branching Logic (Enable vs Skip)
   If Skip for now is selected: payment_activation_status remains disabled. User proceeds to confirmation screen. Payment buttons in workspace remain inactive. If Enable payments is selected: system initiates Stripe Connect Express flow. A Connected Account is either created or retrieved.
3. Step 3 – Connected Account Creation (Stripe Connect Express)
   Platform creates a Connected Account of type express. account_links API is used to generate onboarding URL. User is redirected to Stripe-hosted onboarding. Required data collected by Stripe may include: legal name, address, partial government ID, phone, date of birth, industry classification, bank account details for payouts.
4. Step 4 – Capability Requirements
   After onboarding, the following Stripe capabilities must be verified as active: capabilities.card_payments = active, capabilities.transfers = active, charges_enabled = true, payouts_enabled = true. If any are inactive, the account cannot receive payments or payouts. System must validate these flags via Stripe API before enabling payment UI.
5. Step 5 – Destination Charges Model
   Happ uses Destination Charges, not Direct Charges. Checkout Sessions are created under the platform account without Stripe-Account header. payment_intent_data includes transfer_data[destination] = connected account ID and application_fee_amount representing platform fee. Customer pays platform, Stripe deducts processing fee, application fee is retained by platform, net amount is transferred to connected account.
6. Step 6 – Webhook Configuration and Verification
   Platform must register webhook endpoint at /wp-json/happ/v1/stripe/webhook. Required events: checkout.session.completed, checkout.session.expired, payment_intent.succeeded. Webhook signature must be validated using STRIPE_WEBHOOK_SECRET. livemode flag must be verified to prevent test data corruption.
7. Step 7 – Internal Ledger Recording
   Upon successful payment, system creates three internal ledger entries: Payment received (gross), Stripe processing fee, Happ platform fee. These are stored in payment_ledger repeater including amount_cents, currency, milestone_id, stripe_id and description. Ledger reflects net balance available for payout.
8. Step 8 – Capability Validation Before Payment Creation
   Before generating any Checkout Session, system validates that connected account has active charges_enabled, payouts_enabled and required capabilities. If not valid, Pay Now button must be disabled and user prompted to complete Stripe onboarding.
9. Step 9 – Configuration Requirements
   wp-config must contain STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET and HAPP_PLATFORM_FEE_PERCENT. Stripe Dashboard must have Connect enabled and webhook registered. Failure to configure correctly results in inability to create valid payment sessions.
10. Step 10 – Skip Path System State
    If payments are skipped: stripe_account_id remains null, payment_activation_status = disabled. Workspace is fully operational for agreements and signatures but payment functionality remains locked until activation occurs.
11. Step 11 – Error States and Troubleshooting
    If Checkout throws \\\'Unable to start payment\\\', likely causes include missing stripe_account_id, invalid nonce, incorrect transfer_data destination, missing STRIPE_SECRET_KEY, webhook returning non-200 response or AJAX failure before session creation. These must be validated systematically.
12. Step 12 – Final Activation State
    When Stripe Connect is active and capabilities verified: stripe_account_id stored, payment_activation_status = enabled, Pay Now buttons visible on milestones, funds flow correctly using Destination Charges, ledger reflects net balance and user can request payouts.