INTEGRATION
CHARGES
DISPUTES & FRAUD
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 theIdempotency-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 aGET
operation.The value can be taken from the
version
attribute of the object.