Create Reimbursement — Proposed Guide

Planned API — Reference Only

Create Reimbursement: Creating a proposed reimbursement record would validate that referenced expenses are eligible and have not already been repaid. It…

Overview

Creating a proposed reimbursement record would validate that referenced expenses are eligible and have not already been repaid. It should not silently authorize payment execution.

Key concepts

Record the approved source snapshot, beneficiary reference and explicit currency. Use replay protection for record creation.

Implementation considerations

Bank account selection and payment initiation require separate authorization. The sample creates no real record or financial obligation.

Proposed API behavior

POST /v1/reimbursements is an illustrative design for this topic. Path and field names may change before implementation. Access would require an authorized organization context and operation-specific permission; no public API or authorization grant is available here.

Illustrative request fields
Name	Type	Description
expense_ids	array<string>	Fictional expense references; validate ownership and avoid duplicate membership.
user_id	string	Stable fictional user reference; not a secret and not evidence that a resource exists.
amount_minor	integer	Monetary amount in the documented currency minor unit; 12550 represents USD 125.50, not USD 12,550.
currency	string	Uppercase ISO 4217 currency code. Determine its minor-unit exponent before monetary conversion.

Static example requests

Proposed, non-executing request examples

# Proposed request text only; this reserved host is not a live API.
curl -X POST 'https://api.remizen.example/v1/reimbursements' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: operation_example_123' \
  --data '{
  "expense_ids": [
    "exp_example_123"
  ],
  "user_id": "usr_example_123",
  "amount_minor": 12550,
  "currency": "USD"
}'

Fictional response example

201 (proposed example)Static response fixture

Fictional documentation data only. No request was sent, record created, review performed, payment initiated or provider connection activated.

JSON

{
  "data": {
    "expense_ids": [
      "exp_example_123"
    ],
    "amount_minor": 12550,
    "currency": "USD",
    "id": "reimb_example_123",
    "organization_id": "org_example_123",
    "status": "draft"
  },
  "meta": {
    "request_id": "req_example_123",
    "reference_only": true
  }
}

Illustrative error case

Review this failure case in context: Bank account selection and payment initiation require separate authorization. The sample creates no real record or financial obligation.

422 (illustrative; final error contracts are undecided)Proposed error fixture

Synthetic diagnostic example. Human-readable messages must not be used as stable programmatic contracts.

JSON

{
  "error": {
    "code": "validation_error",
    "message": "The proposed create reimbursement operation requires review of its input or authorization.",
    "request_id": "req_example_123"
  }
}

Proposed data types

Illustrative field dictionary
Name	Type	Description
expense_ids	array<string>	Fictional expense references; validate ownership and avoid duplicate membership.
user_id	string	Stable fictional user reference; not a secret and not evidence that a resource exists.
amount_minor	integer	Monetary amount in the documented currency minor unit; 12550 represents USD 125.50, not USD 12,550.
currency	string	Uppercase ISO 4217 currency code. Determine its minor-unit exponent before monetary conversion.
idempotency_key	string	Non-secret proposed operation key for controlled replay; supplied as an illustrative header.

Retrieve Reimbursement

Reimbursements & Payments

Reimbursement Status