Transaction Reconciliation - Cadana Developers

The Platform Disbursements endpoint gives platform partners a unified view of all transactions across every business under your platform — payroll payments, payouts, and other financial operations — in a single query. Use it to build reconciliation reports, track revenue share, drill into payroll fee breakdowns via invoices, and reconcile your books.

Prerequisites

API key from Dashboard

Get your API key from the Cadana Dashboard. See Authentication for details.

Platform integration

You must be set up as a platform partner managing multiple businesses. See Platform Overview.

Businesses with transactions

At least one business under your platform must have completed payroll runs or wallet transactions.

Platform Disbursements

Fetch all transactions across every business on your platform. Results are filtered by date range and paginated automatically.

Query Parameters

Parameter	Type	Required	Description
`businessId`	string (uuid)	No	Scope results to a single business account (see Scope to a Single Business).
`currency`	string	No	Filter by the business-facing currency — matches either the destination `amount` or the `sourceAmount` (e.g. `USD`).
`startDate`	string	No	Start of date range (ISO 8601, e.g. `2026-01-01`). Defaults to 7 days ago.
`endDate`	string	No	End of date range (ISO 8601, e.g. `2026-02-01`). Defaults to now.
`type`	string	No	Comma-separated transaction types to include (see Transaction Types).
`status`	string	No	Filter by status: `SUCCESS`, `FAILED`, `INITIATED`, `PROCESSING`, `ROUTED`.
`includeRevenueShare`	boolean	No	Set to `true` to include the revenue-share fields in each item (see Revenue Share). Omitted by default.

Response Structure

{
  "data": [ ... ],
  "cursor": {
    "previous": null,
    "next": "eyJsYXN0S2V5Ijp7InBrIjoiLi4uIn19"
  }
}

Transaction Object Fields

Field	Type	Description
`id`	string	Unique transaction identifier
`tenantKey`	string	Identifies which business this transaction belongs to. Use this to group transactions per business.
`status`	string	Transaction status: `SUCCESS`, `FAILED`, `INITIATED`, `PROCESSING`, `ROUTED`
`referenceId`	string	External reference. Payroll transactions from the same run share the same `referenceId`.
`description`	string	Human-readable description (e.g. “January 2026 Payment Dundies”)
`type`	string	Transaction type (see Transaction Types)
`fxRate`	number	FX rate applied. Present only for cross-currency transactions.
`paymentMethod`	string	Delivery method: `bank`, `momo`, `wallet`, `ach`, `card`, `proxy`
`paymentDetails`	object	Full payment method details (bank account, mobile money, wallet, ACH, card info)
`personId`	string	Employee or contractor ID. Present only on payroll transactions.
`userId`	string	Wallet/user account ID. Present on wallet-based transactions. For payroll, only present when payment is delivered to a wallet.
`userName`	string	Recipient name
`amount`	object	Amount the recipient receives, in the destination currency
`sourceAmount`	object	Cost in the source currency, before fees
`feeAmount`	object	Fees charged, in the source currency
`totalAmount`	object	Total debited from sender: `sourceAmount` + `feeAmount`
`fxRevenueShare`	object	Revenue earned from FX spread (see Revenue Share)
`feeRevenueShare`	object	Revenue earned from fees (see Revenue Share)
`totalRevenueShare`	object	Combined total revenue share
`createdTimestamp`	string	When the transaction was created
`lastUpdatedTimestamp`	string	When the transaction was last updated

All amount fields follow this structure:

{
  "value": "100.00",
  "currency": "USD"
}

Transaction Types

Type	Description
`PAYROLL`	Payment from a business to an employee or contractor as part of a payroll run
`PAYOUT`	Outbound transfer from a user’s wallet to an external bank, mobile money, card, or other destination
`TRANSFER`	Internal movement of funds between your platform’s own business accounts — the main parent and its children (see Internal Transfers)
`PAYROLL_FEE`	Processing fee for a payroll run (see Payroll Fee & Invoice Details)
`CARD_MAINTENANCE_FEE`	Recurring maintenance fee for a virtual card
`CARD_CREATION_FEE`	One-time fee for creating a virtual card
`STOCK_BUY`	Stock purchase transaction
`STOCK_SELL`	Stock sale transaction
`INTEREST`	Interest earned or charged

Internal Transfers

Move money between your own business accounts — your main business and any of its child businesses — with the Create Transfer endpoint. Transfers are internal, same-currency only, and settle immediately with no fee. Name the sourceTenantKey (optional — omit to send from your main business) and destinationTenantKey in the request body; allowed movements are main → child, child → child, and child → main. Create Transfer returns only the transfer id — there’s no GET for it. Find a transfer here by filtering to type=TRANSFER (or scope to one account with businessId), then match the returned id or your reference. It appears under the source business as an outgoing transaction.

Identifying Businesses with tenantKey

Every transaction includes a tenantKey that identifies which business it belongs to. Group by tenantKey to produce per-business reconciliation reports.

[
  { "id": "...", "tenantKey": "tbl28153208", "type": "PAYROLL" },
  { "id": "...", "tenantKey": "tbl89195039", "type": "PAYROLL" },
  { "id": "...", "tenantKey": "cad35916961", "type": "PAYOUT" }
]

Scope to a Single Business

Pass businessId=<uuid> to narrow the list to one business’s account. This returns every disbursement where that business’s account is the sender or recipient — both money it sent (payroll, vendor payments, payouts) and money it received (deposits, refunds/reversals). It is bidirectional. This is distinct from tenantKey: tenantKey returns everything under a tenant, while businessId returns only the rows touching that one business’s account — a narrower set. The response shape, fields, and ordering (newest-first by createdTimestamp) are identical to the unfiltered call. A few things to keep in mind when reading the items:

Direction comes from type, not a dedicated field. For example, DEPOSIT is inbound; PAYROLL_TOTAL and VENDOR are outbound. Don’t assume a fixed direction for every type.
userId / userName are the counterparty (the other side of the transaction), not the scoped business itself — so an item is not necessarily “a payment the business sent to userId”.
By default the per-employee PAYROLL legs and PAYROLL_FEE rows are collapsed into the single PAYROLL_TOTAL line; pass an explicit type to get the raw rows. Business-relevant types include PAYROLL_TOTAL, PAYROLL, PAYROLL_FEE, PAYROLL_REVERSAL, DEPOSIT, DEPOSIT_REVERSAL, VENDOR, REVENUE_SHARE_PAYOUT, REIMBURSEMENT, SUBSCRIPTION_PAYMENT, and STATUTORY_DEPOSIT.

Paging through a business’s disbursements

Pagination is the same as the unfiltered endpoint: read cursor.next from each response and send it back to fetch the next page, repeating until it comes back null (default limit 50, max 100). The cursor is opaque — don’t parse it.

GET /v1/platform/disbursements?businessId=…&currency=USD&limit=50
  → cursor.next = "eyJsYXN0S2V5Ijp…"
GET /v1/platform/disbursements?businessId=…&currency=USD&limit=50&next=eyJsYXN0S2V5Ijp…
  → cursor.next = null   (done)

Payroll Transactions

Payroll transactions (type: "PAYROLL") represent individual payments to employees or contractors. Key identifiers:

personId — the employee or contractor being paid. Always present on payroll transactions and is the primary identifier for reconciliation.
userId — only present when payment is delivered to a wallet. Not present for external payments (bank, mobile money, etc.).
referenceId — shared across all payments in the same payroll run, so you can group them.
description — contains the name of the payroll run (e.g. “January 2026 Payment Dundies”).

Example — cross-currency payroll payment to a bank account:

{
  "id": "a2f47c91-3b8e-4d12-9c6a-7e5d1f8b2a40",
  "tenantKey": "tbl89195039",
  "status": "SUCCESS",
  "referenceId": "9c4829a8-0177-4dad-a0d8-e4f8fc42276a",
  "description": "January 2026 Payment Dundies",
  "type": "PAYROLL",
  "fxRate": 5.812,
  "paymentMethod": "bank",
  "personId": "0a938505-ae3f-44a2-9793-196a4a11e6f2",
  "userName": "Maria Santos",
  "amount": { "value": "5812.00", "currency": "BRL" },
  "sourceAmount": { "value": "1000.00", "currency": "USD" },
  "totalAmount": { "value": "1000.00", "currency": "USD" },
  "fxRevenueShare": { "amount": { "value": "10.00", "currency": "USD" }, "rate": 1 },
  "totalRevenueShare": { "value": "10.00", "currency": "USD" }
}

userId is absent here because the payment was delivered to an external bank account, not a wallet.

Example — same-currency payroll payment via wallet:

{
  "id": "c6250a16-eb63-41de-a952-8122d305ebbf",
  "tenantKey": "tbl12101631",
  "status": "SUCCESS",
  "referenceId": "7b82d74e-4ad5-4fbf-af9c-a0f11b224c7a",
  "description": "January 2026 Payment PS",
  "type": "PAYROLL",
  "paymentMethod": "wallet",
  "userId": "060e3aeb-4a9d-4a90-aff5-17f8d69635ce",
  "personId": "8ab2ba37-3c37-485d-9af9-122d11c96bf9",
  "userName": "Reed Maygone",
  "amount": { "value": "1000.00", "currency": "USD" },
  "sourceAmount": { "value": "1000.00", "currency": "USD" },
  "totalAmount": { "value": "1000.00", "currency": "USD" }
}

Here userId is present because the payment went to the employee’s wallet. Same-currency payroll has no fxRate or FX revenue share, and may not have fee fields since fees are captured in the payroll fee transaction instead.

Wallet Transactions

Transactions of type PAYOUT, CARD_MAINTENANCE_FEE, CARD_CREATION_FEE, STOCK_BUY, STOCK_SELL, and INTEREST are wallet-level operations. They are associated with a user via the userId field.

These transactions may include revenue share fields depending on your platform agreement.

Example — cross-currency payout to a bank account in Brazil:

{
  "id": "c5bcdbba-52a2-44a4-8dda-2b03d47a1af1",
  "tenantKey": "tbl28153208",
  "status": "SUCCESS",
  "type": "PAYOUT",
  "fxRate": 5.7896,
  "paymentMethod": "bank",
  "userId": "8cb1d569-5dfd-4b33-b25e-4fab0ee14251",
  "userName": "Paula Torres",
  "amount": { "value": "578.96", "currency": "BRL" },
  "sourceAmount": { "value": "100.00", "currency": "USD" },
  "feeAmount": { "value": "13.50", "currency": "USD" },
  "totalAmount": { "value": "113.50", "currency": "USD" },
  "fxRevenueShare": { "amount": { "value": "1.00", "currency": "USD" }, "rate": 1 },
  "feeRevenueShare": { "amount": { "value": "10.00", "currency": "USD" } },
  "totalRevenueShare": { "value": "11.00", "currency": "USD" }
}

Understanding Amounts

Each transaction has four amount fields that tell you the full financial picture:

Field	Description
`amount`	What the recipient receives, in the destination currency
`sourceAmount`	Cost in the sender’s currency, before fees
`feeAmount`	Fees charged, in the sender’s currency
`totalAmount`	Total debited from sender: `sourceAmount` + `feeAmount`

Cross-Currency Example

When a user sends USD and the recipient receives BRL:

sourceAmount:  100.00 USD   (cost before fees)
feeAmount:      13.50 USD   (fees)
totalAmount:   113.50 USD   (total debited = 100.00 + 13.50)
fxRate:        5.7896        (USD → BRL conversion rate)
amount:        578.96 BRL    (what the recipient gets: 100.00 × 5.7896)

Same-Currency Example

When both sides are in the same currency, no FX conversion applies:

sourceAmount:  1000.00 USD
feeAmount:        0.00 USD
totalAmount:   1000.00 USD
amount:        1000.00 USD   (same as source, no conversion)

If your platform has a revenue share agreement with Cadana, eligible transactions include revenue share fields showing your earnings. These fields are only present when applicable — they are omitted when no revenue share applies.

Field	Description
`fxRevenueShare`	Revenue earned from the FX spread. Contains `amount` (value + currency) and `rate` (share percentage).
`feeRevenueShare`	Revenue earned from transaction fees. Contains `amount` (value + currency).
`totalRevenueShare`	Combined total of FX and fee revenue share. Contains `value` and `currency`.

Example — transaction with both FX and fee revenue share:

{
  "fxRevenueShare": {
    "amount": { "value": "0.41", "currency": "USD" },
    "rate": 1
  },
  "feeRevenueShare": {
    "amount": { "value": "10.07", "currency": "USD" }
  },
  "totalRevenueShare": { "value": "10.48", "currency": "USD" }
}

In this case, the platform earned $0.41 from the FX spread and $10.07 from fees, totaling $10.48 in revenue share.

Sum totalRevenueShare across all transactions to determine your platform’s total earnings for a period. Break it down further with fxRevenueShare and feeRevenueShare to understand the source of revenue.

Payroll Fee & Invoice Details

When a business runs payroll, a separate PAYROLL_FEE transaction appears representing the processing fee for the entire run. To see the detailed breakdown of how the fee was calculated (per-employee line items), you need the invoice ID.

Getting the Invoice ID

After a payroll completes, the payroll response includes an invoiceId field. Fetch the payroll by its ID (you can find this via the referenceId on any PAYROLL transaction from the disbursements response): The response includes the invoiceId once the payroll is in completed status. Then use that ID to fetch the full invoice: The invoice provides a full breakdown of charges associated with a payroll run, including per-employee costs, FX markups, and fees. To download the invoice as a PDF: Response:

{
  "fileUrl": "https://...",
  "expiresAt": 1710590400
}

The fileUrl is short-lived. Fetch a new URL each time you need to download the PDF.

Pagination

Results are paginated. The cursor object tells you whether more pages are available:

{
  "cursor": {
    "previous": null,
    "next": "eyJsYXN0S2V5Ijp7InBrIjoiLi4uIn19"
  }
}

cursor.next — pass as the cursor query parameter to fetch the next page
cursor.previous — pass to go back to the previous page
null — no more pages in that direction

Fetching the next page:

Reconciliation Walkthrough

Step 1: Fetch all successful transactions for the period

Paginate through all results using the cursor.next value until it returns null.

Step 2: Group by business

Group transactions by tenantKey to build per-business ledgers:

tenantKey	Transaction Count	Total Debited
`tbl28153208`	15	$627.47 USD
`tbl89195039`	2	$385.00 USD
`tbl12101631`	2	$3,000.00 USD
`cad35916961`	6	$103.55 USD

Step 3: For payroll, identify employees by personId

Filter for type: "PAYROLL" and group by personId to see how much each employee was paid:

personId	Employee Name	Total Paid (destination)	tenantKey
`0a938505-...`	Elizabeth Wilson	151.39 GHS	`tbl89195039`
`00b39f7a-...`	Dwight Schrute	5,677.18 GHS	`tbl89195039`
`8ab2ba37-...`	Reed Maygone	1,000.00 USD	`tbl12101631`
`ca49c55b-...`	Mahatra Ghandi	2,000.00 USD	`tbl12101631`

Sum totalRevenueShare across all transactions for your platform’s total earnings. Break down further with fxRevenueShare and feeRevenueShare.

Step 5: Get payroll fee details

For any PAYROLL_FEE transactions, use the Get Invoice endpoint to retrieve the detailed breakdown, including per-employee line items.

Account Statements

Download a formatted account statement for a business over a date range with the Get Business Statement endpoint. The statement bundles the opening and closing balance, period totals, and every transaction line into a single document — ready to hand to accounting or reconcile against your books. Pick the output with the format query parameter:

`format`	Returns
(omitted)	JSON statement object
`csv`	CSV file download
`bai2`	BAI2 file download

Next Steps

Pay Workers via Payroll

Run payroll to generate the transactions you’ll reconcile

Payroll Lifecycle

Understand payroll statuses and when invoices become available

Fund Your Account

Ensure your business accounts are funded before running payroll

Webhooks

Get real-time notifications for transaction events

​Prerequisites

​Platform Disbursements

​Query Parameters

​Response Structure

​Transaction Object Fields

​Transaction Types

​Internal Transfers

​Identifying Businesses with tenantKey

​Scope to a Single Business

​Paging through a business’s disbursements

​Payroll Transactions

​Wallet Transactions

​Understanding Amounts

​Cross-Currency Example

​Same-Currency Example

​Revenue Share

​Payroll Fee & Invoice Details

​Getting the Invoice ID

​Pagination

​Reconciliation Walkthrough

​Step 1: Fetch all successful transactions for the period

​Step 2: Group by business

​Step 3: For payroll, identify employees by personId

​Step 4: Calculate revenue share

​Step 5: Get payroll fee details

​Account Statements

​Next Steps

Pay Workers via Payroll

Payroll Lifecycle

Fund Your Account

Webhooks

Prerequisites

Platform Disbursements

Query Parameters

Response Structure

Transaction Object Fields

Transaction Types

Internal Transfers

Identifying Businesses with tenantKey

Scope to a Single Business

Paging through a business’s disbursements

Payroll Transactions

Wallet Transactions

Understanding Amounts

Cross-Currency Example

Same-Currency Example

Revenue Share

Payroll Fee & Invoice Details

Getting the Invoice ID

Pagination

Reconciliation Walkthrough

Step 1: Fetch all successful transactions for the period

Step 2: Group by business

Step 3: For payroll, identify employees by personId

Step 4: Calculate revenue share

Step 5: Get payroll fee details

Account Statements

Next Steps