Idempotency
The API supports idempotency for safely retrying requests without accidentally performing the same operation more than once. This feature is useful when an API call is interrupted in transit due to connection issues.
For example, if a request to create a transaction does not receive a response due to a network connection problem, it is possible to retry the action using the same idempotent key. This way, we ensure that only one transaction is created, avoiding duplicate charges.
Typical failure scenarios:
-
The initial connection may fail as the client attempts to connect to the server.
-
The request may fail midway while the server is processing the operation, leaving the task in an incomplete state.
-
The request may succeed, but the connection could break before the server can notify the client of the result.
How to perform an idempotent request?
To make an idempotent request, provide an additional idempotency key in the request header:
Idempotency-Key:
An idempotency key is a unique value that must be sent by the client-server in every request. It is used by the Pagseguro to recognize retries of the same operation. Whilst it is up to the consumer API to decide how to create these keys, we suggest using V4 UUIDs or another random string with enough entropy to avoid collisions.
APIs that support the idempotency feature in PagSeguro:
Considerations
POST method requests accept idempotency keys. In GET and DELETE requests, sending these keys has no effect and should be avoided since these requests are idempotent by definition.
The lifetime of these idempotency keys on PagSeguro International servers is 24 hours, after which, if a new request is made with the same key, it will be interpreted as the intention of creating a new resource.
We save results only after an endpoint has started executing. If input parameters fail validation, you can reuse the idempotency key for those requests. Learn more about when you can retry idempotent requests .
Updated about 16 hours ago