Transaction Identifiers — Proposed Guide

Planned API — Reference Only

Transaction Identifiers: Internal resource ids, operation keys and provider references serve different correlation purposes. None should be reused as a…

Overview

Internal resource ids, operation keys and provider references serve different correlation purposes. None should be reused as a credential or mistaken for proof of settlement.

Key concepts

Use namespace-aware identifiers and retain the mapping between a reimbursement, its attempts and provider records.

Implementation considerations

A provider reference can be absent before acknowledgment. Do not invent one to make an incomplete state appear final.

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": "Transaction Identifiers",
  "transaction_id": "txn_example_123",
  "attempt_id": "attempt_example_123",
  "provider_reference": "provider_example_123",
  "idempotency_key": "operation_example_123"
}

Design review checklist

Document which organization owns the transaction identifiers representation and which actor may view or change it.
Test the boundaries of transaction id, attempt id, provider reference, idempotency key 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
transaction_id	string	Stable fictional transaction 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.
provider_reference	string	Fictional provider correlation reference, not settlement evidence.
idempotency_key	string	Non-secret proposed operation key for controlled replay; supplied as an illustrative header.

Payment Transactions

Reimbursements & Payments

Payment Reconciliation