Skip to main content
This guide walks the full lifecycle of paying an independent contractor through Cadana, start to finish. Each step links to a deeper guide for full field references — this page is the map. (Hiring an employee instead? Employees add statutory compliance and a tax profile — see Pay an Employee End-to-End.)

​
Prerequisites

Building against the sandbox first? Read Sandbox & Testing — it covers test funding, KYC sentinel values, and resetting users.

​
Step 1: Onboard the Contractor

Create a Person with type: "CONTRACTOR". Contractors are either individuals or registered businesses — set contractorType accordingly (businessName is required for BUSINESS).
The response is the personId you’ll use in every later step: 
{
  "id": "8ef9a712-cdae-4110-b1ea-9ba95abbee6e"
}
Two things to get right here:
  • Amounts are in minor units — 500000 USD is $5,000.00.
  • compInfo is what payroll pays. For contractors, use type net (or fixed). If pay varies per cycle (hourly work, milestones), set salary.amount to 0 and supply the real amount on each payroll entry in Step 4.
See Onboard Workers for all optional fields (departments, custom fields, metadata).

​
Step 2: Put an Agreement in Place (Optional)

Payroll does not require a contract — but most businesses want one on file. Cadana supports two flows; both attach the agreement to the contractor’s personId. See Manage Contracts for the full lifecycle.
List your contract templates, then create a contract for the contractor. Template variables (name, salary, dates) are filled from the Person record at creation time.Both parties then sign electronically — fetch each signer’s link with GET /v1/contracts/{contractId}/signingUrl and track progress via the contract status (awaiting business signature → awaiting person signature → completed).
The agreement documents the terms; it doesn’t drive payment. Payroll amounts come from the Person’s compInfo (or per-cycle entries), and payroll runs regardless of contract status. Template variables snapshot the Person’s data when the contract is created — updating compInfo later does not update an existing contract.

​
Step 3: Give Them a Wallet

Contractors are paid into a Cadana Global Wallet by default. Provisioning takes two calls — full details in Set Up Worker Wallets. 1. Create a User for the Person. This provisions a wallet in their compensation currency and automatically sets wallet as their preferred payment method: By default the contractor receives a welcome email to set their password. Pass suppressWelcomeEmail: true if you handle login via your own SSO. 2. Submit KYC. The wallet can’t receive funds until identity verification is approved. Upload the ID documents (file upload flow), then submit — issuedBy, frontFileId, and selfieFileId are required: Track approval by polling KYC status or subscribing to the user.kyc.updated webhook. Alternatively, the contractor can complete KYC themselves in the Cadana app after logging in. See KYC Verification for statuses, rejections, and resubmission.
In sandbox, use the sentinel values — idDetails.number: "auto-approve" and address.line2: "auto-approve". Non-sentinel submissions are never resolved; see KYC Testing.
Contractors hired by U.S. businesses also complete a tax form (W-9, W-8BEN, or W-8BEN-E) in the Cadana app alongside KYC — no API work needed on your side. See Tax Forms.
Confirm the wallet is ready:
Skipping the wallet? If direct payouts are enabled for your business, you can pay a contractor’s bank, ACH, or mobile-money account instead — no User account needed. Set it with PUT /v1/persons/{personId}/paymentInfo; see Onboard Workers. Direct methods require enablement by your account manager.

​
Step 4: Run Payroll

Pay the contractor with a one-off contractor payroll — full details in Pay Workers via Payroll. 1. Create the payroll shell: 2. Save the entries. The salary here is what gets paid this cycle (minor units): Saving is asynchronous — poll GET /v1/payrolls/{payrollId} until the status is Pending Submission, then review the calculated debit: the total that will leave your business account, i.e. net pay plus fees. The fee breakdown is on the linked invoice (GET /v1/invoices/{invoiceId}). 3. Approve to trigger fund collection and disbursement: 4. Confirm the money landed. When the payroll reaches Completed, each entry carries transactionIds — resolve them with GET /v1/users/{userId}/transactions/{transactionId} or check the wallet balance. Wallet credits can trail the Completed status by up to a minute.
Distribute earning statements with payslip links, and reconcile fees against the payroll’s invoice.

​
Step 5: The Contractor Gets Their Money

Funds sit in the contractor’s wallet until they’re withdrawn. Two paths:

​
Self-serve (Cadana or white-label app)

The contractor logs in — via the welcome-email credentials or your SSO — and cashes out to a bank account, mobile money, or card in 100+ countries from the app. Nothing to build; brand it with White-Label UI.

​
On their behalf (API)

Your platform can run the payout for them — full details in Payout:
  1. Check the corridor: payment methods for the destination country, field requirements for the details schema, and fees, timelines, and limits.
  2. Create a beneficiary — the saved payment destination.
  3. Get an FX quote. A quote is required even when source and destination currencies are the same (the rate is 1).
  4. Create the transaction. reference is your idempotency key and must be a UUID:
  1. Track the transaction to success, or subscribe to transaction.succeeded / transaction.failed webhooks.
Wallet transaction amounts are decimal strings in major units ("500.00" = $500.00) — unlike the minor-unit integers used by payroll. See Money Amounts.

​
Recap

StepEndpointYou have
OnboardPOST /v1/personspersonId
AgreementPOST /v1/contracts or POST /v1/contracts-uploadsigned agreement on file
WalletPOST /v1/users/invite + POST /v1/users/{userId}/kycuserId, KYC-approved wallet
PayPOST /v1/payrolls → save → approvefunds in the wallet
Cash outself-serve app, or POST /v1/users/{userId}/transactionsfunds at the contractor’s bank

​
Next Steps

Onboard Workers

Full Person field reference

Payroll Lifecycle

All payroll statuses and webhooks

Set Up Worker Wallets

Users, KYC, and wallet details

Payout

Beneficiaries, quotes, and corridors