Pyle

Payments & Billing ​

Payments & Billing is the domain that configures how money is collected, records what was charged or refunded on an order, and produces the billing documents that operators or customers can retrieve later.

This first pass treats the domain as five connected layers:

  • gateway configuration and checkout entry
  • order payment capture and reconciliation
  • refunds and balance recovery
  • billing documents and invoice outputs
  • customer payment methods

Status ​

  • [x] Domain overview written
  • [x] Subdomains reviewed
  • [x] Technical node pages linked
  • [x] End-user concept pages linked
  • [x] Task guides linked

Responsibility ​

This domain is responsible for:

  • storing payment-gateway configuration and capability flags
  • creating checkout URLs and card-session URLs for supported gateways
  • recording order payments from Stripe, manual methods, credit-line flows, and synced external charges
  • creating and tracking refund records tied to order payments
  • generating invoice records and PDFs from fulfillments, returns, refunds, and order-level billing events
  • exposing invoice download and saved-card management to the packaged storefront where those surfaces exist

Subdomains ​

  • Gateway Configuration And Checkout Entry
    • PaymentGateway
    • Stripe checkout sessions
    • customer card-session URLs
  • Order Payment Capture And Reconciliation
    • OrderPayment
    • saved-card charges
    • manual payments
    • credit-line payments
    • payment sync and transfer flows
  • Refunds And Balance Recovery
    • OrderRefund
    • refund-selected-items
    • refund-and-cancel-order
  • Billing Documents And Invoice Outputs
    • Invoice
    • invoice PDFs
    • invoice emails
    • consolidated invoice outputs
  • Customer Payment Methods
    • CustomerCard
    • My Account payment methods
    • default-card and delete-card flows

Classification Decisions ​

Standalone technical pages ​

Standalone end-user pages ​

Standalone task guides ​

Folded into parent pages for now ​

  • CustomerCard
    • folded into Payment Gateway and Payment Methods because the shared package exposes it mainly through saved-card workflows rather than as a first-pass admin concept page
  • InvoiceItem
    • folded into Invoice
  • InvoiceDiscountLine
    • folded into Invoice
  • InvoiceFeeLine
    • folded into Invoice
  • InvoiceShippingLine
    • folded into Invoice
  • checkout-session and redirect controllers
    • folded into Payment Gateway and Order Payment because they are transport mechanics for payment collection rather than standalone business concepts
  • consolidated invoice PDF and email outputs
    • folded into Invoice because they summarize existing invoice records instead of representing a new billing record type

Explicitly not getting standalone end-user concept pages in this pass ​

  • Payment Gateway
  • Order Refund

Gateway configuration is an internal configuration concept, and refund handling remains mostly operator- and email-driven rather than a shared shopper-facing destination.

Evidence Highlights ​

Framework ownership ​

  • packages/framework/src/Models/PaymentGateway.php
  • packages/framework/src/Models/OrderPayment.php
  • packages/framework/src/Models/OrderRefund.php
  • packages/framework/src/Models/Invoice.php

Admin and operations surfaces ​

  • packages/framework/routes/admin.php
  • packages/framework/src/Http/Controllers/Api/Admin/PaymentGatewaysController.php
  • packages/framework/src/Http/Controllers/Api/Admin/OrderPaymentsController.php
  • packages/framework/src/Http/Controllers/Api/Admin/OrderRefundsController.php
  • packages/framework/src/Http/Controllers/Api/Admin/InvoicesController.php

Storefront and shopper-visible surfaces ​

  • packages/storefront/routes/web.php
  • packages/storefront/src/Livewire/Storefront/MyAccount/PaymentMethods
  • packages/framework/src/Http/Controllers/Api/Storefront/OrdersController.php
  • packages/storefront/resources/views/components/my-account/orders/data-table/row/header.blade.php

Core behavior and automation ​

  • packages/framework/src/Actions/Stripe/CreateStripeCheckout.php
  • packages/framework/src/Actions/Stripe/ChargeStripeCustomerCard.php
  • packages/framework/src/Actions/Stripe/SyncStripeCheckoutToOrderPayment.php
  • packages/framework/src/Actions/OrderRefund/CreateOrderRefund.php
  • packages/framework/src/Actions/OrderRefund/RefundSelectedItems.php
  • packages/framework/src/Actions/Invoice/GenerateInvoices.php
  • packages/framework/src/Actions/Invoice/CreateInvoiceFromFulfillment.php
  • packages/framework/src/Actions/Invoice/CreateInvoiceFromOrderReturn.php
  • packages/framework/src/Actions/Invoice/CreateInvoiceFromRefund.php
  • Payment gateway type and payment method type are not the same thing. Gateways are configuration records such as stripe or manual, while manual payment creation still asks for a method type such as check or cash.
  • invoice_url on Order is misleadingly named in the Stripe checkout flow. In the shared package it stores the checkout URL returned by Stripe, not a generated invoice record.
  • Refund is not the same thing as Return. OrderRefund is payment-settlement machinery; OrderReturn is the operational return workflow documented under Order Lifecycle.
  • Invoice is not the same thing as a consolidated invoice email or PDF. Consolidated outputs summarize existing order invoices, while Invoice records are generated from fulfillments, refunds, returns, or order discounts.

Priority Technical Pages ​

Priority End-User Pages ​

Priority Task Guides ​