Transactions

A wallet's history is a list of transactions. Every credit and debit is recorded with a type, an amount, an optional external reference, and a timestamp. Transactions are returned alongside the wallet record — there is no separate /transactions collection — so listing them is just a wallet read with an expanded shape.

Reading transactions

Returns the wallet plus its transaction list and a summary block. Same response from getWalletWithTransactions.

Lookup by either walletId or customerId query parameter. Useful when you have the customer's ID but not the wallet ID.

curl "https://appengine.appmint.io/finance/wallets/transactions/lookup?customerId=cust_123" \
  -H "orgid: $ORG" \
  -H "Authorization: Bearer $JWT"

For customer-side reads, the equivalent self-scoped endpoint is:

Always returns the calling customer's wallet with transactions and summary. No parameters.

Transaction shape

Each transaction record carries:

Field	Description
type	The credit/debit type. See list below.
amount	Positive number. Direction is implied by type.
currency	Defaults to wallet currency.
reference	External ID — order number, invoice ID, payout number.
description	Free-text. Shown in statements.
createdAt	ISO timestamp.
runningBalance	Available balance after the transaction posted.

Credit types

Use these when calling POST /finance/wallets/:walletId/credit:

Type	Source
earning	Sale, service charge, base payment
tip	Gratuity from a customer
bonus	Platform-issued bonus
commission	Affiliate or referral commission
referral	Per-signup or per-conversion referral payout
refund	Refund returning to the wallet
adjustment	Manual correction by staff

{
  "amount": 49.99,
  "type": "earning",
  "reference": "ORD-2026-0412-9981",
  "description": "Order #9981 — net of platform fee"
}

Net amounts only. Compute the platform fee on your side and credit the residual; the fee itself is a separate accounting entry on the platform's books.

Debit types

Use these for POST /finance/wallets/:walletId/debit:

Type	Use
payout	Auto-recorded when a payout completes
fee	Per-transaction or per-period fee
chargeback	Reversal from a returned ACH or disputed card charge
adjustment	Manual correction

{
  "amount": 25.00,
  "type": "fee",
  "reference": "fee-2026-04",
  "description": "Monthly platform fee"
}

Filtering and pagination

The wallet response includes the full transaction list. For wallets with many transactions, use getWalletWithTransactions and filter client-side, or call:

To list wallets by ownerType, status, with page and pageSize. Each wallet returned includes a transaction summary block.

Reconciliation

Reconciliation in Finance is a two-way check between:

1. The wallet ledger (this module's transactions).
2. The external payment-rail records (Stripe, PayPal, ACH return files).

For gateway-side records, query through the upstream provider:

Query parameters:

The endpoint proxies listTransactions on the registered upstream vendor. Responses are vendor-shaped, not normalised — match by amount + currency + timestamp.

Reconciliation pattern

1. 1

   Pull gateway-side records

   Call gateway-transactions for the period under review.

2. 2

   Pull wallet-side credits

   Call getWalletWithTransactions for each affected wallet, filtering by the same period.

3. 3

   Match by reference

   For each gateway record, find the matching wallet credit by reference (e.g., the payment intent ID). Flag missing or mismatched amounts.

4. 4

   Post adjustments

   For confirmed discrepancies, post type: "adjustment" credits or debits with a clear description. Don't edit historical records.

Wallet stats

Aggregate counts: total wallets, by status, total available balance, total pending. Used for ops dashboards.