Skip to main content

Checkout and Payments Feature Context

Source: .agents/references/features/checkout-and-payments.md

Content​

Checkout and Payments Feature Context

Purpose​

Checkout and payments cover the flows where visitors or members buy products, subscriptions, memberships, event tickets, sessions, files, and physical goods. This domain is high-risk because it touches pricing, discounts, taxes/fees, payment methods, redirects, analytics, and third-party providers such as Stripe, PayPal, Ebanx, and embedded checkout surfaces.

User-Facing Workflows​

  • Buyers enter checkout from community/product pages, checkout widget pages, physical product pages, plan/subscription pages, or magic checkout flows.
  • Users select payment methods, apply discount codes, review pricing/fees, submit payment, and land on success or authentication/3DS redirects.
  • Product-specific flows can include shipping, location availability, variants, inventory, membership tier selection, affiliate codes, and abandoned checkout recovery.
  • Failed service calls should show existing error toast behavior and reset loading or payment state.
  • Checkout UI must be robust on mobile because footers, summaries, and payment forms are often sticky or narrow.

Key Entrypoints​

  • Routes:
    • src/pages/checkout-global/
    • src/pages/checkout-widget.page.js
    • src/pages/payment-authentication/
    • src/pages/payment-method/
    • src/pages/ebanx-method-update/
    • src/pages/ebanx3ds/
    • src/pages/[communityLink]/physical-products/[productSlug]/
    • src/pages/[communityLink]/join-membership/[tierId].page.tsx
  • Components/features:
    • src/features/CommonCheckoutComponents/
    • src/features/MagicAdsCheckout/
    • src/features/MagicContentCheckout/
    • src/features/AbandonedCheckout/
    • src/features/Affiliates/
    • src/pages/[communityLink]/physical-products/components/checkout/
    • src/components/common/CheckoutPartials/
  • Hooks:
    • src/hooks/usePayment/
    • src/hooks/useFeeCalculation.ts
    • src/hooks/useEntityPrice.ts
    • src/hooks/useEventBulkPurchase.js
    • src/hooks/useInitCommunitySignup.js
    • src/hooks/useGetReferralDetails.js
  • Services:
    • src/services/paymentService.js
    • src/services/changeMethodService.js
    • src/services/unifiedProduct/unifiedProductServices.ts
    • src/services/referral/referralService.ts
    • src/services/nasPlan/nasPlanService.js
  • Utilities:
    • src/utility/checkoutConstants.js
    • src/utility/checkoutUtils.js
    • src/utility/productUtils.ts
    • src/utility/priceValidationUtil.ts
    • src/utility/getSignatureForPresigned.ts

Data Flow and Service Boundaries​

  • Service modules under src/services/ generally return { data, error }; callers should destructure that shape and check if (error) instead of wrapping service calls in try/catch.
  • Pricing is often composed from product state, selected variants/items, discounts, fees, currency, buyer country, and payment provider. Inspect the existing hook/service chain before changing a displayed amount.
  • Payment redirects and authentication routes may depend on query params and provider callback shape. Guard missing params explicitly and avoid leaking sensitive values in logs.
  • Affiliate/referral and abandoned checkout flows may write/read browser storage through existing utility wrappers. Do not add direct localStorage or sessionStorage access.
  • Physical product checkout adds shipping, variants, and location constraints. Start with src/pages/[communityLink]/physical-products/ before touching generic checkout helpers.

Conventions and Gotchas​

  • Treat payment amount, currency, product ID, checkout ID, user ID, and redirect params as hostile input. Validate at boundaries and avoid unsafe interpolation.
  • Keep loading state deterministic. If an error path returns early, reset the same state the success path would leave stable.
  • Do not add broad try/catch around service APIs. Use the repo service-response pattern.
  • Avoid duplicating price formatting. Search existing price utilities and product card display helpers first.
  • Preserve analytics action IDs and provider-specific event timing unless the task explicitly changes them.
  • Do not inline styles for provider widgets unless the third-party API requires dynamic values.
  • For discount or pricing copy, use direct t() keys and aligned placeholders.
  • .agents/rules/no-try-catch-service-api.mdc
  • .agents/rules/web-security.mdc
  • .agents/rules/no-inline-styles.mdc
  • .agents/rules/use-classnames-for-conditional-classes.mdc
  • .agents/rules/direct-translation-and-component-files.mdc
  • .agents/references/coding-standard/useeffect-guidance.md

Useful Searches​

rtk rg "checkout|payment|discount|stripe|paypal|ebanx|3ds|fee|price" src/pages src/features src/hooks src/services src/utility
rtk rg "showErrorToast|paymentService|selectedPaymentMethod|discountCode" src
rtk find src/features/CommonCheckoutComponents -maxdepth 4 -type f

Update Triggers​

Update this reference when payment service contracts, checkout routes, pricing display, provider redirects, discount handling, or physical product checkout behavior changes.