Payment Gateway Lifecycle
Admin guide for gateway setup, connection testing, successor-backed replacement, token coverage, and historical transaction safety
Use Payment Gateway Connections from the Settings app in QA:
https://exodus--vesper.sandbox.lightning.force.com/lightning/n/Payment_Gateway_Connections
Gateway Principle
Payment gateways are operational identities, not disposable credential rows. Existing payment methods, tokens, transactions, settlement, routes, and reports can point to a gateway. Treat gateway changes as lifecycle work.
Core Records
| Record | Purpose |
|---|---|
Payment_Gateway__c | Gateway identity, status, adapter, credentials, environment, and lifecycle. |
Payment_Method_Token__c | Customer token coverage for a gateway or vault route. |
Item_Payment_Gateway__c | Item or route-specific gateway assignment. |
Payment_Transaction__c | Execution evidence and gateway transaction history. |
Processor_Event__c | Incoming processor event/webhook evidence. |
Settlement_Batch__c and Settlement_Line__c | Reconciliation and settlement reporting. |
Lifecycle States
| State | Meaning | Admin behavior |
|---|---|---|
| Active | Eligible for new routing and token readiness. | New quotes and payment orders can use it if route checks pass. |
| Deprecated | Existing-token execution may continue while new routing moves away. | Use only during migration or retokenization windows. |
| Removed | No longer used for execution. | Use only after successor migration and associated-record repair are complete. |
Gateway status should not be changed casually. A deprecated gateway can still be important for historical transactions and legacy token execution.
Gateway Setup Checklist
- Confirm gateway type and adapter class.
- Confirm sandbox versus production environment.
- Configure Named Credential and External Credential names where required.
- Configure API login, public client key, transaction key, signature key, and webhook base URL as applicable.
- Confirm support flags for cash, check, manual ACH, wallet, shared vault, and manual payments.
- Run connection testing from the gateway UI.
- Validate a sandbox payment path before routing real quote/payment traffic.
Relevant Payment_Gateway__c fields include Gateway_Type_Key__c, Adapter_Class__c, Execution_Mode__c, Lifecycle_Status__c, Live_Mode__c, Named_Credential_Name__c, External_Credential_Name__c, Public_Webhook_Base_Url__c, and last connection test fields.
Replacement Flow
Use successor-backed replacement when rotating merchant accounts, gateway IDs, or credential identity.
Do not edit gateway identity in place if historical tokens or transactions still point to it. Keep history readable and move new routing to the successor.
Token Coverage
PaymentTokenCoverageService provides route-level readiness. It can distinguish:
| Readiness state | Meaning |
|---|---|
| Ready | Saved method and token can be used for the selected route. |
| Retokenization required | A saved method exists but does not have valid successor/gateway coverage. |
| New payment method required | Customer must provide a supported new method. |
| Gateway unavailable | Gateway is inactive, deprecated without usable legacy path, removed, or misconfigured. |
Sales users should follow the message. Admins should diagnose the gateway, route, token, and item assignment behind the message.
Sandbox Versus Production
Sandbox gateways can use supported test cards. Production gateway mode must not accept sandbox-only test behavior. The payment code has explicit environment checks to prevent mixing sandbox and production gateway assumptions in one transaction path.
For Vesper QA, use Sandbox A and Sandbox B only for test flows. Do not document or share production credentials in the docs site.
Validation After Gateway Changes
Run these checks before calling a gateway change ready:
- Connection test succeeds.
- Payment Operations Settings still match the intended runtime mode.
- Quote readiness shows the expected route state.
- Add payment method works in sandbox for Account or Contact.
- Payment link checkout works for a Payment Order.
- Existing-token behavior is still correct for deprecated gateways.
- Refund/void/dispute behavior is still routed correctly where applicable.
- Settlement and gateway accounting reports still reconcile.
Last updated on