Retry Reimbursement — Proposed Guide

Planned API — Reference Only

Retry Reimbursement: A proposed retry action would create a new controlled attempt only when the earlier outcome and beneficiary details are understood.…

Overview

A proposed retry action would create a new controlled attempt only when the earlier outcome and beneficiary details are understood. It must not be a blind replay of a payment request.

Key concepts

Reference the prior attempt and an explicit reason. Recheck eligibility, instrument status and authorization.

Implementation considerations

Reject retries for ambiguous or already settled attempts. This static example creates no payment and offers no operational retry control.

Proposed API behavior

POST /v1/reimbursements/{reimbursement_id}/retry 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.

Proposed path parameters
Name	Type	Description
reimbursement_idrequired	string	Stable fictional reimbursement reference; not a secret and not evidence that a resource exists.

Illustrative request fields
Name	Type	Description
attempt_id	string	Stable fictional attempt reference; not a secret and not evidence that a resource exists.
reason	string	Synthetic structured justification, not a real reviewer note.

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/reimb_example_123/retry' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: operation_example_123' \
  --data '{
  "attempt_id": "attempt_example_123",
  "reason": "Example review explanation"
}'

Fictional response example

200 (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": {
    "reimbursement_id": "reimb_example_123",
    "attempt_id": "attempt_example_123",
    "reason": "Example review explanation",
    "id": "reimb_example_123",
    "organization_id": "org_example_123",
    "expense_ids": [
      "exp_example_123"
    ],
    "amount_minor": 12550,
    "currency": "USD",
    "status": "draft"
  },
  "meta": {
    "request_id": "req_example_123",
    "reference_only": true
  }
}

Illustrative error case

Review this failure case in context: Reject retries for ambiguous or already settled attempts. This static example creates no payment and offers no operational retry control.

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 retry reimbursement operation requires review of its input or authorization.",
    "request_id": "req_example_123"
  }
}

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.
attempt_id	string	Stable fictional attempt reference; not a secret and not evidence that a resource exists.
reason	string	Synthetic structured justification, not a real reviewer note.
idempotency_key	string	Non-secret proposed operation key for controlled replay; supplied as an illustrative header.

Returned Payments

Reimbursements & Payments

Payment Transactions