Idempotency-Key

What Idempotency-Key is

Idempotency-Key is a header that helps safely retry invoice creation requests.

If the merchant backend sent a request but did not receive a response because of timeout, network error or connection failure, it can repeat the same request with the same Idempotency-Key.

In this case, Weelay returns the already created invoice instead of creating a duplicate.

Why it is needed

Without duplicate protection, the same operation may create multiple invoices for one order.

This is bad for the merchant and the buyer:

• the buyer may see several payment links;
• the order may receive several different invoices;
• support cases become harder to review;
• the merchant backend may save the wrong invoice.

Idempotency-Key reduces this risk.

Where it is used

At the current stage, Idempotency-Key is used when creating an invoice:

POST /merchant/invoices

Header:

Idempotency-Key: order-1001

How to choose a key

It is best to use a stable key connected with a specific invoice creation operation.

Good options:

• merchant order id;
• order number with prefix;
• unique payment attempt id;
• UUID saved by the merchant before sending the request.

Examples:

• order-1001;
• shop-42-order-1001;
• invoice-create-550e8400-e29b-41d4-a716-446655440000.

Main rule

One Idempotency-Key should correspond to one invoice creation operation.

Do not use the same key for different orders.

Do not change the key when retrying the same request after timeout.

Correct scenario

The correct order is:

1. The merchant creates an order in their system.
2. The merchant generates or selects Idempotency-Key.
3. The merchant saves this key.
4. The merchant sends POST /merchant/invoices.
5. If the response is received, the merchant saves invoice id and payment_url.
6. If no response was received because of a failure, the merchant repeats the request with the same Idempotency-Key.

This way, the repeated request safely returns the already created invoice.

Incorrect scenario

It is incorrect to generate a new Idempotency-Key for every retry of the same invoice creation.

In that case, Weelay treats the request as a new operation and may create a new invoice.

It is also incorrect to use one shared key for all orders, such as payment, invoice or test.

Such a key does not show which order the operation belongs to.

What a repeated request returns

If an invoice was already created with this Idempotency-Key, a repeated request returns the existing invoice.

The merchant should save the received data the same way as after a normal successful creation.

Main fields to save:

• id;
• order_id;
• status;
• payment_url;
• payment_expires_at.

Relation to order_id

order_id and Idempotency-Key solve different tasks.

order_id helps the merchant connect an invoice with an order.

Idempotency-Key helps Weelay understand that a repeated request belongs to the same invoice creation operation.

In practice, the same value may be used, for example ORDER-1001, but the meaning of the fields is different.

Can Idempotency-Key be skipped

Technically, invoice creation can work without Idempotency-Key.

But for production integration, it is better to use it always.

This is especially important if the merchant backend automatically retries requests after timeout or network error.

What to do after network error

If the merchant backend sent an invoice creation request and did not receive a response, do not immediately create a new order or a new key.

It is better to repeat the same request with the same Idempotency-Key.

If the repeated request succeeds, use the returned invoice.

What to do after validation error

If API returned VALIDATION_ERROR, first fix the request data.

If it is still the same invoice creation operation for the same order, the same Idempotency-Key may be kept.

If the merchant creates a new separate payment attempt, use a new key.

Security

Idempotency-Key is not a secret key.

But it still should not be meaningless or shared by all orders.

A good key should be unique for the operation and convenient to find in merchant logs.

Recommendations

For production:

• use Idempotency-Key for every invoice creation;
• save the key before sending the request;
• retry with the same key after timeout;
• do not use one key for different orders;
• do not generate a new key when retrying the same operation;
• save invoice id and payment_url after successful response.

Summary

Idempotency-Key protects invoice creation from duplicates.

One order or one invoice creation operation — one stable key.

When retrying after failure, use the same key.