Idempotent fulfillment means repeated payment notifications produce one business result. Coinvay protects its own settlement records, but your store must independently prevent repeated stock changes, license issuance, account credits or access grants.
Separate payment from delivery
Model payment verification and product delivery as different steps. A verified invoice can exist while a delivery worker is temporarily unavailable. Keep a durable order row, a payment identity and an outbox job rather than using a single browser session to complete everything. This structure lets your system retry an email or API call without requesting another customer payment.
Use database uniqueness, not a memory flag
For example, an order for a downloadable template should have one unique fulfillment key derived from its internal order ID. In one transaction, verify the saved invoice mapping and total, insert the confirmed payment if absent, and create the outbox job if absent. A unique database constraint handles two simultaneous workers more reliably than checking a JavaScript variable. Webhook delivery and status polling may discover the same payment at nearly the same time.
Recover from uncertain downstream results
A worker may send an access-grant request successfully and then crash before recording completion. Prefer a downstream API with an idempotency key, or query whether the exact entitlement already exists before retrying. Keep the customer, product and site identifiers from your trusted order record. Do not blindly issue another credit because the webhook arrived again. Expose a review queue for mismatched prices, changed orders and delivery errors so staff can repair the business outcome without rewriting blockchain history.
Practical checklist
- Create a unique fulfillment identity that belongs to the order, not the webhook attempt.
- Commit payment acceptance and outbox creation atomically in your database.
- Simulate a crash after downstream success and confirm that recovery does not deliver twice.
Common questions
Does invoice idempotency solve fulfillment retries?+
No. An Idempotency-Key prevents duplicate invoice creation for one intended request. Your own fulfillment database and downstream services need separate duplicate protection.
Should I return an error for every duplicate webhook?+
A recognized, already-processed valid event can normally be acknowledged successfully. Keep invalid signatures and inconsistent order evidence distinct from harmless repeats.
Sources and further reading
Primary references and Coinvay product documentation. Check the linked pages for current details.
AI-assisted drafting, published by Coinvay. Examples are illustrative. Read our editorial approach.