This page describes the core entities of the Money API and how they relate. These are the data structures behind collecting payments, sending payouts, and reading transaction and account information.
Response envelope
Every successful response is wrapped in a small envelope. Charge and payout reads return the resource under data with a success flag; create calls return an acknowledgement with a reference.
{ "success": true, "data": { } }
{ "success": true, "reference": "61684531", "redirect_link": "https://app.gozem.co/user/authorize?pid=…" }The transaction details and account endpoints carry the same success flag plus a message, but return their fields flat in the envelope — there is no data wrapper:
{ "success": true, "message": "Ok", "reference": "61684531", "amount": { } }Because message belongs to the envelope, a transaction’s own shared note is exposed as shared_note.
Errors use the same failure envelope everywhere — success: false, a human-readable message, and a machine-readable error_code. Charge and payout use SCREAMING_SNAKE codes (INSUFFICIENT_FUNDS); transaction details and account use lowercase snake_case (transaction_not_found). See Errors for the full shapes and catalogue.
Identifiers and references
A create call (charge or payout) returns a reference — the numeric transaction number (the same one users see in the Gozem apps) that you use to fetch that resource later and the value that appears on the matching webhook. Your merchant profile and primary account are not passed in the URL; they are resolved from your authenticated API client.
Merchant account
Your business account on Gozem Money, bound to your API client. Charges land here; payouts are debited from here. One API client maps to exactly one merchant account. Read it with GET /money/v1/account — it carries the primary wallet number, balance, and a public payment_link.
Charge
A charge pulls money from a payer into your merchant account. It targets a payer_identifier (a Gozem Money account or a phone number) over a channel, and requires your merchant PIN (pin) to authorize. Gozem-channel charges are approved by the payer in the Gozem app via the redirect_link returned at creation; PSP-channel charges (flooz-tg, yas-tg) return a pending acknowledgement and settle asynchronously.
Payout
A payout sends money from your merchant account to a beneficiary_identifier (Gozem Money account or phone; bank accounts are reserved for future use) over a channel. On the transaction envelope a payout has type payout and a negative amount.value. The authorizing pin is your merchant PIN — sent plain or, preferably, encrypted with the RSA public key issued at onboarding (see PIN encryption).
Transaction
A normalized view of a payment where your client is payer or payee, returned by charge/payout detail and by GET /money/v1/transaction-details/:id. The transaction envelope is the shared shape:
| Field | Description |
|---|---|
reference |
Unique transaction reference; matches webhook payloads. |
status |
{ code, label } — numeric code and short label. |
type |
Transaction type, lower case — for example payment (an incoming charge) or transfer (an outgoing payout). Treat it as an open set and match case-insensitively. |
amount |
{ value, currency } — signed; positive in, negative out. |
balance_after |
Merchant balance after the transaction, or null. |
counterpart_account |
The other party: identifier, channel, name. |
account |
The merchant-side account. |
category |
{ id, label } — Gozem Money transaction category, when one applies. |
note |
Your client’s private note on the transaction, or null. |
shared_note |
The note shared between both parties. Named shared_note because message belongs to the envelope. |
description |
Human-readable description generated by Gozem Money, or null. |
payment_references |
Your reconciliation references. |
created_at |
ISO 8601 timestamp. |
category, note, shared_note, and description are returned by transaction details; charge and payout detail responses carry the core fields above.
Channels
The rail a charge or payout runs over: gozem (in-app Gozem Money wallet), flooz-tg (Flooz Togo), and yas-tg (Mix by Yas Togo). PSP channels are asynchronous — the terminal state arrives by webhook (see Payments Lifecycle & Events).
Amounts and currency
Amounts are integers in the smallest currency unit (for example, centimes) and must be greater than zero. Supported currencies are XOF and XAF; the available channels depend on the market (see the Overview).
Idempotency
Create calls accept an idempotency-key header so a safe retry never charges or pays out twice. The mechanism and conflict behaviour are covered in Authentication.