Returned Payments — Proposed Guide

Planned API — Reference Only

Returned Payments: A return is a later event affecting an earlier payment attempt. It is not the same as rejecting a request before it reaches the provider.

Overview

A return is a later event affecting an earlier payment attempt. It is not the same as rejecting a request before it reaches the provider.

Key concepts

Link the return to the original transaction and preserve both event times. Represent any changed reimbursement state explicitly.

Implementation considerations

Do not delete the original completion record. Future accounting treatment and reissue authorization need an approved business policy.

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": "Returned Payments",
  "transaction_id": "txn_example_123",
  "return_id": "return_example_123",
  "reason": "Example review explanation",
  "occurred_at": "2026-01-15T12:00:00Z"
}

Design review checklist

Document which organization owns the returned payments representation and which actor may view or change it.
Test the boundaries of transaction id, return id, reason, 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
transaction_id	string	Stable fictional transaction reference; not a secret and not evidence that a resource exists.
return_id	string	Stable fictional return reference; not a secret and not evidence that a resource exists.
reason	string	Synthetic structured justification, not a real reviewer note.
occurred_at	string (date-time)	Synthetic UTC timestamp. Business occurrence time may differ from delivery or processing time.

Failed Payments

Reimbursements & Payments

Retry Reimbursement