docs
/
AppEngine API

Wallets, payouts and payments

Internal balances, payout workflow, and gateway-agnostic payment operations.

FinanceModule sits between commerce and the books: wallets hold internal balances, payouts move money out to real accounts, and the payment controller is a gateway-agnostic front end for charging cards.

Wallets

GET/finance/walletsJWT
POST/finance/walletsJWT
POST/finance/wallets/get-or-createJWT
GET/finance/wallets/owner/lookupJWT
GET/finance/wallets/transactions/lookupJWT

get-or-create is the idempotent path — call it rather than checking existence first.

Movements

POST/finance/wallets/:walletId/creditJWT
POST/finance/wallets/:walletId/debitJWT
POST/finance/wallets/:walletId/holdJWT
POST/finance/wallets/:walletId/release/:holdIndexJWT

Holds reserve funds without moving them — an escrow between order and fulfillment. Note that a hold is released by index, not by an id, so releasing depends on the hold's position in the wallet's array.

POST/finance/wallets/:walletId/freezeJWT
POST/finance/wallets/:walletId/unfreezeJWT

Datatypes: wallet, wallet_transaction.

Payouts

POST/finance/wallets/:walletId/request-payoutJWT
GET/finance/payoutsJWT
GET/finance/payouts/:payoutIdJWT
GET/finance/payouts/number/lookupJWT
GET/finance/wallets/:walletId/payout-summaryJWT

Lifecycle — each POST /finance/payouts/:payoutId/<action>:

ActionMeaning
approveCleared for processing
processSubmitted to the payment rail
completeFunds confirmed delivered
failRejected or returned
cancelWithdrawn before processing

process and complete are separate because ACH settlement is not immediate. Marking complete on submission would report money as delivered that can still be returned.

POST/finance/batch/payoutsJWT
PUT/finance/wallets/:walletId/payout-settingsJWT
GET/finance/stats/walletsJWT
GET/finance/stats/payoutsJWT

Datatype: payout.

Payments

A uniform surface over whichever gateway is configured.

POST/finance/payments/chargeJWT
POST/finance/payments/authorizeJWT
POST/finance/payments/captureJWT
POST/finance/payments/voidJWT
POST/finance/payments/refundJWT
POST/finance/payments/cancelJWT
POST/finance/payments/verifyJWT
POST/finance/payments/retryJWT
POST/finance/payments/mark-paidJWT
POST/finance/payments/resend-receiptJWT

charge is authorize-and-capture in one step; authorize then capture splits it — the right shape when you charge on shipment rather than on order. void cancels an authorization that was never captured; refund reverses a capture.

POST/finance/payments/actionJWT
POST/finance/payments/gateway-urlJWT
GET/finance/payments/gateway-transactionsJWT

action is the generic dispatcher; gateway-transactions reads from the provider rather than local records, which is how you reconcile a discrepancy.

Customer-facing

Under /client/finance/*, scoped to the signed-in customer — the surface a marketplace seller or affiliate uses.

GET/client/finance/walletJWT
GET/client/finance/payoutsJWT
GET/client/finance/payouts/:payoutIdJWT
POST/client/finance/payouts/requestJWT
PUT/client/finance/payout-settingsJWT

Payout methods:

GET/client/finance/payout-methodsJWT
POST/client/finance/payout-methodsJWT
PUT/client/finance/payout-methods/:methodIdJWT
DELETE/client/finance/payout-methods/:methodIdJWT
PUT/client/finance/payout-methods/:methodId/defaultJWT
  • Storefront payments — Stripe and PayPal at checkout
  • Banking — read-only bank linking and reconciliation (AppEngine does not send transfers)
  • Books — where these movements post to the ledger