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 |
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.
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.
curl -X POST 'https://api.cadanapay.com/v1/businesses/{businessId}/kyb-link' \
-H 'Authorization: Bearer YOUR_API_KEY'
{
"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. curl -X POST 'https://api.cadanapay.com/v1/businesses/{businessId}/kyb' \
-H 'Authorization: Bearer YOUR_API_KEY'
204 on success. The business is now under review.
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.
curl -X PATCH 'https://api.cadanapay.com/v1/businesses/{businessId}/kyb' \
-H 'Authorization: Bearer YOUR_API_KEY'
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.
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 |
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 |
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.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"
}
}
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-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.
Next Steps
