KYB Requirements

Know Your Business (KYB) verification is required before a business can process payments through Cadana. This page covers all requirements and the verification process.

KYB vs KYC: KYB verifies business entities. KYC verifies individual users. See KYC Verification for user verification.

KYB Process Flow

KYB Statuses

Status	Description	Can Process Payments?
`pending`	KYB not submitted or under review	No
`needs-additional-info`	Review complete, more information required	No
`rejected`	Business verification rejected (terminal)	No
`completed`	Business verified	Yes

Submit KYB

You can submit KYB in two ways:

Hosted form — generate a branded link and send it to your customer. The business owner completes KYB through a hosted UI — no need to build your own collection form.
API submission — collect the verification data in your own UI and submit it directly via API.

Hosted KYB Form

If you prefer to delegate KYB data collection to the business owner, generate a hosted form link and share it with them. The business owner visits the link and completes verification through a branded UI. Response:

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "url": "https://app.cadanapay.com/kyb/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "expiresAt": 1765459752
}

Field	Description
`id`	Unique identifier for the KYB link
`url`	The hosted form URL — send this to the business owner
`expiresAt`	Unix timestamp when the link expires

The link has an expiration. If the business owner visits an expired link, they are redirected to your refreshURL where you can generate a new link.

Webhook events (business.kyb.reviewed, business.kyb.completed) work the same regardless of whether KYB was submitted via the hosted form or the API.

API Submission

Submit business and principal information for verification. You can submit all data at once or start with a partial submission and add more information later using the PATCH endpoint.

Incremental submission: You can start with just the business name and address, then use PATCH /v1/businesses/{businessId}/kyb to add more fields over time. KYB moves to review once all requirements are met.

Returns 204 on success. The business is now under review.

Updating KYB Information

Use PATCH to add or correct fields after the initial submission. Only the fields you include are updated — everything else is left unchanged. Document arrays (articlesOfIncorporation, bankStatements, etc.) are appended to, not replaced.

When updating principals in a PATCH request, you must include the principal’s id (returned from the initial submission or GET). This ensures you’re updating the correct principal rather than creating a new one.

PATCH is also how you respond after a review returns needs-additional-info. Parse the currentlyDue array from the business.kyb.reviewed webhook, collect the required data or documents, and PATCH them in. The status automatically moves back to review once all requirements are satisfied.

You cannot PATCH while the KYB is in pending (under review) or completed status.

Business Requirements

Requirement	API Field	Rules
Legal business name	`entityName`	Must exactly match the registered name on government records
Entity type	`entityType`	`corporation`, `c-corporation`, `s-corporation`, `partnership`, `sole proprietorship`, `limited liability company`, `non profit`, `other`
Business address	`address`	Must be a valid physical address; PO Boxes not allowed
Phone number	`phoneNumber`	Must be a reachable business phone
EIN / Tax ID	`taxIdentificationNumber`	Must be a valid IRS-issued EIN
Incorporation address	`incorporation.address`	Must match corporate records
Incorporation date	`incorporation.date`	Must be a valid date
Website URL	`websiteURL`	Must be a valid website

Principal / UBO Requirements

You must provide information for individuals who:

Own 25% or more of the business (ownershipPercentage >= 0.25), or
Hold significant managerial responsibility (isExecutive: true)

At least one executive/representative is required.

Requirement	API Field	Rules
First name	`principals[].firstName`	Must match ID document
Last name	`principals[].lastName`	Must match ID document
Date of birth	`principals[].dateOfBirth`	Must be valid and 18+
Email	`principals[].email`	Valid email address
Phone number	`principals[].phoneNumber`	Reachable phone
Residential address	`principals[].address`	Physical address; PO Boxes not allowed
Identifier	`principals[].identifier`	Type: `ssn` or `passport`
Ownership %	`principals[].ownershipPercentage`	0-1 scale (1 = 100%)
Executive flag	`principals[].isExecutive`	Required for control person
Executive title	`principals[].title`	Required for control person
ID document (front)	`principals[].identityFileId`	Required if SSN verification fails
ID document (back)	`principals[].identityBackPageFileId`	Required if SSN verification fails
Address proof	`principals[].addressFileId`	Required if address verification fails

Upload documents using the file upload flow and pass the returned fileId values.

Required Documents (Conditional)

These documents are only required when automated verification fails.

Verification failure	Required upload	Accepted documents
EIN / Tax ID unverified	`taxDocuments`	IRS EIN confirmation letter (SS-4 or 147C) — must show exact legal name + EIN
Business registration mismatch	`articlesOfIncorporation`	Articles of Incorporation or Certificate of Formation
Business address unverified	`proofOfAddress`	Utility bill, lease, or bank statement
Principal identity unverified	`principals[].identityFileId` and `principals[].identityBackPageFileId`	Government-issued photo ID (front and back)
Principal address unverified	`principals[].addressFileId`	Utility bill, lease, or bank statement
Compliance review	`bankStatements`	Recent bank statements (if requested by Compliance)

Webhook Events

business.kyb.reviewed

Sent after KYB has been reviewed. May indicate approval or that additional information is needed.

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "eventType": "business.kyb.reviewed",
  "version": "1.0",
  "timestamp": 1765359752,
  "data": {
    "tenantKey": "cad95193904",
    "status": "needs-additional-info",
    "businessId": "7dd569f9-bd54-4fbb-a5c2-f0aaadc68adf",
    "businessName": "Acme Corporation",
    "requirements": {
      "currentlyDue": [
        "principals.0.firstName",
        "principals.0.documentsRequired.identityFileId",
        "entityName"
      ],
      "errors": [
        {
          "field": "entityName",
          "reason": "Only english letters are allowed"
        },
        {
          "field": "principals.0.firstName",
          "reason": "Name doesn't match ID document"
        }
      ]
    }
  }
}

Field	Description
`status`	Current KYB status
`requirements.currentlyDue`	Fields that need to be submitted or corrected
`requirements.errors`	Specific validation errors with reasons

When you receive needs-additional-info:

Parse the currentlyDue array to identify required fields
Check errors array for specific issues
Collect the required information/documents from the business owner
Resubmit KYB with corrected data

business.kyb.rejected

Sent when a KYB submission has been permanently rejected. This is a terminal state — the business cannot resubmit.

{
  "id": "c3d4e5f6-a7b8-9012-cdef-345678901234",
  "eventType": "business.kyb.rejected",
  "version": "1.0",
  "timestamp": 1765359752,
  "data": {
    "id": "7dd569f9-bd54-4fbb-a5c2-f0aaadc68adf",
    "businessName": "Acme Corporation",
    "reason": "Business does not meet compliance requirements",
    "status": "rejected",
    "tenantKey": "cad95193904",
    "timestamp": 1765359752
  }
}

business.kyb.completed

Sent when business verification is successful. After receiving this event, the business can process payments.

{
  "id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
  "eventType": "business.kyb.completed",
  "version": "1.0",
  "timestamp": 1765359752,
  "data": {
    "businessId": "7dd569f9-bd54-4fbb-a5c2-f0aaadc68adf",
    "businessName": "Acme Corporation",
    "status": "completed",
    "tenantKey": "cad95193904"
  }
}

See Events for all event types and Webhooks to configure your endpoint.

Timeline

Step	Duration
Submit KYB	Immediate
Review (once all requirements provided)	Up to 3 business days

Sandbox Testing

Use test values to simulate different KYB outcomes without waiting for real verification.

Test value	Field	Result
`000-CAD-AUTO-APPROVE`	`taxIdentificationNumber`	KYB automatically approved
`000-CAD-AUTO-REJECT`	`taxIdentificationNumber`	KYB automatically rejected (terminal)
`000-CAD-AUTO-FLAG`	`taxIdentificationNumber`	Status set to `needs-additional-info`, requests all business documents
`000-11-2222`	`principals[].identifier.value` (SSN)	Requires identity documents and address files for the principal
`000-11-3333`	`principals[].identifier.value` (SSN)	Status set to `needs-additional-info`, principal receives KYC requirement email

These test values only work in the sandbox environment and are silently ignored in production.

See Sandbox & Testing for all test values.

Next Steps

KYC Verification

User identity verification

Multi-Tenant Setup

Platform integration guide

Webhooks

Configure webhook endpoints

Sandbox & Testing

Test values and simulated scenarios

Get Started

Workforce Management

Payroll & Compliance

White-Label UI

Platform Integration

Payments

Wallets

KYB Process Flow

KYB Statuses

Submit KYB

Hosted KYB Form

API Submission

Updating KYB Information

Business Requirements

Principal / UBO Requirements

Required Documents (Conditional)

Webhook Events

business.kyb.reviewed

business.kyb.rejected

business.kyb.completed

Timeline

Sandbox Testing

Next Steps

KYC Verification

Multi-Tenant Setup

Webhooks

Sandbox & Testing

Get Started

Workforce Management

Payroll & Compliance

White-Label UI

Platform Integration

Payments

Wallets

​KYB Process Flow

​KYB Statuses

​Submit KYB

​Hosted KYB Form

​API Submission

​Updating KYB Information

​Business Requirements

​Principal / UBO Requirements

​Required Documents (Conditional)

​Webhook Events

​business.kyb.reviewed

​business.kyb.rejected

​business.kyb.completed

​Timeline

​Sandbox Testing

​Next Steps

KYC Verification

Multi-Tenant Setup

Webhooks

Sandbox & Testing

KYB Process Flow

KYB Statuses

Submit KYB

Hosted KYB Form

API Submission

Updating KYB Information

Business Requirements

Principal / UBO Requirements

Required Documents (Conditional)

Webhook Events

business.kyb.reviewed

business.kyb.rejected

business.kyb.completed

Timeline

Sandbox Testing

Next Steps