Reimbursement Status — Proposed Guide

Planned API — Reference Only

Reimbursement Status: A lifecycle could separate draft, eligible, queued, processing, completed, failed and returned outcomes. Each state needs an…

Overview

A lifecycle could separate draft, eligible, queued, processing, completed, failed and returned outcomes. Each state needs an evidence-based definition before implementation.

Key concepts

Keep processing attempts separate from the reimbursement aggregate. A returned payment can follow an earlier provider completion signal.

Implementation considerations

Do not treat completed as irrevocable unless the rail contract supports that interpretation. No state machine is active here.

Illustrative data model

This local fixture shows a possible representation for the concepts above. It is not an endpoint response, production configuration or a claim that the described capability is implemented.

JSON fixture

Fictional concept fixture

{
  "reference_only": true,
  "topic": "Reimbursement Status",
  "reimbursement_id": "reimb_example_123",
  "status": "draft",
  "attempt_id": "attempt_example_123",
  "occurred_at": "2026-01-15T12:00:00Z"
}

Design review checklist

Document which organization owns the reimbursement status representation and which actor may view or change it.
Test the boundaries of reimbursement id, status, attempt id, occurred at using synthetic values, including missing or inconsistent references.
Before future implementation, obtain an approved contract and review failure behavior. This documentation does not authorize production activation.

Proposed data types

Illustrative field dictionary
Name	Type	Description
reimbursement_id	string	Stable fictional reimbursement reference; not a secret and not evidence that a resource exists.
status	string	Proposed lifecycle value. Its meaning depends on the resource and must not be inferred from HTTP success.
attempt_id	string	Stable fictional attempt reference; not a secret and not evidence that a resource exists.
occurred_at	string (date-time)	Synthetic UTC timestamp. Business occurrence time may differ from delivery or processing time.

Create Reimbursement

Reimbursements & Payments

ACH Reimbursements