Idempotency

Cryptonly supports idempotent creation of invoices, deposits, and withdrawals.

Idempotency is implemented through the orderId field, which acts as the idempotency key when creating:

• invoices
• standalone deposits
• withdrawal quotes

Overview

When creating an invoice, deposit, or withdrawal quote, the merchant can provide an orderId value.

If the same request is sent more than once with the same orderId, Cryptonly treats it as the same logical operation and prevents duplicate object creation.

This is useful when:

• a client retries a request after a timeout
• the network connection is unstable
• the merchant wants to safely repeat a create request without creating duplicates

---

Supported Operations

The orderId field is used for idempotency on:

• invoice creation (POST /invoice)
• standalone deposit creation (POST /deposit)
• withdrawal quote (POST /withdrawal/quote)

For withdrawals, idempotency applies at the quote step. The same (accountId, orderId) pair collapses to a single quote. Commit (POST /withdrawal/commit) reuses that quote and can back at most one committed withdrawal per (accountId, orderId).

It is not intended as a general-purpose idempotency mechanism for unrelated endpoints.

---

How It Works

When a create request is received, Cryptonly checks the provided orderId.

• If the orderId has not been used before for that operation, a new object is created.
• If the same orderId is sent again, Cryptonly treats the request as a retry of the original operation.

This allows merchants to safely retry create requests without accidentally creating duplicate invoices, deposits, or withdrawal quotes.

Best Practices

Use a unique orderId per logical operation

Use a different orderId for each new invoice, deposit, or withdrawal you want to create.

Reuse the same orderId only for retries

If you are retrying the same request because of a timeout or temporary failure, reuse the same orderId.

Generate orderId on your side

The orderId should come from your system and represent your own business object, such as:

• order number
• payment attempt ID
• withdrawal request ID

Do not use random values for retries

If a retried request uses a new orderId, Cryptonly will treat it as a new create request rather than a retry.

---

Recommended Usage Pattern

A typical safe flow looks like this:

1. Generate a merchant-side orderId
2. Send the create request with that orderId
3. If the request times out or the response is uncertain, retry with the same orderId
4. Treat the returned object as the result of the original operation

For withdrawals, repeat the same orderId on quote retries, then commit once you have a quoteId.

This ensures that retries do not create duplicates.

---

Notes

• orderId acts as the idempotency key for invoice creation, deposit creation, and withdrawal quote
• The same orderId should be reused only when retrying the same logical operation
• A new logical operation must use a new orderId

---

Short Summary

Cryptonly uses the orderId field as the idempotency key for invoice creation, deposit creation, and withdrawal quote.

This means you can safely retry those create requests with the same orderId without creating duplicates.