Skip to main content

KYB Guide

Overview​

Welcome to the documentation for the Know Your Business (KYB) process on our cryptocurrency platform.

Before a company can perform transactions, it must successfully complete the KYB verification process. This procedure ensures regulatory compliance (including AML requirements), validates the legitimacy of the legal entity, and protects the integrity of the platform.

This guide provides a comprehensive overview of the KYB workflow, account statuses, and integration steps required to operate on our platform.

First, create a business account using Create Blockwyre Account. For individual account verification, please refer to the KYC Guide.

Table of Contents​

  1. KYB Process Overview
  2. Account Statuses
  3. KYB Verification Statuses
  4. KYB Process Flow
  5. Platform Integration
  6. Webhook Events
  7. Document Requirements
  8. Ownership Requirements
  9. Testing
  10. Final Considerations

KYB Process Overview​

The KYB process verifies the identity and legal standing of a business entity, its ownership structure, and its authorized representatives. It is designed to prevent fraud, money laundering (AML), terrorist financing, and regulatory violations.

When integrating our platform, it is essential to understand and follow this process to ensure compliance and transaction security.

Account Statuses​

After KYB verification is complete, business accounts transition through the following statuses:

  • pending: Initial state when an account is created. The account is waiting for KYB data submission.
  • active: The business entity and its ownership structure have been successfully verified. Transactions are enabled.
  • paused: The account requires additional corporate documents or ownership details.
  • closed: The account has been closed due to rejection or other reasons.

Note: Account status is updated based on KYB verification results. See KYB Verification Statuses for the verification process states.

KYB Verification Statuses​

Business accounts go through the following verification statuses during the KYB process:

  • pending: Initial state when KYB data is submitted.
  • in_review: Corporate and ownership data are under review.
  • approved: The business entity and its ownership structure have been successfully verified.
  • needs_update: Additional corporate documents or ownership details are required.
  • rejected: The account has been rejected due to risk, AML concerns, sanctions exposure, or unverifiable ownership structure.

KYB Process Flow​

The KYB process consists of structured steps that update the verification status according to verification progress.

4.1. Business Account Creation​

  • Action: As a merchant, you use the account creation endpoint to register a new business.
  • Resulting State: The account is created with the initial state pending.

4.2. Submitting KYB Data​

  • Action: Corporate and ownership data are submitted to the KYB provider. This includes:

    Corporate Information

    • Legal company name and DBA (if applicable).
    • Registration documents.
    • Business address.
    • EIN or Tax Identification Number (TIN).
    • Directors and authorized representatives.

    Ownership Structure

    • Full list of direct shareholders (individual or corporate).
    • Ownership percentage of each shareholder (must total 100%).
    • Country of residence or incorporation.
    • Identification of Ultimate Beneficial Owners (UBOs).
    • Disclosure of indirect ownership layers (if applicable).

  • Resulting State: The verification changes to in_review.

4.3. Review and Approval​

  • Action: The KYB provider evaluates:
    • Legal existence of the entity
    • AML and sanctions screening
    • Ownership transparency
    • UBO identification
    • Risk profile
  • Resulting State:
    • If verification is successful, the status changes to approved.
    • The business can now perform transactions on the platform.

4.4. Request for Additional Information​

If the provider requires additional information, the process is as follows:

  • Updated shareholder registry may be required.
  • Clarification of indirect ownership layers.
  • Additional UBO documentation.
  • Resulting State: Once the information is submitted, the status goes back to in_review.

4.5. KYB Process Result​

  • Approval:
    • Status: approved
    • Action: The business account can perform transactions and access platform services.
  • Rejection:
    • Status: rejected
    • Reasons: AML risk, sanctions exposure, unverifiable ownership structure, or regulatory non-compliance.
    • Action: The business must contact support. Transactions remain disabled. No actions can be performed on the account until the status is resolved.

Platform Integration​

To integrate our platform into your system, follow the detailed instructions below.

5.1. Endpoint for Business KYB Submit Banking Verification​

Endpoint: POST /api/v2/kyb/banking-verification/business

Authentication:

  • Bearer token (JWT) required
  • Permissions: KYB management permissions

Required Parameters:

  • accountId: Unique ID of the created account (UUID).
  • name: Registered legal name of the business (2-255 characters).
  • dbaName: Doing Business As (trade name) (2-255 characters).
  • phone: Business contact phone number (E.164 format, including country code).
  • address: Registered business address.
  • idNumber: Business identification number (2-20 characters).
  • idDocumentType: Type of business identification document (e.g., ein, passport).
  • taxNumber: Tax identification number (2-20 characters).
  • entityType: Legal entity type (see Supported Entity Types below).
  • formationDate: Date of incorporation/formation (ISO 8601 format: YYYY-MM-DD).
  • incorporationState: State or jurisdiction of incorporation (2-255 characters).
  • website: Official website of the business (valid URL).
  • operationAddress: Physical address where the business operates.

Each address and operationAddress object must contain:

  • address1: First line of the address (required, max 255 characters).
  • address2: Second line of the address (optional, max 255 characters).
  • city: City (required, max 100 characters).
  • state: State or province (required, max 100 characters).
  • postalCode: Postal or ZIP code (required, validated against country).
  • country: Country (required, ISO 3166-1 alpha-2).

Supported Entity Types​

  • sole_proprietor: Sole Proprietorship
  • limited_liability_company: Limited Liability Company (LLC)
  • general_partnership: General Partnership
  • publicly_traded_company: Publicly Traded Company
  • corporation: Corporation
  • non_profit: Non-Profit Organization
  • government_organization: Government Organization
  • limited_liability_partnership: Limited Liability Partnership (LLP)

Successful Response:

{
  "accountId": "019f1234-5678-90ab-cdef-1234567890ab",
  "status": "pending",
  "name": "Example Corp LLC",
  "dbaName": "Example Corp",
  "phone": "+12025551234",
  "address": {
    "address1": "123 Business Ave",
    "address2": "Suite 100",
    "city": "New York",
    "state": "NY",
    "postalCode": "10001",
    "country": "US"
  },
  "idNumber": "12-3456789",
  "idDocumentType": "ein",
  "taxNumber": "12-3456789",
  "entityType": "limited_liability_company",
  "formationDate": "2020-01-15",
  "incorporationState": "Delaware",
  "website": "https://examplecorp.com",
  "operationAddress": {
    "address1": "456 Operations Blvd",
    "address2": "",
    "city": "New York",
    "state": "NY",
    "postalCode": "10002",
    "country": "US"
  },
  "owners": [],
  "verificationFiles": [],
  "createdAt": "2026-02-16T00:00:00Z",
  "updatedAt": "2026-02-16T00:00:00Z"
}

Note: All process events will be sent via webhooks.

5.2. Endpoint for Business KYB Upload Documents​

The following endpoint allows uploading required corporate documents for the KYB process:

Endpoint: POST /api/v2/kyb/banking-verification/business/upload-document

Authentication:

  • Bearer token (JWT) required

Content Type: multipart/form-data

Size Limit: Maximum 32MB per upload

Required Parameters:

  • accountId: Unique ID of the created account (UUID).
  • documentType: Type of document being uploaded (see supported types below).
  • file: The document file to upload.

Supported Document Types:

  • certificate_of_incorporation: Certificate of Incorporation
  • articles_of_incorporation: Articles of Incorporation
  • organization_chart: Organization Chart
  • proof_of_address: Proof of business address
  • ein_confirmation: EIN Confirmation
  • formation: Formation documents
  • dba: Doing Business As certificate
  • other: Other relevant business documents

Successful Response:

{
  "message": "Document uploaded successfully",
  "documentType": "certificate_of_incorporation",
  "size": 245678
}

Error Responses:

  • 400 Bad Request: Invalid file format or missing parameters
  • 413 Payload Too Large: File exceeds 32MB limit

5.3. Delete Business Verification Document​

Endpoint: DELETE /api/v2/kyb/banking-verification/business/{accountId}/documents/{documentType}

Authentication:

  • Bearer token (JWT) required

Path Parameters:

  • accountId: Unique ID of the business account (UUID).
  • documentType: Type of document to delete (same values as upload document types).

Successful Response:

  • 204 No Content: Document successfully deleted

5.4. Ownership Submission​

Ownership information must be submitted after account creation. All owners/shareholders must be disclosed for the KYB verification to proceed.

Endpoint: POST /api/v2/kyb/banking-verification/business/ownership

Authentication:

  • Bearer token (JWT) required

Required Parameters:

  • accountId: Unique ID of the business account (UUID).
  • ownerId: Unique identifier of the owner (UUID).
  • firstName: First name of the owner (2-255 characters).
  • lastName: Last name of the owner (2-255 characters).
  • email: Email address of the owner.
  • phone: Phone number of the owner (E.164 format, including country code).
  • dateOfBirth: Date of birth of the owner (ISO 8601 format: YYYY-MM-DD).
  • documentId: Identification document for the owner.
  • address: Address of the owner.
  • ownershipPercentage: Percentage of ownership (must be a number between 1 and 100).
  • role: Role of the owner in the company (2-255 characters).

The documentId object must contain:

  • idNumber: Identification document number (required, 2-20 characters).
  • idDocumentType: Type of document (required, e.g., passport, national_id, driver_license).
  • idIssueDate: Issue date (optional, ISO 8601 format: YYYY-MM-DD).
  • idExpiryDate: Expiration date (optional, ISO 8601 format: YYYY-MM-DD).
  • idCountryOfIssue: Country of issuance (optional, ISO 3166-1 alpha-2).
  • nationality: Nationality of the owner (optional, ISO 3166-1 alpha-2).

The address object must contain the same fields as described in 5.1.

Successful Response:

{
  "ownerId": "019f5678-abcd-ef01-2345-678901234567",
  "status": "pending",
  "verificationUrl": "https://verification.blockwyre.com/v2/verification/...",
  "firstName": "John",
  "lastName": "Doe",
  "email": "john.doe@examplecorp.com",
  "phone": "+12025551234",
  "dateOfBirth": "1985-06-15",
  "documentId": {
    "idNumber": "AB1234567",
    "idDocumentType": "passport",
    "idIssueDate": "2020-01-01",
    "idExpiryDate": "2030-01-01",
    "idCountryOfIssue": "US",
    "nationality": "US"
  },
  "address": {
    "address1": "123 Owner St",
    "address2": "",
    "city": "New York",
    "state": "NY",
    "postalCode": "10001",
    "country": "US"
  },
  "ownershipPercentage": 51,
  "role": "director"
}

Important Notes:

  • Total ownership percentages across all owners must equal 100%.
  • All owners must have their KYC approved before the KYB can be finalized.
  • There is no maximum limit on the number of owners that can be added.

Deleting an Owner:

Endpoint: DELETE /api/v2/kyb/banking-verification/business/ownership/{ownerId}

Authentication:

  • Bearer token (JWT) required

Path Parameters:

  • ownerId: Unique identifier of the owner to delete (UUID).

Successful Response:

  • 204 No Content: Owner successfully deleted

State Diagram and Actions​

5.5. Request Ownership Verification Review​

When an owner's verification is in needs_update status and the owner has provided additional information, you can request a re-verification review.

Endpoint: POST /api/v2/kyb/banking-verification/business/ownership/{ownerId}/request-verification

Authentication:

  • Bearer token (JWT) required

Path Parameters:

  • ownerId: Unique identifier of the owner (UUID).

Response: Returns the ownership verification details (same format as ownership submission response).

5.5.1 Submit External Ownership Verification​

If the owner's identity has already been verified by an external provider (e.g. Jumio, Onfido), you can submit the verification data directly without going through the default Veriff flow.

Endpoint: POST /api/v2/kyb/banking-verification/business/ownership/{ownerId}/submit-external-verification

Authentication:

  • Bearer token (JWT) required

Content Type: multipart/form-data

Path Parameters:

  • ownerId: Unique identifier of the owner (UUID).

Required Parameters:

  • face: Selfie image file of the owner.
  • documentFront: Front of the ID document file.
  • raw: Raw verification JSON from the external provider (must be valid JSON).
  • provider: Source provider name (e.g. jumio, onfido).

Optional Parameters:

  • documentBack: Back of the ID document file.

Prerequisites:

  • The ownership data must be submitted first.
  • The owner must not already be approved or in_review.

Status Change: The owner status changes directly to approved.

Response: Returns the ownership verification details (same format as ownership submission response) with status approved.

Error Responses:

  • 400 Bad Request: Invalid raw JSON
  • 409 Conflict: Owner already in approved or in_review status

5.6. Request Business Banking Verification Review​

When the business KYB status is needs_update and the required additional information has been provided, you can request a re-verification review.

Endpoint: POST /api/v2/kyb/banking-verification/business/request-verification

Authentication:

  • Bearer token (JWT) required

Request Body:

{
  "accountId": "019f1234-5678-90ab-cdef-1234567890ab"
}

Response: Returns the full KYB banking verification details (same format as 5.7 Checking KYB Status response).

5.7. Checking KYB Status​

Endpoint: GET /api/v2/kyb/banking-verification/business/{accountId}

Authentication:

  • Bearer token (JWT) required

Path Parameters:

  • accountId: Unique ID of the business account (UUID).

Response:

{
  "accountId": "019f1234-5678-90ab-cdef-1234567890ab",
  "status": "in_review",
  "name": "Example Corp LLC",
  "dbaName": "Example Corp",
  "phone": "+12025551234",
  "address": {
    "address1": "123 Business Ave",
    "address2": "Suite 100",
    "city": "New York",
    "state": "NY",
    "postalCode": "10001",
    "country": "US"
  },
  "idNumber": "12-3456789",
  "idDocumentType": "ein",
  "taxNumber": "12-3456789",
  "entityType": "limited_liability_company",
  "formationDate": "2020-01-15",
  "incorporationState": "Delaware",
  "website": "https://examplecorp.com",
  "operationAddress": {
    "address1": "456 Operations Blvd",
    "address2": "",
    "city": "New York",
    "state": "NY",
    "postalCode": "10002",
    "country": "US"
  },
  "owners": [
    {
      "ownerId": "019f5678-abcd-ef01-2345-678901234567",
      "status": "approved",
      "firstName": "John",
      "lastName": "Doe",
      "email": "john.doe@examplecorp.com",
      "phone": "+12025551234",
      "dateOfBirth": "1985-06-15",
      "documentId": {
        "idNumber": "AB1234567",
        "idDocumentType": "passport"
      },
      "address": {
        "address1": "123 Owner St",
        "city": "New York",
        "state": "NY",
        "postalCode": "10001",
        "country": "US"
      },
      "ownershipPercentage": 100,
      "role": "director"
    }
  ],
  "verificationFiles": [
    {
      "documentType": "certificate_of_incorporation",
      "fileName": "cert_of_inc.pdf",
      "contentType": "application/pdf"
    }
  ],
  "eventHistory": [
    {
      "status": "pending",
      "date": "2026-02-16T00:00:00Z"
    },
    {
      "status": "in_review",
      "date": "2026-02-16T01:00:00Z"
    }
  ],
  "createdAt": "2026-02-16T00:00:00Z",
  "updatedAt": "2026-02-16T12:00:00Z"
}

Actions based on Status:

  • pending: Ensure business data and ownership information submission is completed.
  • in_review: No action required; the process is underway.
  • needs_update: Notify the business and request missing documentation or ownership clarification.
  • approved: Allow the business to perform transactions.
  • rejected: Disable transactions and provide support guidance.

5.8. Communication with Business Clients​

Maintaining clear communication is essential:

  • Status Notifications: Inform the business when the KYB status changes. You will receive webhook notifications for all status changes.
  • Document Guidance: Provide precise instructions for submitting corporate documents.
  • Ownership Requirements: Clearly communicate that all beneficial owners must be disclosed and verified.
  • Support: Provide compliance support for complex ownership or regulatory issues.

Webhook Events​

BlockWyre sends webhooks for all KYB process events. Configure webhook targets to receive real-time notifications.

KYB Events​

The following webhook events are sent during the KYB process:

Event TypeDescription
kyb_verification_submittedKYB verification has been submitted
kyb_status_updatedKYB verification status has changed
kyb_document_uploadedBusiness document has been uploaded successfully
kyb_verification_completedKYB verification process is complete

Note: KYB verification also triggers general account status webhooks (account_status_updated) when the account status changes based on verification results.

Webhook Configuration​

For complete webhook documentation including:

  • How to configure webhook targets
  • Signature verification
  • Payload structure and examples
  • Best practices and troubleshooting

Please see the Webhooks Guide.

Example Webhook Payload​

{
  "webhookId": "019f1234-5678-90ab-cdef-1234567890ab",
  "type": "kyb_verification_submitted",
  "accountId": "019f9876-5432-10fe-dcba-0987654321fe",
  "timestamp": "2026-02-16T12:00:00Z",
  "details": {
    "kybId": "019faaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
    "accountId": "019f9876-5432-10fe-dcba-0987654321fe",
    "status": "in_review",
    "entityType": "limited_liability_company"
  },
  "systemNotes": "Business verification submitted"
}

Document Requirements​

Corporate Documents​

The following documents are accepted for the KYB process:

Document TypeDescriptionRequired
certificate_of_incorporationCertificate of IncorporationYes
articles_of_incorporationArticles of IncorporationRecommended
organization_chartOrganization chart or ownership structure diagramRecommended
proof_of_addressProof of business address (utility bill, lease agreement)Yes
ein_confirmationEIN confirmation or tax documentsYes
formationFormation documentsIf applicable
dbaDoing Business As certificateIf applicable
otherOther relevant business documentsAs needed

Owner Documents​

Each owner/shareholder must provide:

  • Valid government-issued identification (passport, national ID, or driver's license)
  • All documents must be current and not expired

Document Guidelines​

  • Formats: Clear, legible images or PDFs
  • Size Limit: Maximum 32MB per document upload
  • Validity: All documents must be current and not expired
  • Country Codes: Use ISO 3166-1 alpha-2 format for country codes
  • Date Format: Use ISO 8601 format (YYYY-MM-DD) for all dates

Ownership Requirements​

Disclosure Requirements​

  • Complete Transparency: All direct shareholders must be disclosed.
  • Ownership Percentages: Must total exactly 100% across all owners.
  • Ultimate Beneficial Owners (UBOs): All individuals with 25% or more ownership must be identified.
  • Indirect Ownership: Multi-layer corporate structures must be fully transparent.
  • Director Information: All directors must be disclosed.

Ownership Validation​

  • All shareholders and UBOs are subject to AML and sanctions screening.
  • Incomplete ownership disclosure will result in needs_update or rejected status.
  • Regulatory thresholds for UBO identification may vary by jurisdiction.

Common Issues​

  • Ownership doesn't add to 100%: Ensure all shareholders are listed and percentages are accurate.
  • Missing UBO information: All beneficial owners with significant ownership (typically 25%+) must be identified.
  • Corporate shareholders: If a shareholder is another company, that entity's ownership structure may also need to be disclosed.

Testing​

Sandbox Environment​

BlockWyre provides a sandbox environment for testing KYB flows without affecting production data.

Simulator UI: You can test the complete verification flow using the simulator interface at:

https://sandbox.blockwyre.com/v2/verification/simulator/{sessionId}

Test Scenarios: The simulator supports the following test outcomes:

  • approved: Verification approved
  • declined: Verification declined
  • resubmission_requested: Additional information required

Testing Best Practices​

  1. Use sandbox environment for all testing
  2. Test with various entity types (LLC, Corporation, Partnership)
  3. Test complete ownership disclosure (single owner, multiple owners, corporate shareholders)
  4. Verify webhook delivery for each status change
  5. Test document upload for all document types
  6. Validate ownership percentage calculations
  7. Test rejection scenarios and needs_update flows

Final Considerations​

Regulatory Compliance​

  • AML/KYC Requirements: All beneficial owners must be identified and verified.
  • Sanctions Screening: All entities and individuals are screened against sanctions lists.
  • Jurisdictional Requirements: UBO identification thresholds may vary by jurisdiction.
  • Data Protection: All business data is encrypted and stored securely in compliance with data protection regulations.

Ownership Structure​

  • Ownership percentages must equal 100%.
  • Multi-layer corporate structures must be fully transparent.
  • All shareholders and UBOs are subject to AML and sanctions screening.
  • Incomplete ownership disclosure will result in needs_update or rejected status.

Document Requirements​

  • All corporate documents must be current and valid.
  • Owner identification documents must not be expired.
  • Additional documentation may be requested during the review process.

Data Security​

  • Encryption: All sensitive data is encrypted at rest and in transit.
  • Access Control: Access to KYB data is strictly controlled and logged.
  • Storage: Documents are stored in private, secure storage with appropriate access controls.

Updates and Changes​

  • Provider Changes: Stay updated with potential changes in the verification process or additional requirements from the KYB provider.
  • API Updates: Monitor for API version updates and new features.
  • Webhook Events: New webhook events may be added as the platform evolves.
  • Regulatory Changes: Compliance requirements may change based on jurisdictional regulations.

Support​

If you need assistance or have questions about the KYB process:

Email: support@blockwyre.com

Support and Resources​

If you need assistance or have any questions, our support team is here to help. You can contact our support team at support@blockwyre.com.

Stay Updated​

Stay up-to-date with the latest news, updates, and features from BlockWyre by following us on social media:

We are excited to have you on board and look forward to seeing how you leverage BlockWyre's powerful tools to enhance your financial operations. Happy integrating!