Idempotency

COS supports idempotency to allow requests to be retried without risk of the operation being performed multiple times. This is especially useful in situations where there is a network outage and you are unsure if a previous request had been processed successfully. When in doubt, submit the request again with the same idempotency key in the request header.

📘

Best Practice

Include a unique idempotency key with all POST requests. It will protect against accidental duplicate requests.

It is highly recommended your idempotency key be a V4 UUID, however it can be any value you choose, up to 50 characters. Whenever the API detects a previously processed request, it will automatically return the cached results of the original request. A previously processed request is determined by a combination of same endpoint, request body and idempotency key. If the request body is modified in anyway, it will NOT be seen as a duplicate request and will be processed normally.

COS will guarantee this behavior for up to 7 days from the date of the original request. Given this, if the intent is to process the request a second time, the idempotency key should always be changed to a new value. It is not recommended to rely on the age of the original request as the deciding factor.

GET and DELETE requests are naturally idempotent and do no require a key to be passed. The key will simply be ignored if present for these requests.

You can detect if the request is being handled as a duplicate and returning a cached response, by looking for the "original-request-id" response header. That header value will correlate to the request-id of the original request processed under the idempotency key provided.

Using an Idempotency Key

The key is passed in the request header as follows:

idempotency-Key: 'xxxxx'

Client Identifiers

It is recommended you pass a unique internal identifier for the payment or transaction being sent to COS in the clientIdentifier field if available. This can be any string value up to 50 characters. Note that COS does not enforce uniqueness or idempotency based on this value and it is optional. It is however an important part of implementing your idempotency solution. This value can be used to search for a payment to check if COS had successfully processed your request when in doubt. This should not be done if the response indicates success. It is only to be used in edge cases when there is doubt regarding the response (i.e. an exception occurred)

For example, you resubmit a request using the same idempotency key and the cached response indicates an error occurred. Before resubmitting with a new idempotency key it is recommended the payment is searched for using your clientIdentifier. If a result is returned, then there is no need to resubmit and you should record the payment details returned accordingly. If no results are returned, then the payment should be resubmitted using a new idempotency key. When searching by clientIdentifier, be sure to include a from and to date parameter. If omitted, the default search period is 24 hours.