SwapSS learn

Crypto payment idempotency

Crypto payments mix customer actions, chain confirmations, merchant systems, and webhook retries. Idempotency is what keeps a retry from creating a second invoice, shipping a second order, or crediting a customer twice.

Use keys at creation time

When a merchant creates an invoice, a stable idempotency key lets the API return the same invoice for the same intended operation instead of creating duplicates after a network retry.

Keep fulfillment separate from delivery

A webhook delivery can happen more than once. Fulfillment should check the current invoice status, the stored event ID, and the merchant order record before unlocking an order or crediting an account.

Apply the same rule to refunds and payouts

Refunds, payouts, and settlement exports need deterministic references too. A support retry must not produce a second outgoing payment because the first response was delayed.

What to document for developers

Public docs should define the idempotency header, retention window, duplicate response shape, and error behavior. Developers should not need to guess how the gateway behaves during retry storms.