Skip to main content

Idempotency

Idempotency keeps the same operation from being processed more than once when a request has to be sent again.

In practice, it means you can repeat a creation call with the same idempotencyKey without creating a duplicate operation.

What it is for​

Use idempotency whenever there is a chance the same request is sent again for a technical reason, such as:

  • a response timeout
  • a momentary network failure
  • an automatic retry by the HTTP client
  • a manual resend of the same call

This behavior is especially important for financial operations, because it prevents the integrator from creating two transactions, two deposits or two withdrawals by accident.

How to use it​

The recommended flow is simple:

  1. generate a unique idempotencyKey for the operation
  2. send that key along with the creation request
  3. if the same operation has to be sent again, reuse the same key
  4. if it is a new operation, generate a new key
Rule of thumb

If the business intent is the same, reuse the same idempotencyKey. If the intent changed, create a new key.

What the platform does​

From the integrator's point of view, the platform recognizes that the same key represents the same operation within the same integration context.

That way a retry does not accidentally become a new operation.

If the first attempt is still being processed, the second call may wait for the result of the original operation before responding.

How long the key is valid​

The platform keeps the result of the operation associated with the idempotencyKey for 1 hour from the first time it was sent.

ℹ️ Idempotency window

Within that window, resending the same idempotencyKey returns the result of the original operation, without creating a new one.

After 1 hour the key expires: a resend with the same idempotencyKey is no longer recognized as a retry and may generate a new operation.

If your retry flow can take longer than that, make sure the resend happens within that window.

idempotencyKey vs externalCode​

These two fields have different roles:

  • idempotencyKey: identifies a single operation attempt and protects against technical duplication
  • externalCode: your business reference for locating the operation in your own system

They can be used together, but one does not replace the other.

When to generate a new key​

Generate a new idempotencyKey when:

  • the order changed
  • the amount changed
  • the recipient changed
  • it is a different operation, even if it looks similar

Do not reuse the same key for different intents.

Practical example​

First attempt​

{
  "amount": 500,
  "paymentMethod": "PIX",
  "externalCode": "PEDIDO-123",
  "idempotencyKey": "b7f9c2d8-8f59-4a55-8c3c-8a6a4f9d1f2d"
}

Retry of the same operation​

If the previous call gave no clear answer, resend the same payload with the same idempotencyKey and the platform treats it as the same operation.

{
  "amount": 500,
  "paymentMethod": "PIX",
  "externalCode": "PEDIDO-123",
  "idempotencyKey": "b7f9c2d8-8f59-4a55-8c3c-8a6a4f9d1f2d"
}

Good practices​

  • use the idempotencyKey on creation POST requests
  • keep the same key while you are still trying to complete the same operation
  • generate a new key for each new business intent
  • do not use the key as a replacement for externalCode
  • treat timeouts and retries from your client as expected scenarios

Where this applies​

In our API, this concept applies mainly to the creation endpoints:

In short​

Idempotency is what lets you re-run the same operation without creating a duplicate.

For the integrator, the main rule is:

  • same operation, same idempotencyKey
  • new operation, new idempotencyKey