Univapay Integration: Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Integrate Univapay as a marketplace payment provider with per-content control and automated onboarding.

Architecture: A multi-tenant “Connect” model using a central Laravel trait for API communication. It allows suppliers to enable Univapay for specific services, mirroring the existing Stripe Connect architecture.

Tech Stack: Laravel (Backend), Next.js (Frontend), Univapay PHP SDK & JS Widget.

Task 1: Backend Foundation & SDK Setup

Files:

• Modify: yoyacoo_be/common/composer.json

• Create: yoyacoo_be/common/config/univapay.php

• Step 1: Add Univapay SDK
  Add "univapay/univapay-php": "^1.0" to the require section of yoyacoo_be/common/composer.json.

• Step 2: Run composer update
  Run composer update univapay/univapay-php in the yoyacoo_be/common directory.

• Step 3: Add configuration
  Create config/univapay.php to map environment variables for Platform ID and Secret Key.

Task 2: Database Migrations

Files:

• Create: yoyacoo_be/common/database/migrations/YYYY_MM_DD_create_user_payment_univapays_table.php

• Modify: yoyacoo_be/common/database/migrations/YYYY_MM_DD_add_univapay_columns_to_orders_table.php

• Step 1: Create user_payment_univapays table
  Define schema: id, user_id (foreign), store_id, api_key, secret_key, charges_enabled (bool), status.

• Step 2: Update orders table
  Add univapay_charge_id (string, nullable) and univapay_status (string, nullable).

• Step 3: Run migrations
  Run php artisan migrate.

Task 3: Core API Trait (UnivapayPlatform)

Files:

• Create: yoyacoo_be/common/src/Base/Traits/UnivapayPlatform.php

• Modify: yoyacoo_be/common/src/Models/UserPaymentSetting.php

• Step 1: Implement createSubStore
  Logic to call Univapay’s Store creation endpoint using platform credentials.

• Step 2: Implement createCharge
  Logic to initiate a charge targeting the user’s specific store_id.

• Step 3: Implement refundCharge
  Logic to handle refunds via the Univapay SDK.

Task 4: Supplier Onboarding UI & API

Files:

• Create: yoyacoo_be/user/app/Domains/Account/Usecase/ConnectUnivapayInteractor.php

• Create: yoyacoo_fe/supplier/src/components/organisms/accounts/index/UnivapayConnectInfo.tsx

• Modify: yoyacoo_fe/supplier/src/pages/accounts/payment/index.tsx

• Step 1: Create Backend Onboarding Interactor
  Handle the “One-Click Connect” logic: call createSubStore and save credentials.

• Step 2: Create Frontend Connection Component
  Build UnivapayConnectInfo mirroring the existing StripeConnectInfo.tsx layout.

• Step 3: Integrate into Settings Page
  Place the new component in the main Payment Settings layout.

Task 5: Per-Content Payment Control

Files:

• Modify: yoyacoo_be/common/src/Models/ServicePaymentMethod.php

• Modify: yoyacoo_fe/supplier/src/components/organisms/services/ServiceForm.tsx

• Step 1: Add “Univapay” to allowed payment types
  Update Enums and Model logic to recognize univapay as a valid payment option.

• Step 2: Update Service Form UI
  Add the “Enable Univapay” checkbox to the service creation/edit form.

• Step 3: Implement Disabled State Logic
  If the user hasn’t connected Univapay in Settings, the checkbox should be disabled with a hint: “Connect Univapay in Settings to enable”.

Task 6: Customer Checkout & Webhooks

Files:

• Create: yoyacoo_be/customer/app/Http/Controllers/UnivapayWebhookController.php

• Modify: yoyacoo_fe/customer/src/components/organisms/reservation/PaymentSelection.tsx

• Step 1: Implement Univapay Widget
  Load the Univapay JS SDK and mount the widget when Univapay is selected at checkout.

• Step 2: Create Webhook Handler
  Process charge.finished events. Verify the signature and update the internal Order status.

• Step 3: Final Verification
  Test the complete flow from onboarding to content enablement and customer checkout.