Skip to main content
A User is a Cadana account for an existing Person. Creating a User provisions a Global Wallet that the worker can use to receive payments, access self-service features, and manage their funds.

​
Prerequisites

1

API key from Dashboard

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

Existing Person record

The worker must already be onboarded as a Person. See Onboard Workers.

​
Step 1: Create a User

Invite the worker to Cadana by creating a User linked to their Person record. This provisions a wallet in their compensation currency.
bash
curl -X POST 'https://api.cadanapay.com/v1/users/invite' \
  -H 'Authorization: Bearer YOUR_API_KEY'
Response: 
{
  "userId": "3a1b2c3d-4e5f-6789-abcd-ef0123456789"
}
By default, the worker receives a welcome email with instructions to set up their password and log into the Cadana app. Pass returnLink: true to receive the worker’s unique onboarding URL in the response. This is useful when you want to send it through a custom channel.
bash
curl -X POST 'https://api.cadanapay.com/v1/users/invite' \
  -H 'Authorization: Bearer YOUR_API_KEY'
Response: 
{
  "userId": "3a1b2c3d-4e5f-6789-abcd-ef0123456789",
  "inviteLink": "https://app.cadanapay.com/login?auth=..."
}
The inviteLink is also returned when suppressWelcomeEmail is true, even without setting returnLink.
Using custom authentication? Pass "suppressWelcomeEmail": true to skip the welcome email and password setup. You’ll handle login via your own SSO flow instead. See Custom Authentication.

​
Step 2: KYC Verification

Before the wallet can be fully functional, the worker must complete identity verification (KYC). There are two ways to do this:

​
Option A: Worker self-service

The worker completes KYC themselves through the Cadana app or your white-label UI after logging in.

​
Option B: Submit KYC via API

You can submit KYC on behalf of the worker directly through the API. This is useful when you’ve already collected identity documents during your own onboarding flow.
bash
curl -X POST 'https://api.cadanapay.com/v1/users/3a1b2c3d-4e5f-6789-abcd-ef0123456789/kyc' \
  -H 'Authorization: Bearer YOUR_API_KEY'
Returns 204 on success — the submission is sent for verification.
Upload identity documents first using the file upload flow, then pass the returned fileId values as frontFileId, backFileId, or selfieFileId in idDetails.

​
Check KYC status

Poll the KYC endpoint or listen for the user.kyc.updated webhook event to track verification progress:
bash
curl -X GET 'https://api.cadanapay.com/v1/users/3a1b2c3d-4e5f-6789-abcd-ef0123456789/kyc' \
  -H 'Authorization: Bearer YOUR_API_KEY'
Response: 
{
  "idDetails": {
    "country": "NG",
    "type": "Passport"
  },
  "identity": "approved",
  "address": "approved",
  "firstName": "John",
  "lastName": "Doe"
}
Sandbox behavior: In sandbox mode, KYC is automatically approved. A user can complete KYC immediately without waiting for verification.
For details on what’s required, see KYC Verification.

​
Tax Forms (U.S. Businesses)

Contractors hired by U.S. businesses are also required to complete and sign a tax form (W-9, W-8BEN, or W-8BEN-E) as part of wallet onboarding. The contractor completes this through the Cadana app alongside KYC — no API integration needed. You can retrieve and download completed forms via the API. See Tax Forms.

​
Wallet Payment Method

When you create a User for a Person, the platform automatically sets wallet as the preferred payment method. No additional API call is needed — payroll disbursements will go to the worker’s Cadana wallet by default. You can verify this by checking the Person’s payment info:
bash
curl -X GET 'https://api.cadanapay.com/v1/persons/8ef9a712-cdae-4110-b1ea-9ba95abbee6e/paymentInfo' \
  -H 'Authorization: Bearer YOUR_API_KEY'
If you need to switch the worker to a different payment method (bank transfer, mobile money, etc.), use PUT /v1/persons/{personId}/paymentInfo. See Onboard Workers for details.

​
Check Wallet Balance

Retrieve a worker’s wallet balances. A worker can hold balances in multiple currencies.
bash
curl -X GET 'https://api.cadanapay.com/v1/users/3a1b2c3d-4e5f-6789-abcd-ef0123456789/balances' \
  -H 'Authorization: Bearer YOUR_API_KEY'
Response: 
{
  "data": [
    {
      "id": "517075a2-17db-469f-9481-eb8347cb920c",
      "currency": "USD",
      "balance": 703448,
      "available": 703448,
      "processing": 0
    }
  ]
}
FieldDescription
currencyWallet currency
balanceTotal balance in lowest denomination (cents)
availableAmount available for withdrawal
processingAmount currently being processed (e.g. pending withdrawals)

​
Managing Users

OperationEndpointDescription
List usersGET /v1/usersFilter by personId or email
Get userGET /v1/users/{userId}Retrieve user details and status
See the Workforce API Reference for full request and response schemas.

​
Next Steps

Pay Workers via Payroll

Pay workers into their wallets

KYC Verification

How identity verification works

Tax Forms

W-9 and W-8 forms for U.S. business contractors

Custom Authentication

Integrate your own SSO for worker login

Wallets API Reference

Full wallet endpoint documentation