/api/qmail/db/payments/list

GET

The receiver-side payment transaction log. Lists payment tells (tell_type 3) this client has received: who sent each payment, when, the purpose code, the amount (once claimed), and the claim status. Typically called on the receiving client.

http://localhost:8082/api/qmail/db/payments/list

Description

Payment tells are claimed automatically by the beacon loop (coins move from the sender's locker into this wallet), and each one is recorded in the local database. This endpoint reads that record — it makes no RAIDA calls. Because payment tells carry no message, the purpose code is the entire “memo”: a payment with purpose=0 displays as a subscription payment.

Response

Per-Payment Properties (array payments[])

payment_id string (32 hex)
The payment GUID from the tell.
sender_sn / sender_denomination integer
The sender's mailbox coin — AN-authenticated by the beacon, cannot be spoofed.
timestamp integer (Unix seconds)
When the payment was sent (sender's tell timestamp, ±60 s server-verified).
purpose / purpose_name integer / string
The purpose code and its registry name (subscription, invoice, gift_tip, refund, payroll, purchase, unspecified; unknown codes report unknown).
payment_status / payment_status_text integer / string
Claim state: pending (received, not yet claimed), claimed, refunded, or failed.
amount_units integer (10-8 CC units)
Actual claimed value; present once the claim completes (5000 CC = 500000000000). Omitted while still pending — the amount is known only after the locker is downloaded.

Example

{
  "success": true,
  "command": "payments",
  "payments": [
    {
      "payment_id": "9f2ab3c4d5e6f7a8b9c0d1e2f3a4b5c6",
      "sender_sn": 1234,
      "sender_denomination": 2,
      "timestamp": 1785305423,
      "purpose": 0,
      "purpose_name": "subscription",
      "payment_status": 2,
      "payment_status_text": "claimed",
      "amount_units": 500000000000
    }
  ],
  "count": 1
}

Important Notes

Pending Payments

A payment stuck in pending (e.g. the client went offline mid-claim) is retried by the beacon's stored-tell re-drive, and can always be claimed manually with /api/qmail/raida/payments/claim using its payment_id.

Sender-Side Ledger

The sending client keeps its own durable record of outgoing payments (GUID, recipient, amount, purpose, locker key, tell status) in the qmail_sent_payments table; see /api/qmail/raida/payments/send.