Payment Lifecycle
End-to-end payment object lifecycle from order intent through checkout, tokenization, transaction execution, receipt, allocation, settlement, refunds, voids, and disputes
This guide explains how payment records move through Salesforce. Use it when reconciling a customer payment or diagnosing payment readiness.
Lifecycle Map
Source Records
Payment work can start from a Quote, Sales Order, Invoice, Account, or Contact.
| Source | Typical payment action |
|---|---|
| Quote | Validate payment plan/readiness before approval or conversion. |
| Sales Order | Create payment order, send link, manage recurring plan, review payment console. |
| Invoice | Send invoice and collect AR. |
| Account/Contact | Add saved payment method. |
| Payment Order | Send link, print payment order, record dispute. |
Payment Order
Payment_Order__c is the collection intent. It groups customer, amount, route, due date, collection method, payment method/token, invoice, quote, and sales order context.
Use it to answer:
| Question | Field/object area |
|---|---|
| Who owes money? | Account, Contact, payer fields. |
| What is being paid? | Quote, Sales Order, Invoice, Payment Order Lines. |
| How much is requested? | Requested, authorized, captured, refunded, balance fields. |
| How will it be collected? | Collection method, route key, gateway, saved token. |
| What happened recently? | Latest transaction, email, settlement, collection action fields. |
Payment Intent and Public Link
Payment_Intent__c represents an executable public checkout intent. PaymentLinkCheckoutController and PaymentLinkCheckoutService handle public payment link behavior.
Payment links should be generated from supported Salesforce actions so the token, expiry, amount, customer context, and email history remain connected.
Execution State Flow
Saved Methods and Tokens
Saved payment methods are represented by Payment_Method__c, Payment_Profile__c, and Payment_Method_Token__c.
Token coverage is not just "does the customer have a card." A saved method needs a valid token for the route/gateway being used.
| Token state | Meaning |
|---|---|
| Valid route token | Can collect with saved method. |
| Missing route token | Customer may need a new method or admin retokenization. |
| Deprecated gateway token | May be legacy-executable only if lifecycle rules allow it. |
| Removed gateway token | Should not be used for new execution. |
Attempts and Transactions
Payment_Attempt__c records an attempt. Payment_Transaction__c records execution evidence such as action, amount, gateway, idempotency key, reference numbers, provider transaction id, fees, settlement state, and reversals.
Transaction execution goes through services such as PaymentTransactionExecutionService, gateway adapters, idempotency logic, and post-processing services.
Do not create transaction records manually to "make a report work." The transaction is accounting and processor evidence.
Receipts and Allocations
Payment_Receipt__c and Payment_Allocation__c connect collected funds to invoices and AR.
If payment appears collected but AR does not move:
- Confirm the Payment Transaction captured amount.
- Confirm the Payment Receipt exists.
- Confirm allocation to the intended Invoice.
- Confirm the invoice balance and aging reports.
- Check post-processing failures.
Settlement
Settlement sync uses Settlement_Batch__c, Settlement_Line__c, transaction settlement fields, and settlement scheduler/service classes.
Finance should reconcile:
| Record | Use |
|---|---|
| Payment Transaction | Processor reference, fee, captured/refunded amount. |
| Settlement Batch | Batch-level settlement state. |
| Settlement Line | Per-transaction settlement detail. |
| Gateway accounting reports | Gateway mix, fee, monthly accounting. |
Refunds, Voids, and Disputes
Refunds and voids should route through PaymentTransactionReversalService and supported payment actions. Disputes should be recorded through RecordDispute on Payment Order.
| Event | Expected evidence |
|---|---|
| Void | Parent transaction, reversal action, provider reference, updated balance. |
| Refund | Refunded amount, parent transaction, receipt/allocation impact. |
| Dispute | Dispute__c record tied to payment order/transaction context. |
| Processor event | Processor_Event__c record with payload hash/reference. |
Recurring Payments
Recurring plans use Payment_Agreement__c, recurring plan services, lifecycle actions, recurring scheduler, and payment order/transaction creation over time.
Before treating recurring collection as live:
- Confirm Payment Operations Settings allow recurring payments.
- Confirm the schedule exists and is intended to run.
- Confirm the agreement is active and has a next scheduled payment.
- Confirm token coverage remains valid.
- Confirm pause/resume/cancel actions update the agreement state.
Recurring Plan Flow
Last updated on