Idempotency

The idempotency key should be provided in the request's Idempotency-Key HTTP header. Idempotency keys are stored for 24 hours, so generated idempotency keys should be unique within that time frame.

The client is responsible for ensuring the idempotency key's uniqueness. Idempotency keys are unique within a merchant acceptor.

The endpoints that accept the Idempotency-Key as header input parameters support idempotent processing.

Silverflow needs to maintain an internal state to provide idempotent processing of charges. If this state becomes unavailable, the system will return a 503 retryable error with the type: https://api.silverflow.co/problems/service-unavailable/state. If this is the case, it is possible to retry the request without the Idempotency-Key header.

For all other endpoints that don't support idempotency keys (yet), it is advised to use the conditional update mechanism. This mechanism is currently most useful for provisioning, such as updating merchants and merchant acceptors.

Conditional Updates

In some cases, multiple processes interact with the API simultaneously, which could lead to an object being updated twice simultaneously. This could result in the lost update problem, in which changes from the first update are 'overwritten' by the second update.

To avoid this problem, any update (HTTP PATCH) operation should be accompanied by an If-Match header containing the object's version. The update will succeed when the object being updated still has that version. However, if a different process changes the object, the update operation will fail with a 412 Precondition Failed. When this is the case, it is up to the client to resolve this situation.

The contents of the If-Match header can be derived in two ways:

The value can be taken from the ETag response header when the object is retrieved through a GET operation.
The value can be taken from the version attribute of the object.