Univapay Integration: Project Design & Specification

1. Project Summary

This project integrates Univapay as a multi-tenant payment provider. It follows the “Platform” model, allowing each Supplier (User) to have their own Univapay Store. This enables automated revenue payouts and fee-splitting, mirroring the existing Stripe Connect implementation.

New Requirement: Content-Level Payment Control

Suppliers have the granular control to enable or disable Univapay for specific content (services). When creating or editing content, the user can toggle whether Univapay methods (PayPay, Bank Transfer, Univapay Credit Card) are offered to customers for that specific item.

2. Backend Design (Laravel)

2.1 Domain & Models

• New Table: user_payment_univapays
  • id, user_id, store_id, api_key, secret_key, charges_enabled, status, created_at, updated_at.
• Model Update: Order
  • Add univapay_charge_id to track the remote transaction.
• Model Update: ServicePaymentMethod
  • Add logic to support univapay as a valid payment type associated with a specific service.

2.2 Traits & Logic

• UnivapayPlatform Trait: Added to common/src/Base/Traits.
  • createSubStore(User $user): Calls Univapay API to create a store and returns credentials.
  • createCharge(Order $order, array $paymentMethod): Initiates a Univapay charge.
  • refundCharge(string $chargeId, int $amount): Handles partial/full refunds.
• Platform Fee Logic: Extend PlatformFeeCal to calculate the platform’s cut for Univapay transactions based on the user’s plan.

3. Frontend Design (Next.js)

3.1 Supplier Onboarding (supplier dashboard)

• UnivapayConnectInfo Component:
  • Displays current connection status.
  • Shows active payment methods (Cards, PayPay, Bank Transfer).
  • Includes a “Connect Univapay” button that triggers automated store creation.
• Integration: Add to yoyacoo_fe/supplier/src/pages/accounts/payment/index.tsx.

3.2 Content Creation & Management

• Payment Toggle: In the “Create/Edit Service” form, add a checkbox: “Allow Univapay payments (PayPay, Bank Transfer, etc.)”.
• Conditional Logic: Disable the selection and provide a tooltip or hint (e.g., “Connect Univapay in Settings to enable”) if the Supplier has not yet connected their Univapay account.

3.3 Customer Reservation (customer site)

• Dynamic Payment Methods: The checkout step will fetch allowed payment methods for the specific service. If the user disabled Univapay for that content, only Stripe/PayPal (if enabled) will appear.
• Univapay Widget:
  • Load https://widget.univapay.com/client/checkout.js.
  • Use an inline form where customers can select between Credit Card, PayPay, or Bank Transfer.

4. Webhook & Fulfillment

• Univapay Webhook Handler:
  • Listens for charge.updated and charge.finished.
  • Updates Order status to “Paid” upon success.
  • Triggers reservation confirmation emails and external syncs (Google Calendar).

5. Security & Compliance

• Data Isolation: Univapay credentials are encrypted and scoped to the authenticated User.
• PCI Compliance: Card data never touches our servers; handled entirely by the Univapay Widget.
• Verification: Webhook requests are validated using Univapay’s shared secret signature.