Sandbox Triggers

The sandbox trigger command lets you simulate payment and payout lifecycle events in sandbox mode — useful for testing your webhook handlers without waiting for real provider callbacks.

Available Triggers

Trigger Name	Description	Required Flag
payment_succeeded	Simulate a successful payment callback	--payment-intent
payment_failed	Simulate a failed payment callback	--payment-intent
payout_paid	Simulate a successful payout callback	--payout
payout_failed	Simulate a failed payout callback	--payout

Usage

Simulate a successful payment

# 1. Create a payment
ikw payments create --amount 5000 --currency XOF --json
# → { "id": "pi_abc123", ... }

# 2. Trigger the success callback
ikw sandbox trigger payment_succeeded --payment-intent pi_abc123
# → ok

Simulate a failed payment

ikw sandbox trigger payment_failed \
  --payment-intent pi_abc123 \
  --failure-reason insufficient_funds

Simulate a successful payout

ikw sandbox trigger payout_paid --payout po_xyz789

Simulate a failed payout

ikw sandbox trigger payout_failed \
  --payout po_xyz789 \
  --failure-code provider_error \
  --failure-message "Recipient wallet not found"

Options

Flag	Description
--payment-intent <id>	Payment intent public ID (pi_...)
--payout <id>	Payout public ID (po_...)
--failure-reason <text>	Reason for payment failure
--failure-code <code>	Code for payout failure
--failure-message <text>	Message for payout failure

Typical Workflow

Combine sandbox triggers with the webhook listener for a complete local testing loop:

# Terminal 1: Listen for webhooks
ikw webhooks listen --port 4242

# Terminal 2: Create and trigger events
ikw payments create --amount 5000 --currency XOF --json > /tmp/pi.json
PI_ID=$(cat /tmp/pi.json | jq -r '.id')

ikw sandbox trigger payment_succeeded --payment-intent $PI_ID
# → Terminal 1 shows the payment_intent.succeeded webhook event

tip

Sandbox triggers bypass the real payment provider flow. They directly simulate the callback that would normally come from Orange Money, MTN MoMo, etc.