Payment Transactions — Proposed Guide

Planned API — Reference Only

Payment Transactions: A transaction representation would record payment-provider facts associated with a reimbursement. It should distinguish money…

Overview

A transaction representation would record payment-provider facts associated with a reimbursement. It should distinguish money movement records from the employee expense that prompted them.

Key concepts

Keep transaction amount, currency and provider reference together. Multiple attempts may exist for one reimbursement.

Implementation considerations

Do not sum all attempts as successful payments. Reporting must filter by a defined settlement interpretation and handle reversals.

Proposed API behavior

GET /v1/payment-transactions 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 query parameters
Name	Type	Description
status	string	Proposed lifecycle value. Its meaning depends on the resource and must not be inferred from HTTP success.

Static example requests

Proposed, non-executing request examples

# Proposed request text only; this reserved host is not a live API.
curl -X GET 'https://api.remizen.example/v1/payment-transactions?status=draft' \
  -H 'Authorization: Bearer YOUR_API_KEY'

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": [
    {
      "transaction_id": "txn_example_123",
      "reimbursement_id": "reimb_example_123",
      "amount_minor": 12550,
      "currency": "USD",
      "id": "txn_example_123",
      "organization_id": "org_example_123",
      "status": "pending"
    }
  ],
  "pagination": {
    "has_more": false,
    "next_cursor": null
  },
  "meta": {
    "request_id": "req_example_123",
    "reference_only": true
  }
}

Illustrative error case

Review this failure case in context: Do not sum all attempts as successful payments. Reporting must filter by a defined settlement interpretation and handle reversals.

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

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.
reimbursement_id	string	Stable fictional reimbursement 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.
status	string	Proposed lifecycle value. Its meaning depends on the resource and must not be inferred from HTTP success.

Retry Reimbursement

Reimbursements & Payments

Transaction Identifiers