PisoWiFi E-Wallet Reconciliation When Webhooks Retry
Tech GuruQuick Answer
Treat a webhook as a payment event to verify and reconcile, not as permission to add time repeatedly. Keep provider payment identity, received events and applied portal credit linked but distinct. Duplicate, delayed or concurrent delivery must not duplicate the same credit. Resolve ambiguous status through the provider's supported lookup and an exception queue. After a restart or rollback, preserve newer transactions and reconcile balances instead of restoring a stale ledger blindly.
Evidence status: Maya's webhook documentation was checked for HTTPS, payload/status, duplicate handling, source-IP guidance and registration. No payment, webhook replay, ledger transaction, concurrent worker or portal recovery test was performed. The ledger design below is a proposed acceptance model, not a certified payment integration.
What To Check
The Maya guide documents JSON POST notifications, a prompt 2xx response and duplicate delivery. It recommends environment-specific source-IP restrictions. It does not establish a universal HMAC signature scheme for this article; use the controls documented for the actual provider/product.
Receiving an event and delivering paid time are separate state changes. Keep enough durable information to retry a failed credit without charging or crediting the customer twice. A success page, customer screenshot or webhook-shaped request alone is not authoritative payment proof.
Key Concepts In Plain Language
- Payment identity: the provider's payment identifier within the correct merchant and environment.
- Idempotent credit: repeating the same authorized credit request does not add the entitlement twice.
- Exception queue: unresolved payment/credit mismatches with an owner and auditable resolution, not silently assumed success.
Technical Checklist
- Key payment records by provider, merchant/environment and payment ID; retain event history and uniquely identified entitlement actions.
- Verify ambiguous state through the applicable provider status API and track unresolved cases with ownership.
- Test duplicates, concurrent delivery, timeouts, late success, refunds, partial credit failure, portal restart and operator retry.
- Reconcile wallet, voucher, coin, credited time, refunds and exceptions daily with an auditable adjustment history.
Interactive Operating Model
Use the planned checks below with this overview. No test result is implied by the diagram.
Before You Start: Safe Defaults
Use provider-approved sandbox transactions and synthetic customers. Restrict credentials, webhook logs and personal data. Back up portal and ledger state with a recovery plan that retains events newer than the backup. Identify who can authorize refunds or manual adjustments.
- Back up router, portal, voucher, payment, and session records before changing authentication or routing.
- Keep portal, DNS, payment, and management destinations reachable through the intended main path.
- Use test accounts and low-value test transactions with the payment provider's documented environment or process.
- Define a customer-credit, refund, and exception procedure before intentionally testing retries or link failure.
Go, Hold, Recover, Or Escalate
Credit only a verified qualifying payment according to the integration's rules. Hold ambiguous, mismatched-merchant or unexpected-amount events for investigation. Do not repeatedly grant time because a customer retries, and do not erase paid-but-uncredited cases when a queue is restarted.
Planned Checks And Recovery
For Maya, review Maya Business Manager > Settings > Webhooks for the intended merchant and environment. Preserve plugin-managed URLs through the plugin workflow. The same page warns that its dashboard test tool may fail while under maintenance; a saved URL or successful reachability response is not proof that credit processing works.
Step 1: Define the payment-to-credit record
Record merchant/environment, provider payment ID, expected order/amount/currency, verified status and the entitlement action. Keep refunds and adjustments as separate recorded actions rather than overwriting the original sale. Confirm the actual status API and credentials with the provider documentation.
Step 2: Make acceptance durable
As a design requirement, validate the incoming event and durably accept it before acknowledging work that must survive a crash. Keep complex credit processing out of the request timeout path. Enforce uniqueness and atomic state transitions at the ledger boundary so two workers cannot both grant the same credit.
Step 3: Retry without duplicating entitlement
Link each credit attempt to the same durable action. If the portal and ledger cannot commit together, use a retryable handoff whose receiver can recognize the same action; do not mark delivery complete before confirmation. Route uncertain provider or portal outcomes to reconciliation.
Step 4: Exercise failure and daily reconciliation
Replay the same sandbox event concurrently, delay a success, interrupt processing at the ledger/portal boundary and retry after restart. Compare provider, ledger, entitlement and refund records. Reconcile daily and after recovery, retaining an explanation for each manual adjustment.
Validation Checklist
- Repeated and concurrent event delivery produces one intended credit, with repeated receipts still auditable.
- A crash before or after credit delivery can be resolved without losing the payment or duplicating time.
- Merchant, amount, status and environment mismatches are not automatically credited.
- Daily and post-restore reconciliation account for refunds, manual adjustments and newer transactions.
Troubleshooting
- Customer paid but received no time: Compare provider status, durable action and portal receipt before issuing another credit.
- A duplicate creates extra time: Check database uniqueness and the portal's action identity under concurrent workers, not only an in-memory flag.
- HTTP 200 but credit is missing: Distinguish endpoint receipt from worker completion; inspect durable queued work and exceptions.
Security, Privacy, Legal, And Recovery Boundaries
Security
Protect portal administration, payment secrets, router management, voucher generation, and session APIs with least privilege and auditable access.
Privacy
MAC addresses, phone identifiers, payment references, and connection history can identify customers; minimize collection and set a retention policy.
Legal
Comply with payment-provider terms, consumer-protection duties, tax and record requirements, and applicable privacy law; never test against another operator.
Recovery
Keep exportable transaction and voucher records, a router rollback, a manual credit path, and an exception queue that survives portal or webhook downtime.
Record any local exception, its owner, its expiration condition, and the evidence required to remove it.
What The Evidence Does Not Prove
The proposed atomic/idempotent design requires implementation and failure testing in the selected database and portal. No exact provider status endpoint or signature algorithm is assumed across products. The retained BSP bulletin is background context, not proof of this integration's correctness or compliance.
Related TechGeeks Resources
- PisoWiFi Operations Notes: Start Here
- Networking Field Notes: Start Here
- 15 Router Security Settings to Audit Before Something Breaks
References
Next Action
Trace one sandbox payment through receipt, one credit, a duplicate and a restart. Reconcile the records before accepting real customer money through the revised flow.
