Idempotency

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

The uniqueness of the idempotency key is the responsibility of the client. Idempotency keys are unique within a merchant acceptor.

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

Note: 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 type: https://api.silverflow.co/problems/service-unavailable/state. If this is the case, it's 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 updating merchant acceptors.

Conditional Updates

In some cases multiple processes interact with the API simultaneously which could lead to an object being updated twice at the same time. This could result in the lost update problem in which case 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 which contains the version of the object. When the object being updated still has that version the update will succeed. However, if the object was changed by a different process 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 was retrieved through a GET operation.
The value can be taken from the version attribute of the object.