KYB Requirements - Cadana Developers

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?
`initialized`	KYB record created (e.g. by generating a hosted link), nothing submitted yet	No
`incomplete`	Partially submitted — required fields are still outstanding (see `requirements.currentlyDue`)	No
`pending-review`	All requirements submitted, under review	No
`awaiting-principal-kyc`	Submitted, waiting on one or more principals to complete identity verification	No
`needs-additional-info`	Review complete, more information required	No
`rejected`	Business verification rejected (terminal)	No
`complete`	Business verified	Yes

Before the first submission (or hosted-link generation), GET /v1/businesses/{businessId}/kyb returns 404.

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/onboarding/business/?token=eyJhbGciOi...",
  "expiresAt": 1765459752
}

Field	Description
`id`	Unique identifier for the KYB link
`url`	The hosted form URL — send this to the business owner. White-label platforms get the link on their own domain.
`expiresAt`	Unix timestamp when the link expires

Links expire 6 hours after creation (expiresAt). If the business owner visits an expired link, they are redirected to your refreshURL where you can generate a new link. Progress is saved as the owner completes each step, so a new link resumes where they left off.

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 and submit the rest over time. The status stays incomplete — with the outstanding fields listed in requirements.currentlyDue — until all requirements are met, then moves to pending-review. Use PATCH /v1/businesses/{businessId}/kyb to fill in scalar fields, but note that PATCH cannot add principals — to add a principal, re-POST the full submission (allowed while the status is initialized, incomplete, awaiting-principal-kyc, or needs-additional-info). A re-POST replaces the entire principal list.

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 GET KYB). PATCH can only update existing principals — a principal with an unknown id is silently ignored (the request still returns 204), and PATCH cannot add new principals. To add a principal, re-POST the full submission.

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 POST or PATCH while the KYB is in pending-review, complete, or rejected status — the request returns 400.

Check KYB Status

Retrieve the full KYB record at any time, including the current status and any outstanding requirements. requirements.currentlyDue lists the exact field paths still needed — the same paths used in the business.kyb.reviewed webhook — so you can poll this endpoint instead of (or in addition to) listening for webhooks. Response (truncated):

{
  "id": "7c74cc95-d7c6-4537-b388-6d57ed020b34",
  "tenantKey": "cad95193904",
  "entityName": "Acme Corporation",
  "status": "incomplete",
  "principals": [
    {
      "id": "c4874dfd-50ef-429a-afbe-3c8adc0ecbe9",
      "firstName": "Jane",
      "lastName": "Founder",
      "identifier": { "type": "ssn", "value": "****" }
    }
  ],
  "requirements": {
    "currentlyDue": [
      "entityType",
      "principals.0.identifier.identityFileId"
    ],
    "errors": []
  }
}

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[].identifier.identityFileId`	Required if SSN verification fails
ID document (back)	`principals[].identifier.identityBackPageFileId`	Required if SSN verification fails
Address proof	`principals[].identifier.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[].identifier.identityFileId` and `principals[].identifier.identityBackPageFileId`	Government-issued photo ID (front and back)
Principal address unverified	`principals[].identifier.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": {
    "id": "7c74cc95-d7c6-4537-b388-6d57ed020b34",
    "tenantKey": "cad95193904",
    "status": "needs-additional-info",
    "timestamp": 1765359752,
    "businessId": "7dd569f9-bd54-4fbb-a5c2-f0aaadc68adf",
    "businessName": "Acme Corporation",
    "requirements": {
      "currentlyDue": [
        "principals.0.firstName",
        "principals.0.identifier.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": {
    "id": "7c74cc95-d7c6-4537-b388-6d57ed020b34",
    "businessId": "7dd569f9-bd54-4fbb-a5c2-f0aaadc68adf",
    "businessName": "Acme Corporation",
    "status": "complete",
    "timestamp": 1765359752,
    "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. You can’t combine 000-CAD-AUTO-APPROVE with a sentinel SSN in the same submission — the request returns 400.

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

​KYB Process Flow

​KYB Statuses

​Submit KYB

​Hosted KYB Form

​API Submission

​Updating KYB Information

​Check KYB Status

​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

Check KYB Status

Business Requirements

Principal / UBO Requirements

Required Documents (Conditional)

Webhook Events

business.kyb.reviewed

business.kyb.rejected

business.kyb.completed

Timeline

Sandbox Testing

Next Steps