State Mismatches
A state mismatch occurs when different systems have different states for the same transaction.
For example:
Payment Provider
└── Successful
SolydFlow
└── Pending
The payment may have succeeded, but SolydFlow has not yet received or processed the information needed to update its transaction state.
State mismatches are a normal challenge in distributed payment systems.
SolydFlow Truth is designed to help identify these differences, gather additional evidence, and resolve the transaction into a reliable state.
Why State Mismatches Happen
A payment transaction can pass through several systems:
Customer
↓
Application
↓
SolydFlow
↓
Payment Provider
Information can be delayed or lost between these systems.
For example:
Provider
↓
Successful Payment
X
Webhook Delivery
The provider knows the payment succeeded, but SolydFlow may still show:
Pending
This creates a state mismatch.
A State Mismatch Is Not Necessarily a Payment Failure
This distinction is important.
Suppose:
Provider
└── Successful
SolydFlow
└── Pending
The mismatch does not mean:
Payment Failed
It means:
Systems Disagree
The transaction needs to be investigated and, where necessary, verified.
Common Causes
State mismatches can occur because of:
- Missing webhooks
- Delayed webhooks
- Duplicate webhooks
- Out-of-order events
- Network failures
- Provider API delays
- Payment request timeouts
- Recovery operations
- Manual intervention
- Provider-specific transaction behavior
- Incomplete synchronization
These conditions can cause different systems to temporarily or permanently disagree.
Types of State Mismatches
Provider vs SolydFlow
The provider reports one state while SolydFlow has another.
Provider
└── Successful
SolydFlow
└── Pending
This is one of the most important mismatch types because the provider may have information that SolydFlow has not yet received.
Application vs SolydFlow
The application may maintain its own transaction state.
For example:
Application
└── Successful
SolydFlow
└── Pending
This can happen if the application updated its own records based on information that SolydFlow has not yet processed.
Application vs Provider
The application may disagree directly with the payment provider.
Application
└── Failed
Provider
└── Successful
In this situation, SolydFlow can provide an intermediate layer for resolving the transaction state.
Multiple Provider Signals
Even information from the same provider can appear inconsistent.
For example:
Provider Response
└── Pending
Provider Verification
└── Successful
This requires context and verification rather than simply choosing one value.
How Mismatches Develop
Consider a payment request:
Application
↓
SolydFlow
↓
Provider
The provider processes the payment:
Provider
└── Successful
But the response is lost:
Provider
↓
Successful
X
Response
SolydFlow may therefore remain:
Pending
Later, the webhook may also fail:
Webhook
X
The result is:
Provider → Successful
SolydFlow → Pending
A mismatch now exists.
Detecting a Mismatch
A mismatch can be identified when SolydFlow receives information that conflicts with its current transaction state.
For example:
Current State
└── Pending
New Evidence
└── Successful
The system can identify:
Pending ≠ Successful
This should trigger the appropriate resolution process.
Mismatch Detection Does Not Immediately Change the State
Detecting a mismatch and resolving it are separate steps.
Mismatch Detected
↓
Evaluate Evidence
↓
Verify if Necessary
↓
Resolve
↓
Update Transaction
This prevents the system from changing transaction state based on incomplete or untrusted information.
Evidence Used to Resolve Mismatches
The Truth layer can use available transaction evidence such as:
Provider Response
│
Webhook
│
Verification
│
Recovery
↓
Mismatch Resolution
The available evidence depends on the provider and transaction.
Verification as a Resolution Tool
When the available information is insufficient, SolydFlow can verify the transaction with the provider where supported.
For example:
SolydFlow
└── Pending
Provider Verification
└── Successful
The evidence can then be used to resolve the mismatch:
Pending
↓
Verification
↓
Successful
See:
Consensus and State Mismatches
When multiple signals exist, the consensus engine helps evaluate them.
For example:
Webhook
└── Successful
Verification
└── Successful
Current State
└── Pending
The evidence is consistent:
Successful
Successful
↓
Consensus
↓
Successful
The transaction can then be resolved.
See:
Missing Webhooks
A missing webhook is one of the most common causes of a provider/SolydFlow mismatch.
Provider
└── Successful
Webhook
└── Missing
SolydFlow may still show:
Pending
Recovery can detect that the transaction has remained unresolved and trigger verification.
Pending
↓
Webhook Missing
↓
Recovery
↓
Verification
↓
Successful
See:
Delayed Webhooks
A webhook may eventually arrive after the transaction has already been resolved through another mechanism.
For example:
Payment
↓
Pending
↓
Verification
↓
Successful
Later:
Webhook
└── Successful
The webhook should not create another payment or another transaction.
It should be processed against the already-resolved transaction.
This is where idempotent event handling becomes important.
See:
Duplicate Webhooks
A provider may send the same webhook multiple times:
Webhook A
Webhook A
Webhook A
This should not produce:
Payment
Payment
Payment
Instead, all deliveries should refer to the same underlying transaction/event.
One Transaction
↑
Webhook A
Webhook A
Webhook A
See:
Out-of-Order Events
Events may arrive in a different order from the order in which they were generated.
For example:
Generated:
A → B → C
Received:
B → A → C
The system should not automatically assume that the last received event represents the latest transaction state.
Instead, the event's meaning, timestamp, transaction identity, and existing transaction history should be considered.
Timeout-Generated Mismatches
A payment request can time out even though the provider successfully processes the transaction.
Application
↓
Payment Request
↓
Provider
↓
Successful
Application
X
Response Timeout
The application may interpret the timeout as:
Unknown
while the provider has:
Successful
Verification can resolve the uncertainty without creating another payment.
See:
Zombie Transactions
A transaction that remains pending longer than expected can become a candidate for investigation.
Pending
↓
No Expected Progress
↓
Zombie Candidate
Recovery can then attempt to establish its actual state.
Zombie Transaction
↓
Verification
↓
Successful / Failed / Still Pending
See:
Resolving a State Mismatch
A simplified resolution workflow is:
Mismatch Detected
↓
Identify Transaction
↓
Collect Evidence
↓
Validate Evidence
↓
Compare States
↓
Verify if Necessary
↓
Evaluate Evidence
↓
Resolve Transaction State
↓
Record Resolution
Step 1: Identify the Transaction
Before resolving the mismatch, SolydFlow needs to establish exactly which transaction is affected.
Provider Reference
↓
SolydFlow Transaction
↓
Matching Transaction
This prevents one transaction's information from being applied to another.
Step 2: Collect Evidence
Gather the available information:
Provider Response
Webhook
Verification
Recovery
Transaction History
↓
Evidence
The evidence should be associated with the correct transaction.
Step 3: Validate Evidence
Before using external events, validate them appropriately.
For webhooks:
Webhook
↓
Signature Verification
↓
Valid
For provider verification:
Provider Response
↓
Transaction Identity
↓
Validated
See:
Step 4: Compare States
The system compares the current state with the new evidence.
Current
└── Pending
Evidence
└── Successful
This establishes the mismatch.
Step 5: Verify When Necessary
If the available evidence is insufficient or conflicting:
Mismatch
↓
Verification
↓
Provider State
Verification provides additional evidence for the resolution process.
Step 6: Evaluate the Evidence
The evidence is evaluated according to the transaction context.
Evidence
↓
Consensus
↓
Resolved State
See:
Step 7: Resolve the Transaction
Suppose:
Current State → Pending
Verification → Successful
The transaction can be resolved:
Pending
↓
Successful
The state change should be recorded.
Step 8: Record the Resolution
The ledger should preserve the resolution:
Pending
↓
Verification
↓
Successful
This provides traceability for future investigation.
See:
What Happens When a Mismatch Cannot Be Resolved?
Not every mismatch can be immediately resolved.
For example:
Provider
└── Unavailable
Webhook
└── Missing
Verification
└── Failed to Complete
There may not be enough evidence to establish a final state.
In that situation, SolydFlow should preserve the uncertainty:
Insufficient Evidence
↓
Remain Unresolved
↓
Recovery / Retry
A temporary inability to verify should not automatically become:
Failed
Mismatch Resolution and Retries
If verification fails because of a temporary provider or network problem, verification may be retried.
Verification
↓
Temporary Failure
↓
Retry
↓
Verification
This should not be confused with retrying the original payment.
See:
Mismatch Resolution and Duplicate Payments
State mismatch handling is especially important when the original payment outcome is uncertain.
For example:
Payment
↓
Timeout
↓
Unknown
Creating another payment immediately could result in a duplicate charge.
Instead:
Unknown
↓
Verify Existing Transaction
↓
Resolve State
Only after the original transaction is appropriately resolved should the application determine whether another payment attempt is actually necessary.
Mismatch Resolution and Entitlements
A mismatch can affect whether an entitlement is granted.
For example:
Provider
└── Successful
SolydFlow
└── Pending
Entitlement
└── Not Granted
After verification:
Successful
↓
Transaction Resolved
↓
Entitlement
This helps prevent customers from being incorrectly denied access after a successful payment.
See:
Mismatch Resolution and Revenue
A mismatch can also affect revenue reporting.
For example:
Provider
└── Successful
Revenue Record
└── Missing
The transaction ledger and reconciliation processes can help identify and resolve the difference.
Transaction
↓
Truth
↓
Ledger
↓
Reconciliation
↓
Revenue Record
See:
State Mismatches and Reconciliation
State mismatch resolution and reconciliation are closely related.
A mismatch may first be detected as:
Provider
└── Successful
SolydFlow
└── Pending
Reconciliation can identify the difference:
Compare Records
↓
Difference Detected
Truth can then help determine the appropriate state:
Difference
↓
Verification / Consensus
↓
Resolved State
See:
Example: Missing Webhook Resolved
Initial state:
Provider → Successful
SolydFlow → Pending
Detection:
Webhook Missing
Recovery:
Recovery
↓
Verification
Verification:
Provider → Successful
Resolution:
Pending
↓
Successful
Ledger:
Pending
↓
Recovery
↓
Verification
↓
Successful
Example: Temporary Provider Failure
Initial state:
SolydFlow → Pending
Verification:
Provider → Unavailable
The system should not conclude:
Failed
Instead:
Pending
↓
Verification Unavailable
↓
Retry / Recovery
Later:
Provider → Successful
The transaction can then be resolved.
Example: Conflicting Evidence
Suppose:
Webhook → Successful
Verification → Failed
The system should flag the conflict:
Conflicting Evidence
Then:
Evaluate
↓
Additional Evidence
↓
Resolution
The final state should only be established when the available evidence supports it.
Preventing State Mismatches
Not all mismatches can be prevented, but SolydFlow can reduce their impact through reliable transaction processing.
Important mechanisms include:
- Idempotent event handling
- Webhook verification
- Transaction verification
- Recovery workflows
- Transaction history
- Provider-specific integrations
- Reconciliation
- Clear transaction state transitions
Together:
Reliable Events
+
Verification
+
Recovery
+
Truth
↓
Consistent Transaction State
The Mismatch Resolution Model
The overall model is:
Different States
↓
Detect Mismatch
↓
Collect Evidence
↓
Validate
↓
Verify if Needed
↓
Consensus
↓
Resolve
↓
Ledger
↓
Reliable State
This keeps transaction resolution inside the revenue infrastructure rather than forcing each application to implement its own reconciliation logic.
Key Principles
1. A mismatch is not automatically a failure
Different states indicate disagreement, not necessarily payment failure.
2. Detect before resolving
The system should identify the mismatch before changing the transaction state.
3. Verify uncertain transactions
When appropriate, verify the existing transaction instead of creating another payment.
4. Do not manufacture certainty
If there is insufficient evidence, preserve the unresolved state.
5. Record the resolution
State changes should remain traceable in the transaction ledger.
6. Handle duplicate and delayed events
Webhook delivery behavior should not create duplicate transactions or incorrect state changes.
7. Keep reconciliation and Truth connected
Reconciliation identifies differences; Truth helps establish the reliable transaction state.
The Core Principle
A state mismatch means the systems disagree. Truth exists to determine why they disagree and, when sufficient evidence exists, establish the state the system can rely on.
The workflow is:
Mismatch
↓
Evidence
↓
Verification
↓
Consensus
↓
Resolution
↓
Ledger