Skip to Content

Idempotent Requests

To ensure the reliability and consistency of your integrations, the Checkbook API supports idempotent requests for all POST requests (e.g., creating payments).

What is Idempotency?

An idempotent operation is one that can be applied multiple times with the same effect as applying it only once. In the context of API requests, this means that if a request is sent to the Checkbook API multiple times with the same idempotency key, only the first successful request will have the intended effect. Subsequent identical requests will return the same response as the first successful one, without creating duplicate resources or triggering unintended side effects.

Why is Idempotency Important?

Idempotency is crucial for handling network issues, timeouts, and other transient errors that can occur during API communication. Without it, retrying a failed request might lead to unintended consequences, such as:

  • Duplicate Payments — paying out multiple times for the same transaction.
  • Inconsistent Data — creating multiple identical resources when only one was intended.

By implementing idempotent requests, you can safely retry failed operations without the risk of these issues, leading to more robust and reliable integrations.

How to Implement Idempotent Requests in the Checkbook API:

To make a request idempotent, you need to include a unique identifier in the request header:

  • Idempotency-Key Header: You must generate a unique string for each request that you want to be idempotent and include it in the Idempotency-Key HTTP header.
💡
Tip

The idempotency key is valid for 24 hours. After that, using the same key will result in a new request.

Key Considerations for the Idempotency-Key:

  • Uniqueness: The Idempotency-Key should be unique to the specific operation you are performing. For example, when creating a payment for a particular order, you might use a combination of your order ID and a timestamp or a UUID.
  • Persistence (Recommended): Ideally, you should store the Idempotency-Key associated with the request on your side. This allows you to retry the exact same request with the same key if the initial request fails or times out.
  • Granularity: Choose the appropriate level of granularity for your idempotency keys. For instance, if you are creating multiple line items in an order, you might want the entire order creation to be idempotent rather than each individual line item creation.
  • Length and Format: The Idempotency-Key should be a string. As there is a length limitation of 255 characters for the key, it’s recommended to keep it reasonably sized (e.g., using UUIDs, which are 36 characters long).

Example curl Request with an Idempotency-Key:

curl -X POST \
  -H "Authorization: d6aa2703655f4ba2af2a56202961ca86:dXbCgzYBMibj8ZwuQMd2NXr6rtvjZ8" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: employee-of-the-month-bonus-payment-id22" \
  -d '{
    "name": "Dwight Schrute",
    "recipient": "dwight@dundermifflin.com",
    "amount": 500.00,
    "description": "Employee of the Month Bonus"
  }' \
  https://demo.checkbook.io/v3/check/digital
Last updated on