Payment Technical Reference

Developer reference for payment services, objects, public checkout, gateway adapters, token coverage, schedulers, sandbox simulation, and reversal behavior

Use this page when changing payment code or diagnosing payment behavior beyond the user-facing Payment Operations screens.

Source Ownership

Payment source lives primarily in features-payments, with Sales Order and Invoice integration in features-orders and quote readiness hooks in features-crm.

Area	Source
Gateway records and runtime	`features-payments/main/default/classes/payments`
Payment objects/tabs/pages	`features-payments/main/default/objects`, `tabs`, `pages`, `flexipages`
Payment LWCs	`features-payments/main/default/lwc`
Sales Order payment workspace	`features-orders/main/default/lwc/salesOrderPaymentsWorkspace`
Quote payment plan/readiness	quote services and `QuotePaymentPlanService`
Invoice/payment sync	`InvoicePaymentSyncService`, invoice email/PDF services

Core Services

Service	Responsibility
`PaymentGatewayConnectionsController`	Admin-facing gateway inventory and connection UI.
`PaymentGatewayLifecycleService`	Active/deprecated/removed lifecycle and successor handling.
`PaymentGatewayManagementService`	Gateway management operations.
`PaymentGatewayRegistry`	Adapter/provider resolution.
`PaymentTokenCoverageService`	Route-level readiness and retokenization state.
`PaymentTokenizationService`	Token creation and token record management.
`PaymentTransactionExecutionService`	Authorize/capture/sale execution and idempotency.
`PaymentTransactionRuntimeService`	Runtime transaction orchestration.
`PaymentTransactionReversalService`	Void/refund/reversal behavior.
`PaymentOrderService`	Payment order creation and maintenance.
`PaymentLinkCheckoutService`	Public payment link checkout execution.
`PaymentSettlementSyncService`	Settlement sync and reconciliation fields.
`RecurringPaymentPlanService`	Recurring plan creation and lifecycle.
`PaymentVaultManagementService`	Vault inventory and saved method operations.

Adapters include AuthorizeNetGatewayAdapter, InternalVaultGatewayAdapter, and the base gateway adapter classes. Gateway records identify adapter behavior through fields such as Gateway_Type_Key__c, Adapter_Class__c, Execution_Mode__c, Named_Credential_Name__c, and External_Credential_Name__c.

Adapter changes must preserve:

Idempotency.
Provider reference fields.
Error handling and sanitized user messages.
Sandbox versus production behavior.
Settlement and reversal compatibility.

Public Checkout

The hosted payment link checkout is implemented as PaymentLinkCheckout.page with controller/service support. Payment intents should be reached through generated public tokens, not manually constructed URLs.

Technical expectations:

Requirement	Reason
Tokenized public link	Avoids exposing internal record ids.
Expiry enforcement	Prevents stale links from collecting unexpectedly.
Idempotency key	Prevents duplicate execution on retry/refresh.
Gateway environment guard	Prevents sandbox/production mixing.
Post-processing	Updates orders, receipts, allocations, and metrics.

Token Coverage States

PaymentTokenCoverageService is the readiness source for route-aware payment UX.

State	Technical meaning
Ready	Saved method has usable token coverage for route/gateway.
Retokenization required	Method exists but successor/gateway coverage is missing.
New payment method required	Customer must provide a new method.
Gateway unavailable	Gateway lifecycle/config prevents execution.

Do not replace this logic with a simpler "has card" check.

Schedulers and Queueables

Scheduler/queueable	Purpose
`RecurringPaymentScheduler`	Runs recurring payment execution.
`RecurringPaymentExecutionQueueable`	Executes recurring payment work.
`PaymentAutomatedCollectionScheduler`	Runs automated collections.
`PaymentAccountUpdaterScheduler`	Runs account updater sync.
`PaymentGatewayHealthMonitorScheduler`	Checks gateway health.
`PaymentSettlementSyncScheduler`	Runs settlement sync.
`PaymentRuntimePostProcessingQueueable`	Performs async post-processing after payment execution.

Settings in Payment_Operations_Settings__c gate runtime behavior. A schedule can exist while a feature toggle remains disabled.

Sandbox Simulation

SandboxPaymentSimulationService supports sandbox-only payment simulation. It checks org sandbox state and prevents simulation behavior in production.

Use sandbox simulation for QA and stress flows only. Do not rely on sandbox tokens or test-card behavior in production gateway testing.

Reversal and Dispute Behavior

Voids/refunds use PaymentTransactionReversalService. Disputes use ManualDisputeService and Payment Order dispute action surfaces.

Technical changes in this area must verify:

Parent transaction lookup.
Gateway adapter reversal support.
Refunded/voided amount math.
Receipt/allocation impact.
Settlement reporting impact.
Dispute record linkage.
Existing sandbox simulation branches.

Validation Guidance

For payment code changes, use focused tests first, then org/runtime validation when ready:

sf apex run test --target-org vesper --class-names PaymentGatewayLifecycleServiceTest,PaymentTokenCoverageServiceTest,PaymentTransactionExecutionServiceTest
sf apex run test --target-org vesper --class-names PaymentLinkCheckoutServiceTest,PaymentOrderServiceTest,PaymentSettlementSyncServiceTest

Use the exact class list that matches your changed files. Do not claim payment operations are production-ready from local tests alone; confirm deployability, settings toggles, and scheduler state in the target org.