Idempotency in healthcare payment posting means a retried request cannot create a second claim, payment, or posting record when the first attempt's outcome was uncertain. The mechanism varies by system. Stedi's institutional claims API accepts an Idempotency-Key header and permits safe retries with the same key for 24 hours after the first request [1]. Increase's banking API uses an Idempotency-Key creation parameter that should be pre-allocated before invoking a creation method [4]. Convenient Checkout's v2 payment API uses merchantTransactionId as a composite idempotency key with merchantId, limiting attempts to five total [6]. Elation Billing's payment posting documentation addresses duplicate prevention through workflow rules rather than a documented API key, warning users not to click Auto Post Now after marking an ERA reviewed [5]. These differences shape how engineering teams design retry logic, database constraints, and reconciliation procedures.
Where the Idempotency Boundary Lives
The location of the idempotency boundary determines what a retry can safely repeat. Stedi places the boundary at the HTTP request level for claims submission. The documentation states that including an idempotency key in the Idempotency-Key header prevents sending duplicate claims to payers in the case of network errors or other intermittent failures, and that retries with the same key are safe within 24 hours [1]. The legacy professional claims endpoint specifies the key can be up to 255 characters and carries the same 24-hour retry window [7]. This boundary covers the submission call itself, not the downstream payer's processing of the 837 transaction.
Increase places the boundary at object creation. The Idempotency-Key is an optional creation parameter that should be a unique value pre-allocated in the system before invoking the creation method, such as an application's Invoice ID for an ACH Transfer [4]. Increase recommends setting the value for all POST requests and building automatic retries, especially for transfer creation. The documentation warns against building automatic solutions using reads of the list endpoint; instead, retry with the same parameters and the same Idempotency-Key and rely on idempotency to eventually deliver a successful response [4]. This boundary covers the creation of a transfer object, not the settlement of funds.
Composite Keys and Retry Limits
Convenient Checkout's v2 payment API documents a composite uniqueness rule: merchantTransactionId plus merchantId together form the idempotency key [6]. The same merchantTransactionId from different merchants creates separate payments, which prevents cross-merchant collisions. The documentation specifies a maximum of five total attempts, one initial plus four retries. On retry, the API returns the existing payment resource with its current status, and a retry does not create a new Stripe PaymentIntent [6]. After the limit, the API returns 422 UNPROCESSABLE_ENTITY and the merchant must use a new merchantTransactionId. This documentation is marked as internal information not visible on the public merchant site.
The retry limit introduces a design constraint absent from Stedi's 24-hour window. A team integrating Convenient Checkout must track retryCount atomically, using an UPDATE statement that increments retryCount only where retryCount is less than five to prevent race conditions [6]. The documentation also instructs engineers to forward merchantTransactionId to Stripe as the Stripe idempotency key, creating a second deduplication layer. If the service database shows no record but Stripe has one after a partial failure, the Stripe response takes precedence and the service reconciles the state [6]. This layered approach means the effective idempotency boundary spans two systems with different storage durations.
Choosing a Key Generation Strategy
The documented sources point to different key generation strategies. Increase recommends pre-allocating a unique value before invoking the creation method, using an application's Invoice ID for an ACH Transfer or User ID for an Entity [4]. AWS recommends generating the key inside a step once and passing it to every attempt, warning that a key generated outside a step changes on replay [2]. PayPal recommends UUID format to meet its 38 single-byte character limit [3]. Stedi's legacy professional claims endpoint allows a key up to 255 characters [7]. A team should select a strategy that satisfies the most restrictive constraint among the systems in its workflow, and document where the key is generated relative to any durable execution replay boundary.
Payment Posting Without a Documented API Key
Elation Billing's payment posting documentation does not describe an idempotency key header or parameter. Instead, duplicate prevention appears as workflow instructions. The documentation states that after saving a payment from an ERA, the user should mark the source ERA as reviewed and not also click Auto Post Now, or duplicates will be created [5]. This places the deduplication responsibility on the human operator following a sequence, rather than on an automated key exchange between systems.
The Elation documentation also addresses reconciliation scenarios that can create apparent duplicates. When an EOB total does not match the check, the user must reconcile the variance before posting, with common causes including interest lines, prior overpayment recoupment lines, or a multi-EOB check [5]. Recoupment or takeback lines on a current EOB appear as negative-payment lines that offset prior payments; the user posts the offset as a negative payment line on the original claim or follows the reversal workflow [5]. These instructions describe how to handle offsetting entries, not how to retry a failed API call safely. An engineering team integrating with Elation Billing would need to determine from Elation whether any programmatic idempotency mechanism exists, because the supplied documentation does not state one.
Durable Execution and External Service Retries
AWS's Durable Execution SDK documentation describes a pattern for idempotency tokens that applies to external services supporting an idempotency key, such as most modern payment APIs [2]. The guidance is to generate a key inside a step once and pass it to every attempt of the side-effecting step. The documentation warns that a key generated outside a step changes on replay, which defeats deduplication and doubles up on retry [2]. This distinction matters for healthcare payment workflows that run inside durable execution frameworks, where a step may be replayed after a crash.
The AWS documentation also addresses how to interpret duplicate-request errors. When an idempotency-enabled API returns a duplicate-request error on retry, it usually means the first attempt already succeeded, and the caller should handle that error as success, not failure [2]. The same pattern applies to any operation that writes to an external store: include the key in the write and rely on the store's deduplication [2]. PayPal's idempotency documentation adds a related caution: the PayPal-Request-Id header value must be unique for both each request and an API call type, such as authorize payment versus capture authorized payment, and PayPal recommends the UUID standard because it meets the 38 single-byte character limit [3]. PayPal also notes that it provides the status of a request at the current time, not the status of the original request [3].
A Suggested Validation Scenario
A useful hypothetical validation scenario for a healthcare payment posting integration would test the boundary between a claims submission API and a payment processor. Suppose a billing service submits an 837I institutional claim through Stedi with an Idempotency-Key header, then separately initiates an ACH transfer through Increase using the same pre-allocated key value. The test would confirm that retrying the Stedi claim submission within 24 hours with the same key does not create a second claim [1], and that retrying the Increase transfer creation with the same Idempotency-Key returns the existing transfer object rather than a new one [4].
The scenario should also test failure interpretation. If the Increase retry returns a duplicate-request error, the integration should treat it as success per the AWS guidance [2]. If the Convenient Checkout payment API is involved, the test would verify that attempt six with the same merchantTransactionId returns 422 and that a new merchantTransactionId is required [6]. This scenario is a suggestion for engineering validation, not a report of independent testing. It isolates the documented behaviors without asserting that any combination of these systems has been tested together.
Sources & references
- Submit institutional claims - API and UI · www.stedi.com
- Idempotency and retries - AWS Durable Execution SDK Developer Guide · docs.aws.amazon.com
- Idempotency | PayPal Developer · developer.paypal.com
- Idempotency keys - Increase: Banking API · increase.com
- Recording & posting a payment in Elation Billing · help.elationhealth.com
- Idempotency & Retries | Convenient Checkout · developers.healthsafepay.com
- Professional Claims (837P) JSON - Legacy - Stedi Docs · www.stedi.com
- Payment Posting - InstaMed Developer Portal · developers.instamed.com