Transaction Reconciliation

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.

bash

curl -X GET 'https://api.cadanapay.com/v1/platform/disbursements' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Try it in the playground →

Query Parameters

Parameter	Type	Required	Description
`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`.

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
`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

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" }
]

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):

bash

curl -X GET 'https://api.cadanapay.com/v1/payrolls/9c4829a8-0177-4dad-a0d8-e4f8fc42276a' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Try it in the playground →

The response includes the invoiceId once the payroll is in completed status. Then use that ID to fetch the full invoice:

bash

curl -X GET 'https://api.cadanapay.com/v1/invoices/8dbaa174-b5a0-4396-8c87-77e746b50917' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Try it in the playground →

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:

bash

curl -X GET 'https://api.cadanapay.com/v1/invoices/8dbaa174-b5a0-4396-8c87-77e746b50917/url' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Try it in the playground →

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:

bash

curl -X GET 'https://api.cadanapay.com/v1/platform/disbursements' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Reconciliation Walkthrough

Step 1: Fetch all successful transactions for the period

bash

curl -X GET 'https://api.cadanapay.com/v1/platform/disbursements' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Try it in the playground →

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.

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

Get Started

Workforce

White-Label UI

Platform Integration

Payments

Wallets

Global Tax Engine

Embedded Tools

Prerequisites

Platform Disbursements

Query Parameters

Response Structure

Transaction Object Fields

Transaction Types

Identifying Businesses with tenantKey

Payroll Transactions

Wallet Transactions

Understanding Amounts

Cross-Currency Example

Same-Currency Example

Payroll Fee & Invoice Details

Getting the Invoice ID

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 5: Get payroll fee details

Next Steps

Pay Workers via Payroll

Payroll Lifecycle

Fund Your Account

Webhooks

Get Started

Workforce

White-Label UI

Platform Integration

Payments

Wallets

Global Tax Engine

Embedded Tools

​Prerequisites

​Platform Disbursements

​Query Parameters

​Response Structure

​Transaction Object Fields

​Transaction Types

​Identifying Businesses with tenantKey

​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

​Next Steps

Pay Workers via Payroll

Payroll Lifecycle

Fund Your Account

Webhooks

Prerequisites

Platform Disbursements

Query Parameters

Response Structure

Transaction Object Fields

Transaction Types

Identifying Businesses with tenantKey

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

Next Steps