Collections (repayments, deposits, and charges) can sometimes become stuck when the payment provider's response is
ambiguous. This happens when the system cannot determine whether the customer actually paid or not.
When Collections Get Stuck
A collection becomes stuck in these situations:
- Payment Provider Timeout - The payment request timed out before receiving confirmation
- Provider Server Error - The provider returned an error that leaves payment status unclear
- Recording Failed - Payment was confirmed received but failed to record in Microbanking (CRITICAL)
- Unknown Error - An unexpected error occurred with ambiguous state
Before Resolving
Before resolving a stuck collection, you must manually verify the payment status:
Log in to Symba Portal with a user account that is
authorized to resolve stuck transactions.
Check the payment provider's dashboard or API to confirm whether the payment was actually received:
- MTN MoMo: Check the MoMo portal for transaction status
- Safaricom Daraja: Check the M-PESA portal for payment confirmation
- Cash: Verify with the staff member who collected the payment
Verify the account balance in Symba Microbanking:
- For repayments: Check the loan account balance
- For deposits: Check the savings account balance
- For charges: Check the client's charge status
Resolution Actions
Once you've verified the payment status, choose the appropriate action:
Mark as Succeeded
Use this action when you've confirmed that:
- The payment provider shows the payment was received
- The customer has paid the amount
What happens:
- The system attempts to record the payment in Microbanking
- If successful, the transaction is marked as "succeeded"
- If recording fails again, the transaction stays "stuck" with a CRITICAL alert
When this is appropriate:
- Provider dashboard shows payment completed
- Customer confirms they paid
- Money is visible in provider account
Mark as Failed
Use this action when you've confirmed that:
- The payment provider shows the payment was NOT received
- The customer did NOT pay
- Payment was declined or cancelled
What happens:
- The transaction is marked as "failed"
- No attempt to record in Microbanking (nothing to record)
- Transaction is considered complete
When this is appropriate:
- Provider dashboard shows no payment received
- Customer confirms they did not complete payment
- Payment was explicitly declined or cancelled
Steps to Resolve
Navigate to the appropriate collection list:
Find the stuck transaction in the list (status shows "stuck")
Select the checkbox next to the stuck transaction
Click the Resolve Stuck button in the action bar
Review the resolution dialog:
- Read the warning about verifying provider status first
- Confirm you've checked the provider dashboard
- Understand the consequences of each action
Choose your action:
- Click Mark as Succeeded if payment was received
- Click Mark as Failed if payment was NOT received
- Click Cancel to abort without changes
Wait for confirmation:
- Success message appears if resolution completed
- Error message appears if resolution failed
- Transaction updates to new status ("succeeded" or "failed")
CRITICAL Alert Scenario
If you see a stuck transaction with a status message starting with "CRITICAL":
CRITICAL: Payment received but failed to record in Microbanking
This is the most serious stuck state. It means:
- The payment provider confirmed payment was received
- The customer's money was debited
- Microbanking failed to credit the account
Resolution steps:
- Verify in provider dashboard that payment was definitely received
- Check Microbanking to confirm the transaction is NOT recorded
- Choose "Mark as Succeeded" to retry recording in Microbanking
- If retry fails, manual database intervention is required:
- Contact Symba Global Support
- Provide transaction UUID and details
- Support will manually record the transaction in database
Do NOT mark as failed in CRITICAL scenarios - the customer already paid and must be credited.
Understanding Collection vs Disbursement Resolution
Collections work differently than disbursements:
| Aspect |
Collections (Incoming Money) |
Disbursements (Outgoing Money) |
| Provider-First |
Request payment FIRST, record AFTER |
Record in MB FIRST, transfer AFTER |
| Mark Succeeded |
Attempts to record in Microbanking |
No action (already recorded) |
| Mark Failed |
No action (nothing to record) |
Attempts rollback in Microbanking |
| Cannot Rollback |
You can't undo received payments |
Can undo recorded transactions |
| CRITICAL Alert |
Payment received but not recorded |
Rollback failed after transfer |
Common Mistakes to Avoid
❌ Don't mark as succeeded without checking provider dashboard
- This could create a duplicate payment if you retry a failed payment
❌ Don't mark as failed if payment was actually received
- This would lose the customer's money - they paid but won't be credited
❌ Don't ignore CRITICAL stuck states
- These indicate customer money was received but not credited - must be resolved
❌ Don't try to resolve multiple stuck transactions at once
- Select exactly one transaction to resolve at a time
✅ Do verify provider status before choosing action
- This is the most important step - prevents wrong resolution
✅ Do check Microbanking balance to confirm current state
- Helps verify whether payment was already recorded
✅ Do contact support for CRITICAL alerts that won't resolve
- Manual database intervention may be needed
Troubleshooting
"Please select exactly one stuck transaction to resolve"
You can only resolve one stuck transaction at a time. Make sure:
- You've selected exactly one checkbox
- The selected transaction has status "stuck"
- You're not trying to resolve multiple transactions
Mark as Succeeded fails again
If you choose "Mark as Succeeded" and it fails again:
- The transaction remains stuck
- Check Microbanking API connectivity
- Verify the loan/savings/charge still exists
- Contact Symba Global Support if issue persists
Don't see Resolve Stuck button
The resolve button only appears when:
- You have the appropriate authorization
- You've selected exactly one transaction
- The selected transaction has status "stuck"
Related Topics