Simulate Transaction Event

The Simulate Transaction Event endpoint on Payiano allows developers to manually trigger payout lifecycle events for testing purposes in non-production environments. This simulation system enables you to test the full payout flow end-to-end without moving real funds or impacting live transactions.

You can simulate any lifecycle stage including initiating, validating, processing, settling, success, or failed. When a later stage is simulated, all preceding events in the payout timeline are automatically completed to preserve correct sequencing. Failed simulations require a reason, enabling full testing of error-handling logic.

All simulated events behave exactly like real events: they update the transaction timeline, trigger associated payout workflows, and dispatch webhooks making this endpoint ideal for integration, validation, and regression testing.

This tool helps development teams test UI flows, verify webhook handlers, simulate edge cases, and build robust payout integrations before going live without relying on external banking systems or real settlement operations.

Important: This endpoint is automatically disabled in production environments and cannot be used to simulate events on live transactions.

⚠️ Important Notes About Event Simulation:

Simulation Validation Rules

The endpoint performs immediate validation before queueing any event:

• Sequence validation: You cannot simulate an earlier event after a later one has already been processed. For example, if processing is already completed, you cannot simulate validating.
• Duplicate prevention: If an event is already completed, attempting to simulate it again will return an immediate error.
• Event dependency check: The system verifies all required preceding events exist and are properly sequenced.

Race Condition Handling

When multiple simulation requests arrive simultaneously:

• First request validation: The initial request passes all validations and is queued for processing.
• Subsequent requests: If a second request arrives while the first is still queued (not yet processed), it will pass initial validation but will be silently discarded during queue processing.
• Post-processing behavior: After the first simulation completes, any identical subsequent requests will fail validation immediately with a clear error message.
• Idempotent design: This approach ensures safe retries while preventing duplicate event processing and webhook spam.

Event Chain Reactions

A single simulated event may trigger multiple internal events:

• Cascade effects: Simulating settling automatically triggers completion of initiating, validating, and processing events in the correct sequence.
• Webhook bursts: Each triggered event (including auto-completed ones) fires its own webhooks, which may result in multiple webhook deliveries from a single simulation request.
• Current event updates: The transaction's current_event field is updated with the latest event details as each event completes.
• Status updates for final events: When simulating success or failed events, the transaction's status field is updated to success or failed respectively. Intermediate events (initiating, validating, processing, settling) do not change the transaction status.

Transaction Status Updates

Transaction status behavior during simulation:

• Final events update status:
  • Simulating success event → Transaction status becomes success
  • Simulating failed event → Transaction status becomes failed
• Intermediate events keep current status:
  • Simulating initiating, validating, processing, or settling → Transaction status remains unchanged (typically pending)
• Current Event vs Status:
  • current_event: Always updated with the latest simulated event, showing the current step in the payout lifecycle
  • status: Only updated when reaching terminal states (success/failed), representing the final outcome of the transaction
• Example flow:
  1. Transaction created with status: pending
  2. Simulate validating → current_event updates, status remains pending
  3. Simulate processing → current_event updates, status remains pending
  4. Simulate failed → current_event updates to failed, status updates to failed

Error Response Behavior

The endpoint provides clear error feedback in these scenarios:

• Already completed events: Returns a 400 error with a message indicating the event has already been processed.
• Invalid sequence: Returns a 400 error explaining why the requested event sequence is invalid.
• Only silent discard during processing: Duplicate detection during actual processing happens silently to prevent webhook spam, but initial validation catches most error cases.

Best Practices for Simulation Testing

• Check event status first: Use the transaction events endpoint to see current transaction events before simulating new events.
• Monitor both fields: Track current_event for progress through the lifecycle and status for final outcome.
• Follow natural progression: Simulate events in their natural order: initiating → validating → processing → settling → success/failed.
• Wait for completion: After triggering an event, wait for all webhooks to arrive before simulating the next event.
• Handle errors gracefully: The API provides clear error messages for invalid requests - use them to adjust your simulation flow.
• Expect immediate feedback: Most validation errors are returned immediately, not during async processing.

Verifying Simulation Results

• Monitor webhooks: Listen for webhook notifications to confirm event processing.
• Check transaction events: Use the transaction events listing endpoint to verify the updated timeline.
• Review current_event field: The transaction's current_event field will update with each simulated event.
• Check status for final events: After simulating success or failed, verify the transaction status field has updated accordingly.
• Allow processing time: While validation is immediate, actual event processing and webhook delivery may take a few moments.