Platform APIs for interacting with businesses
openapi: 3.0.0
info:
description: APIs for interacting with Cadana Embedded Consumer Wallets
version: 1.0.0
title: Embedded Consumer Wallets Balances Platform API
termsOfService: https://cadanapay.com/terms-and-conditions
contact:
email: api@cadanapay.com
license:
name: Apache 2.0
url: http://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: https://api.cadanapay.com
description: Prod Server
- url: https://dev-api.cadanapay.com
description: Dev Server
security:
- Authorization: []
tags:
- name: Platform
description: Platform APIs for interacting with businesses
paths:
/v1/platform/businesses:
post:
summary: Create
description: Create a business
operationId: createBusiness
tags:
- Platform
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateBusinessRequest'
responses:
'200':
$ref: '#/components/responses/CreateBusinessResponse'
'400':
$ref: '#/components/responses/BadRequestError'
5XX:
$ref: '#/components/responses/InternalError'
security:
- Authorization: []
get:
summary: List
description: Fetch all businesses
operationId: retrieveBusinesses
tags:
- Platform
parameters:
- in: query
name: idempotencyKey
schema:
type: string
description: Idempotency key of a business
- in: query
name: next
schema:
type: string
description: Query next set of results based on limit
- in: query
name: previous
schema:
type: string
description: Query previous set of results based on limit
- in: query
name: limit
schema:
type: integer
minimum: 1
default: 20
maximum: 100
description: Maximum number of items to return per page
responses:
'200':
$ref: '#/components/responses/GetBusinessesResponse'
'400':
$ref: '#/components/responses/BadRequestError'
security:
- Authorization: []
/v1/platform/disbursements:
get:
summary: List Disbursements
description: Retrieve all disbursements across all businesses under the platform. Use this endpoint for financial reconciliation across your sub-businesses.
operationId: getPlatformDisbursements
tags:
- Platform
parameters:
- in: query
name: businessId
schema:
type: string
format: uuid
description: 'Scope results to a single business account. Returns only rows 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). This is narrower than `tenantKey`, which returns every row under a tenant.
'
example: 1e6c5a83-7b86-4a32-a7da-0e5e2b3d8f10
- in: query
name: currency
schema:
type: string
description: Filter by the business-facing currency — matches either the destination `amount` or the `sourceAmount`.
example: USD
- in: query
name: startDate
schema:
type: string
format: date
description: Start of date range (ISO 8601, e.g. 2026-01-01). Defaults to 7 days ago.
- in: query
name: endDate
schema:
type: string
format: date
description: End of date range (ISO 8601, e.g. 2026-02-01). Defaults to now.
- in: query
name: type
schema:
type: string
description: 'Comma-separated, repeatable filter of disbursement type(s) to include. Supported values: PAYROLL, PAYOUT, TRANSFER, CARD_MAINTENANCE_FEE, CARD_CREATION_FEE, STOCK_BUY, STOCK_SELL, PAYROLL_FEE, INTEREST. When scoped to a single business with `businessId`, the business-relevant types are PAYROLL_TOTAL, PAYROLL, PAYROLL_FEE, PAYROLL_REVERSAL, DEPOSIT, DEPOSIT_REVERSAL, VENDOR, REVENUE_SHARE_PAYOUT, REIMBURSEMENT, SUBSCRIPTION_PAYMENT, STATUTORY_DEPOSIT; by default the per-employee PAYROLL legs and PAYROLL_FEE are collapsed into the single PAYROLL_TOTAL row, and passing an explicit `type` returns the raw rows.
'
example: PAYROLL,PAYOUT
- in: query
name: status
schema:
type: string
enum:
- SUCCESS
- FAILED
- INITIATED
- PROCESSING
- ROUTED
description: Filter by transaction status.
example: SUCCESS
- in: query
name: includeRevenueShare
schema:
type: boolean
default: false
description: Set to `true` to include the revenue-share fields (`feeRevenueShare`, `fxRevenueShare`, `totalRevenueShare`) in each item. Omitted by default.
example: true
- in: query
name: limit
schema:
type: integer
minimum: 1
default: 50
maximum: 100
description: Maximum number of items to return per page.
- in: query
name: next
schema:
type: string
description: Opaque cursor for the next page — pass the `cursor.next` value from the previous response. Keep paging until `cursor.next` is null.
- in: query
name: previous
schema:
type: string
description: Cursor to fetch the previous page of results.
responses:
'200':
$ref: '#/components/responses/GetPlatformDisbursementsResponse'
'400':
$ref: '#/components/responses/BadRequestError'
5XX:
$ref: '#/components/responses/InternalError'
security:
- Authorization: []
/v1/platform/disbursements/{disbursementId}:
get:
summary: Get Disbursement
description: Fetch a single disbursement by ID.
operationId: getPlatformDisbursement
tags:
- Platform
parameters:
- $ref: '#/components/parameters/disbursementId'
responses:
'200':
$ref: '#/components/responses/GetPlatformDisbursementResponse'
'400':
$ref: '#/components/responses/BadRequestError'
'404':
$ref: '#/components/responses/NotFoundError'
5XX:
$ref: '#/components/responses/InternalError'
security:
- Authorization: []
/v1/platform/transfers:
post:
summary: Create Transfer
description: 'Move money between your own business accounts — your main business and
its child businesses — internally and same-currency only. Settles
immediately with no fee.
Set `sourceTenantKey` to the business funds move from (omit it to send
from your main business) and `destinationTenantKey` to the business they
move to. Allowed movements are main → child, child → child, and
child → main.
There is no `GET` for a transfer — track it via the
[platform disbursements endpoint](/api-reference/workforce/platform/list-disbursements)
filtered to `type=TRANSFER`, matching the returned `id` or your `reference`.
'
operationId: createPlatformTransfer
tags:
- Platform
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateTransferRequest'
examples:
transferRequest:
summary: Example transfer request
value:
sourceTenantKey: blm123456
destinationTenantKey: blm998877
amount:
amount: 500000
currency: USD
reference: transfer-123
responses:
'200':
$ref: '#/components/responses/CreatePlatformTransferResponse'
'400':
$ref: '#/components/responses/BadRequestError'
'403':
$ref: '#/components/responses/ForbiddenError'
5XX:
$ref: '#/components/responses/InternalError'
security:
- Authorization: []
/v1/permissions/roles:
get:
summary: Custom Roles
description: Get Custom Roles
operationId: getRoles
tags:
- Platform
responses:
'200':
$ref: '#/components/responses/GetPermissionRolesResponse'
5XX:
$ref: '#/components/responses/InternalError'
security:
- Authorization: []
parameters:
- $ref: '#/components/parameters/XMultiTenantKey'
components:
schemas:
PlatformDisbursement:
type: object
properties:
id:
type: string
format: uuid
description: Unique transaction identifier
example: 87eec1a4-d757-45be-a75e-f3638d044750
tenantKey:
type: string
description: Identifies which business this transaction belongs to
example: tbl28153208
status:
type: string
description: Transaction status
enum:
- SUCCESS
- FAILED
- INITIATED
- PROCESSING
- ROUTED
example: SUCCESS
referenceId:
type: string
format: uuid
description: External reference ID. Payroll transactions from the same run share the same referenceId.
example: 9c4829a8-0177-4dad-a0d8-e4f8fc42276a
description:
type: string
description: Human-readable description of the transaction
example: January 2026 Payment
type:
type: string
description: 'Transaction type. The possible values depend on the endpoint — see the operation description for the set each endpoint returns. A business disbursement is one of: PAYROLL_TOTAL, PAYROLL, PAYROLL_FEE, PAYROLL_REVERSAL, DEPOSIT, DEPOSIT_REVERSAL, VENDOR, REVENUE_SHARE_PAYOUT, REIMBURSEMENT, SUBSCRIPTION_PAYMENT, STATUTORY_DEPOSIT.
'
enum:
- PAYOUT
- PAYROLL
- PAYROLL_TOTAL
- PAYROLL_FEE
- PAYROLL_REVERSAL
- VENDOR
- DEPOSIT
- DEPOSIT_REVERSAL
- REVENUE_SHARE_PAYOUT
- REIMBURSEMENT
- SUBSCRIPTION_PAYMENT
- STATUTORY_DEPOSIT
- CARD_MAINTENANCE_FEE
- CARD_CREATION_FEE
- STOCK_BUY
- STOCK_SELL
- INTEREST
example: PAYROLL_TOTAL
fxRate:
type: number
nullable: true
description: Foreign exchange rate applied. Only present for cross-currency transactions.
example: 5.7896
paymentMethod:
type: string
description: How funds were delivered
enum:
- bank
- momo
- wallet
- ach
- card
- proxy
example: bank
paymentDetails:
$ref: '#/components/schemas/paymentMethods'
userId:
type: string
format: uuid
description: The wallet/user account ID. Present on wallet-based transactions. For payroll, only present when payment is delivered to a wallet.
example: 8cb1d569-5dfd-4b33-b25e-4fab0ee14251
personId:
type: string
format: uuid
nullable: true
description: The employee or contractor ID. Present only on payroll transactions.
example: 7fc25070-8037-44f8-8c42-9d05ffc01f0b
userName:
type: string
description: Recipient name
example: Paula Torres
amount:
description: Amount the recipient receives in the destination currency
allOf:
- $ref: '#/components/schemas/Amount'
sourceAmount:
description: Cost in the source currency before fees
allOf:
- $ref: '#/components/schemas/Amount'
feeAmount:
description: Fees charged in the source currency
allOf:
- $ref: '#/components/schemas/Amount'
totalAmount:
description: Total debited from the sender (sourceAmount + feeAmount)
allOf:
- $ref: '#/components/schemas/Amount'
fxRevenueShare:
nullable: true
description: Revenue earned from the FX spread. Only present when applicable.
allOf:
- $ref: '#/components/schemas/RevenueShare'
feeRevenueShare:
nullable: true
description: Revenue earned from transaction fees. Only present when applicable.
allOf:
- $ref: '#/components/schemas/RevenueShare'
totalRevenueShare:
nullable: true
description: Combined total revenue share
allOf:
- $ref: '#/components/schemas/Amount'
estimatedDelivery:
type: string
nullable: true
description: Estimated time the funds will be delivered to the recipient
externalReference:
type: string
nullable: true
description: External reference associated with the transaction, when available
createdTimestamp:
type: string
description: Timestamp when the transaction was created
example: 2026-01-28 14:29:09 +0000 UTC
lastUpdatedTimestamp:
type: string
description: Timestamp when the transaction was last updated
example: 2026-01-28 14:29:18 +0000 UTC
operation:
type: object
properties:
description:
type: string
example: Operations related to user management
description: Operations tied to the role
permissions:
type: array
items:
$ref: '#/components/schemas/permission'
resource:
type: string
description: The domain for the operations
example: user
businessMinimalDetailsEntry:
properties:
id:
$ref: '#/components/schemas/uuid'
name:
type: string
example: Wayne Enterprise
shortName:
type: string
example: W.E.
status:
type: string
description: Business status. `pending_verification` until KYB is approved, then `ACTIVE`.
enum:
- ACTIVE
- pending_verification
- CLOSED
example: ACTIVE
tenantKey:
type: string
example: abc123
country:
type: string
example: US
address:
$ref: '#/components/schemas/address'
requiresKYB:
type: boolean
description: Whether the business must complete KYB before processing payments
example: true
admin:
type: object
properties:
name:
type: string
example: Jane Founder
email:
type: string
example: jane@example.com
createdTimestamp:
type: integer
description: Unix timestamp when the business was created
example: 1765359752
idempotencyKey:
type: string
description: Idempotency key supplied when the business was created
example: b6ae5da9-6342-4a58-bd50-8564d68d3f7e
swiftDetails:
type: object
required:
- currency
- iban
- accountName
- accountNumber
- bankName
- swiftCode
- address
properties:
currency:
type: string
description: The currency of the bank account
example: EUR
iban:
type: string
description: The International Bank Account Number
example: DE00000000000000000000
accountName:
type: string
description: The name on the bank account
example: John Doe
accountNumber:
type: string
description: The bank account number
example: '1234567890'
bankName:
type: string
description: The name of the bank
example: Example Bank
swiftCode:
type: string
description: The SWIFT/BIC code of the bank
example: EXMPDEFF
address:
$ref: '#/components/schemas/address'
permission:
type: object
properties:
action:
type: string
description: The specific permission for the role
example: CAN_VIEW_USER
value:
type: boolean
example: true
role:
type: object
properties:
description:
type: string
description: A custom role that can be attached to a user
example: This is the role for a finance manager
id:
$ref: '#/components/schemas/uuid'
name:
type: string
example: Finance Manager
operations:
type: array
items:
$ref: '#/components/schemas/operation'
roleType:
type: string
example: custom
CreateTransferRequest:
type: object
required:
- destinationTenantKey
- amount
- reference
properties:
sourceTenantKey:
type: string
description: The business funds move from. Omit to send from your main business, or pass a child business's tenant key.
example: blm123456
destinationTenantKey:
type: string
description: The business funds move to — a child business or your main business. Cannot equal the source.
example: blm998877
amount:
type: object
required:
- amount
- currency
properties:
amount:
type: integer
description: Value in the lowest denomination of the currency (e.g. cents)
example: 500000
currency:
type: string
description: ISO 4217 code. Source and destination must match — cross-currency is not supported.
example: USD
reference:
type: string
description: Your client reference for the transfer. Stored on it so you can locate it later.
example: transfer-123
phoneNumber:
type: object
description: Person's phone number
properties:
countryCode:
type: string
example: '1'
number:
type: string
example: '2345678901'
uuid:
type: string
format: uuid
example: 8ef9a712-cdae-4110-b1ea-9ba95abbee6e
NotFoundError:
description: Not Found
allOf:
- $ref: '#/components/schemas/Error'
example:
code: resource_not_found
message: Requested resource could not be found.
walletDetails:
type: object
properties:
type:
type: string
description: The type of wallet account
enum:
- user
- business
example: user
identifier:
type: string
description: The unique identifier for the wallet account
example: 69a2a928-ed49-4e53-92ec-a72b4ee7eacc
currency:
type: string
description: The currency of the wallet
example: USD
InternalError:
description: Internal server error
allOf:
- $ref: '#/components/schemas/Error'
example:
code: internal_error
message: An unexpected error occurred. Please try again later.
CreateBusinessRequest:
description: Create business request payload
type: object
required:
- businessName
- adminFirstName
- adminLastName
- address
- adminEmail
- idempotencyKey
- country
properties:
businessName:
type: string
description: Business name
example: Wayne Enterprise
businessShortName:
type: string
example: W.E.
description: Shortname of the business
adminFirstName:
type: string
example: Jane
description: First name of the admin of the business
adminLastName:
type: string
example: Founder
description: Last name of the admin of the business
address:
$ref: '#/components/schemas/address'
adminEmail:
type: string
description: Person's email
example: admin@example.com
suppressWelcomeEmail:
type: boolean
description: Whether you want to suppress the welcome email
default: false
registrationId:
type: string
description: Registration id/number of the business
example: '991234567'
idempotencyKey:
type: string
description: Unique string to prevent dedupe
example: b6ae5da9-6342-4a58-bd50-8564d68d3f7e
country:
type: string
example: US
adminPhoneNumber:
$ref: '#/components/schemas/phoneNumber'
BadRequestError:
description: Bad input provided by client
allOf:
- $ref: '#/components/schemas/Error'
- type: object
properties:
params:
description: A map for meta data around the error that occurred
type: object
example:
code: invalid_request_body
message: The request body provided is not valid
params:
field: Value is invalid.
nodePagination:
type: object
description: Node pagination
properties:
next:
type: string
previous:
type: string
ForbiddenError:
description: Forbidden
allOf:
- $ref: '#/components/schemas/Error'
example:
code: forbidden
message: Transfers are only available to platform businesses.
beneficiaryId:
type: object
description: ID details for the beneficiary
properties:
type:
type: string
enum:
- NIT
- CC
- CE
- TI
- PASS
description: Type of beneficiary ID
example: NIT
value:
type: string
description: ID number of the beneficiary
example: '123456789'
Amount:
type: object
required:
- value
- currency
properties:
value:
type: string
description: The value of the amount
example: '10.00'
currency:
type: string
description: The currency of the asset
example: USD
wireDetails:
type: object
description: Wire transfer payment details
properties:
bankName:
type: string
description: The name of the bank
example: Example Bank
accountName:
type: string
description: The name on the account
example: John Doe
routingNumber:
type: string
description: The routing number
example: '000000000'
accountNumber:
type: string
description: The account number
example: '123456789'
address:
$ref: '#/components/schemas/address'
node:
type: object
description: Node pagination
properties:
previous:
type: string
nullable: true
next:
type: string
nullable: true
paymentMethods:
type: object
required:
- preferredMethod
properties:
preferredMethod:
type: string
enum:
- momo
- bank
- swift
- ach
- wallet
- wire
description: The preferred payment method type
example: bank
momo:
$ref: '#/components/schemas/momoDetails'
bank:
$ref: '#/components/schemas/bankDetails'
swift:
$ref: '#/components/schemas/swiftDetails'
ach:
$ref: '#/components/schemas/achDetails'
wallet:
$ref: '#/components/schemas/walletDetails'
wire:
$ref: '#/components/schemas/wireDetails'
bankDetails:
type: object
properties:
accountName:
type: string
description: The name on the bank account
example: John Doe
accountNumber:
type: string
description: The bank account number
example: '1234567890'
accountType:
type: string
description: The type of bank account (e.g., Checking, Savings)
example: Checking
ownerType:
type: string
description: The type of account owner
enum:
- Individual
- Business
example: Individual
bankCode:
type: string
description: The bank identification code
example: EXMPJPJT
bankName:
type: string
description: The name of the bank
example: Gotham City Bank
branchName:
type: string
description: The name of the bank branch
example: Downtown Branch
sortCode:
type: string
description: The bank sort code (UK); carries the IFSC for India
example: '401234'
iban:
type: string
description: The International Bank Account Number
example: GB00000000000000000000
provider:
type: string
description: The platform providing this account (e.g., wise)
example: wise
currency:
type: string
description: The currency of the bank account
example: USD
beneficiaryId:
$ref: '#/components/schemas/beneficiaryId'
address:
$ref: '#/components/schemas/address'
phoneNumber:
$ref: '#/components/schemas/phoneNumber'
email:
type: string
format: email
description: The email address of the account holder
example: john.doe@example.com
momoDetails:
type: object
properties:
accountName:
type: string
description: The name associated with the mobile money account
example: John Doe
provider:
type: string
description: The name of the mobile money provider
example: MTN
providerCode:
type: string
description: The code identifying the mobile money provider
example: MTN
phoneNumber:
$ref: '#/components/schemas/phoneNumber'
currency:
type: string
description: The currency of the mobile money account
example: GHS
achDetails:
type: object
properties:
bankName:
type: string
description: The name of the bank
example: Example Bank
accountName:
type: string
description: The name on the bank account
example: John Doe
routingNumber:
type: string
description: The ACH routing number of the bank
example: '000000000'
accountNumber:
type: string
description: The bank account number
example: '1234567890'
accountType:
type: string
description: The type of bank account (Checking or Savings)
example: Checking
provider:
type: string
description: The platform providing this account (e.g., wise)
example: wise
address:
$ref: '#/components/schemas/address'
RevenueShare:
type: object
properties:
amount:
$ref: '#/components/schemas/Amount'
rate:
type: number
description: The revenue share percentage
example: 1.0
address:
type: object
description: Address
required:
- countryCode
properties:
line1:
type: string
example: Street 1
line2:
type: string
example: Apt 1
city:
type: string
example: Gotham
postalCode:
type: string
example: '10001'
state:
type: string
example: NY
countryCode:
type: string
example: US
Error:
type: object
properties:
code:
description: A machine parsable error code
type: string
enum:
- invalid_request_body
- resource_not_found
- forbidden
- internal_error
message:
description: A human readable message describing the error
type: string
responses:
InternalError:
description: Internal error
content:
application/json:
schema:
$ref: '#/components/schemas/InternalError'
NotFoundError:
description: Requested resource was not found
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundError'
GetPermissionRolesResponse:
description: get permission roles response
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/role'
GetPlatformDisbursementResponse:
description: Disbursement details
content:
application/json:
schema:
$ref: '#/components/schemas/PlatformDisbursement'
CreateBusinessResponse:
description: get user kyc response
content:
application/json:
schema:
type: object
properties:
businessId:
$ref: '#/components/schemas/uuid'
tenantKey:
type: string
example: biz123456
GetPlatformDisbursementsResponse:
description: List of disbursements across all platform businesses
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/PlatformDisbursement'
cursor:
$ref: '#/components/schemas/node'
examples:
payrollAndPayout:
$ref: '#/components/examples/platformDisbursementsResponse'
ForbiddenError:
description: The caller is not permitted to perform this action
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
GetBusinessesResponse:
description: get businesses response
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/businessMinimalDetailsEntry'
node:
$ref: '#/components/schemas/nodePagination'
CreatePlatformTransferResponse:
description: Transfer created response
content:
application/json:
schema:
type: object
properties:
id:
type: string
format: uuid
description: The transfer id. Track it via the platform disbursements endpoint filtered to `type=TRANSFER`.
example: 9b2c1f47-8a0d-4e21-bf3c-2d6f1a9e74c5
examples:
transfer:
summary: Example transfer creation response
value:
id: 9b2c1f47-8a0d-4e21-bf3c-2d6f1a9e74c5
BadRequestError:
description: Bad input provided by client
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestError'
parameters:
disbursementId:
name: disbursementId
in: path
description: The unique identifier for the disbursement
required: true
schema:
type: string
format: uuid
XMultiTenantKey:
name: X-MultiTenantKey
in: header
required: false
schema:
type: string
description: Required when using a Platform API token. The tenant key identifying which business to operate on.
examples:
platformDisbursementsResponse:
summary: Platform Disbursements Response
value:
data:
- id: c62
# --- truncated at 32 KB (34 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/cadana/refs/heads/main/openapi/cadana-platform-api-openapi.yml