Idempotency, callbacks and double-shipping

Three places that must be idempotent

1. Create order: derive an idempotency key from order number + line number; duplicate submits return the same result.
2. Payment callback: check the current order status first; anything not pending returns success immediately.
3. Upstream callback: locate the local order by upstream id; duplicate pushes overwrite but never ship twice.

Always poll in addition to callbacks

Webhooks get dropped, blocked by firewalls, or missed when your service restarts. In-flight orders need a scheduled polling fallback.

When in doubt, don't touch it

When the upstream reports failure, don't flip the order straight to "failed" — mark it pending-review and leave it for a human or the next poll.