Swipelux
Customers

Business

Create business customers with complete KYB information

Business customers represent company or organizational accounts for B2B applications. They require detailed KYB information including business identity, financial details, and compliance data.

Create

Not authenticated•Authenticate first
POST/v1/customers/business
Copy as

Creates a new business customer with complete KYB (Know Your Business) information. This creates both a customer record and associated business customer data.

Required Information

Optional Fields: Only the following fields are optional:

  • middleName - Middle name of the representative
  • addressLine2 - Additional address line (suite, apartment, etc.)
  • entityTypeDescription - Custom entity type description
  • businessTypeDescription - Custom business type description
  • sourceOfFundDescription - Additional source of funds details
  • purposeOfFundsDescription - Additional purpose of funds details

All other fields are required for business customer creation.

Business customer creation requires the following sections:

1. Personal Information (Representative)

  • Required: First name, last name, email, birth date, phone
  • Optional: Middle name

2. Business Identity

  • Required: Jurisdiction, entity type, entity name, trade name, registration number, tax number
  • Optional: Entity type description (custom description if needed)

3. Business Details

  • Required: Business description (min 10 characters), business type, websites, phone number
  • Optional: Business type description (custom description if needed)

4. Business Address

  • Required: Country, street address, city, state, ZIP code
  • Optional: Address line 2 (suite, apartment, floor, etc.)

5. Financial Information

  • Required: Source of funds, expected monthly volume (USD), purpose of funds, flow of funds description
  • Optional: Source of fund description, purpose of funds description (additional custom descriptions)

6. Compliance

  • Sanctioned Country Operations: Does business operate in sanctioned countries (true/false)
  • High-Risk Activities: Array of high-risk activities (can be empty)

7. Documents (Required)

  • Upload business verification documents for KYB compliance
  • Supports: PDF, JPEG, PNG formats
  • Provide base64 encoded file data or storage keys
  • Required document types:
    • certificate_of_incorporation - Certificate of Incorporation
    • power_of_attorney - Power of Attorney
    • corporate_structure - Corporate Structure
    • director_structure - Director Structure
    • proof_of_address - Proof of Address (utility bill or bank statement)

8. Shareholders (Required)

  • At least 1 shareholder is required for all business customers
  • Information about beneficial owners, directors, and authorized signers
  • Validation rules:
    • Minimum: 1 shareholder required
    • If only 1 shareholder: ownershipPercentage must be 100
    • Multiple shareholders: total ownership must equal 100%
  • Required for each shareholder:
    • Personal details (name, birth date, email)
    • Ownership percentage (must total 100% across all shareholders)
    • Role indicators (has control, is signer, is director)
    • Residential address
    • Identity documents (passport, national ID, or driver's license - both sides)
    • Proof of address document

Compliance Tip:

  • At least 1 shareholder is required
  • If only 1 shareholder, they must have 100% ownership
  • Include all beneficial owners with 25% or more ownership
  • Include all directors and authorized signers for complete KYB compliance
  • Total ownership across all shareholders must equal 100%

Request Body

Complete Example with Documents and Shareholders

{
  "firstName": "John",
  "lastName": "Smith",
  "birthDate": "1975-03-15",
  "email": "john@acmecorp.com",
  "phone": "+14155556789",
  "jurisdiction": "US",
  "entityType": "LLC",
  "entityName": "Acme Corporation LLC",
  "tradeName": "Acme Tech Solutions",
  "registrationNumber": "LLC-2015-123456",
  "taxNumber": "98-7654321",
  "businessDescription": "We provide software development and consulting services for enterprise clients worldwide",
  "businessType": "Technology",
  "websites": ["https://acmecorp.com", "https://acmetech.io"],
  "phoneNumber": "+14155550100",
  "addressCountry": "US",
  "streetAddress": "123 Market Street",
  "addressLine2": "Suite 500",
  "city": "San Francisco",
  "state": "CA",
  "zip": "94105",
  "sourceOfFunds": "Business Revenue",
  "expectedMonthlyVolumeUsd": 50000,
  "purposeOfFunds": "Business Operations",
  "flowOfFundsDescription": "Client payments received via bank transfer, used for operational expenses and vendor payments",
  "sanctionedCountryOperations": false,
  "highRiskActivities": [],
  "documents": [
    {
      "purposes": ["certificate_of_incorporation"],
      "file": "data:application/pdf;base64,JVBERi0xLjQKJeLjz9MKMyAwIG9iago8PC9UeXBlL..."
    },
    {
      "purposes": ["power_of_attorney"],
      "file": "data:application/pdf;base64,JVBERi0xLjQKJeLjz9MKMyAwIG9iago8PC9UeXBlL..."
    },
    {
      "purposes": ["corporate_structure"],
      "file": "data:application/pdf;base64,JVBERi0xLjQKJeLjz9MKMyAwIG9iago8PC9UeXBlL..."
    },
    {
      "purposes": ["director_structure"],
      "file": "data:application/pdf;base64,JVBERi0xLjQKJeLjz9MKMyAwIG9iago8PC9UeXBlL..."
    },
    {
      "purposes": ["proof_of_address"],
      "file": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEAYABgAAD/2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBkSEw8UHRofHh0a..."
    }
  ],
  "shareholders": [
    {
      "firstName": "Jane",
      "lastName": "Doe",
      "birthDate": "1980-05-20",
      "email": "jane@acmecorp.com",
      "phone": "+14155551234",
      "title": "CEO",
      "ownershipPercentage": 100,
      "hasControl": true,
      "isSigner": true,
      "isDirector": true,
      "address": {
        "streetAddress": "456 Oak Avenue",
        "city": "San Francisco",
        "country": "US",
        "zip": "94102"
      },
      "identifyingInformation": [
        {
          "type": "passport",
          "issuingCountry": "US",
          "number": "123456789"
        }
      ],
      "documents": [
        {
          "purposes": ["drivers_license_front"],
          "file": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEAYABgAAD/2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBkSEw8U..."
        },
        {
          "purposes": ["drivers_license_back"],
          "file": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEAYABgAAD/2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBkSEw8U..."
        },
        {
          "purposes": ["proof_of_address"],
          "file": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEAYABgAAD/2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBkSEw8U..."
        }
      ]
    }
  ]
}

Documents Format

Documents can be provided in two ways:

1. Base64 Encoded (Recommended for new uploads)

Use data URI format with base64 encoding:

{
  "documents": [
    {
      "purposes": ["certificate_of_incorporation"],
      "file": "data:application/pdf;base64,JVBERi0xLjQKJeLjz9MK..."
    },
    {
      "purposes": ["power_of_attorney"],
      "file": "data:application/pdf;base64,JVBERi0xLjQKJeLjz9MK..."
    },
    {
      "purposes": ["corporate_structure"],
      "file": "data:application/pdf;base64,JVBERi0xLjQKJeLjz9MK..."
    },
    {
      "purposes": ["director_structure"],
      "file": "data:application/pdf;base64,JVBERi0xLjQKJeLjz9MK..."
    },
    {
      "purposes": ["proof_of_address"],
      "file": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEAYABgAAD/2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBkSEw8UHRofHh0a..."
    }
  ]
}

Supported formats:

  • data:application/pdf;base64,... - PDF documents
  • data:image/jpeg;base64,... - JPEG images
  • data:image/png;base64,... - PNG images

2. Storage Key (For existing uploads)

{
  "documents": [
    {
      "purposes": ["certificate_of_incorporation"],
      "file": "customers/merchant_abc123/incorporation.pdf"
    }
  ]
}

Shareholders Format

Each shareholder requires personal information, ownership details, and address:

{
  "shareholders": [
    {
      "firstName": "Jane",
      "lastName": "Doe",
      "birthDate": "1980-05-20",
      "email": "jane@acmecorp.com",
      "phone": "+14155551234",
      "title": "CEO",
      "ownershipPercentage": 100,
      "hasControl": true,
      "isSigner": true,
      "isDirector": true,
      "address": {
        "streetAddress": "456 Oak Avenue",
        "city": "San Francisco",
        "country": "US",
        "zip": "94102"
      },
      "identifyingInformation": [
        {
          "type": "passport",
          "issuingCountry": "US",
          "number": "123456789"
        }
      ],
      "documents": [
        {
          "purposes": ["drivers_license_front"],
          "file": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEAYABgAAD/2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBkSEw8U..."
        },
        {
          "purposes": ["drivers_license_back"],
          "file": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEAYABgAAD/2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBkSEw8U..."
        },
        {
          "purposes": ["proof_of_address"],
          "file": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEAYABgAAD/2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBkSEw8U..."
        }
      ]
    }
  ]
}

Shareholder Document Purposes:

Identity Documents (choose one type):

  • passport_front, passport_back - Passport pages
  • id_card_front, id_card_back - National ID card
  • drivers_license_front, drivers_license_back - Driver's License

Address Verification:

  • proof_of_address - Proof of Address (utility bill, bank statement, etc.)

Required shareholder documents:

  • Identity document (Passport OR ID Card OR Driver's License - both sides)
  • Proof of Address

Response

Returns a customer object with all business information:

{
  "id": "cus_TkqrD3axUgHQhHYRLE",
  "firstName": "John",
  "lastName": "Smith",
  "birthDate": "1975-03-15",
  "email": "john@acmecorp.com",
  "phone": "+14155556789",
  "jurisdiction": "US",
  "entityType": "LLC",
  "entityName": "Acme Corporation LLC",
  "tradeName": "Acme Tech Solutions",
  "registrationNumber": "LLC-2015-123456",
  "taxNumber": "98-7654321",
  "businessDescription": "We provide software development and consulting services for enterprise clients worldwide",
  "businessType": "Technology",
  "websites": ["https://acmecorp.com", "https://acmetech.io"],
  "phoneNumber": "+14155550100",
  "addressCountry": "US",
  "streetAddress": "123 Market Street",
  "addressLine2": "Suite 500",
  "city": "San Francisco",
  "state": "CA",
  "zip": "94105",
  "sourceOfFunds": "Business Revenue",
  "expectedMonthlyVolumeUsd": 50000,
  "purposeOfFunds": "Business Operations",
  "flowOfFundsDescription": "Client payments received via bank transfer, used for operational expenses and vendor payments",
  "sanctionedCountryOperations": false,
  "highRiskActivities": [],
  "documents": [
    {
      "id": "bizdoc_BYpFPfrMBYBwqQIhiH",
      "purposes": ["certificate_of_incorporation"],
      "file": "business-customer-company-docs/25k1daVb5I7mrfoBG3mzv.pdf",
      "status": "pending",
      "createdAt": "2025-12-31T11:52:26.433Z",
      "updatedAt": "2025-12-31T11:52:26.433Z"
    },
    {
      "id": "bizdoc_CA2IELYzQSAKG2hf16",
      "purposes": ["power_of_attorney"],
      "file": "business-customer-company-docs/mM9H0ujfFKGtJ4E6wGwyW.pdf",
      "status": "pending",
      "createdAt": "2025-12-31T11:52:26.672Z",
      "updatedAt": "2025-12-31T11:52:26.672Z"
    },
    {
      "id": "bizdoc_EC5pUZ4EQakCJpytvy",
      "purposes": ["corporate_structure"],
      "file": "business-customer-company-docs/meI5T6CRdlSK1o_xWo1Ug.pdf",
      "status": "pending",
      "createdAt": "2025-12-31T11:52:26.919Z",
      "updatedAt": "2025-12-31T11:52:26.919Z"
    },
    {
      "id": "bizdoc_wKVLAzg9CBRhe5oas9",
      "purposes": ["director_structure"],
      "file": "business-customer-company-docs/jDiAD-6EJt4kdTnldL7t0.pdf",
      "status": "pending",
      "createdAt": "2025-12-31T11:52:27.204Z",
      "updatedAt": "2025-12-31T11:52:27.204Z"
    },
    {
      "id": "bizdoc_pL8mNzR4TfVkW9xYq2",
      "purposes": ["proof_of_address"],
      "file": "business-customer-company-docs/nX7tY5uHvKzP3mQ8rL6j.jpg",
      "status": "pending",
      "createdAt": "2025-12-31T11:52:27.450Z",
      "updatedAt": "2025-12-31T11:52:27.450Z"
    }
  ],
  "shareholders": [
    {
      "id": "bizsh_iyegFEuCzX7YxPXjMj",
      "firstName": "Jane",
      "lastName": "Doe",
      "birthDate": "1980-05-20",
      "email": "jane@acmecorp.com",
      "phone": "+14155551234",
      "title": "CEO",
      "ownershipPercentage": 100,
      "hasControl": true,
      "isSigner": true,
      "isDirector": true,
      "address": {
        "streetAddress": "456 Oak Avenue",
        "city": "San Francisco",
        "country": "US",
        "zip": "94102"
      },
      "identifyingInformation": [
        {
          "type": "passport",
          "issuingCountry": "US",
          "number": "123456789"
        }
      ],
      "documents": [
        {
          "id": "bizshd_Abc123XyZ789",
          "purposes": ["drivers_license_front"],
          "file": "business-customer-shareholder-docs/dL_fRoNt_123.jpg",
          "status": "pending",
          "createdAt": "2025-12-31T11:52:27.500Z",
          "updatedAt": "2025-12-31T11:52:27.500Z"
        },
        {
          "id": "bizshd_Def456UvW012",
          "purposes": ["drivers_license_back"],
          "file": "business-customer-shareholder-docs/dL_BaCk_456.jpg",
          "status": "pending",
          "createdAt": "2025-12-31T11:52:27.650Z",
          "updatedAt": "2025-12-31T11:52:27.650Z"
        },
        {
          "id": "bizshd_Ghi789TsR345",
          "purposes": ["proof_of_address"],
          "file": "business-customer-shareholder-docs/aDdReSs_789.pdf",
          "status": "pending",
          "createdAt": "2025-12-31T11:52:27.800Z",
          "updatedAt": "2025-12-31T11:52:27.800Z"
        }
      ],
      "createdAt": "2025-12-31T11:52:27.231Z",
      "updatedAt": "2025-12-31T11:52:27.231Z"
    }
  ],
  "createdAt": "2025-12-31T11:52:26.076Z",
  "updatedAt": "2025-12-31T11:52:26.076Z"
}

Notes:

  • The id field is the customer ID (starts with cus_) used for all subsequent operations like creating wallets and transfers
  • Document IDs use prefix bizdoc_ for business documents and bizshd_ for shareholder documents
  • Shareholder IDs use prefix bizsh_
  • All dates are in ISO 8601 format
  • Only middleName, addressLine2, and *Description fields are optional - all others are required
  • Phone numbers must be unique across all customers

Best Practices

Accurate Information

Provide complete and accurate business information to avoid verification delays. Inaccurate data can result in account suspension.

Transaction Volume

Be realistic with expectedMonthlyVolumeUsd. Significant deviations from stated volume may trigger additional verification.

Compliance Disclosure

Accurately disclose sanctioned country operations and high-risk activities. False information can lead to compliance issues.

Business Description

Write clear, detailed descriptions. Vague descriptions like "Various services" will slow verification.

Document Uploads

  • Use clear, legible scans or photos
  • Provide multiple document types for faster verification
  • Supported formats: PDF, JPEG, PNG (max 10MB per file)
  • Use base64 encoding: "data:image/jpeg;base64,..."

Shareholders Information

  • Required: At least 1 shareholder must be provided
  • Single shareholder: Must have exactly 100% ownership
  • Multiple shareholders: Total ownership must equal 100%
  • Include all beneficial owners with 25% or more ownership
  • Add all directors and authorized signers
  • Provide complete address for each shareholder
  • Upload identity documents (front and back) + proof of address for each shareholder
  • Ensure ownership percentages are accurate

Common Entity Types

  • LLC - Limited Liability Company
  • Corporation - C-Corp, S-Corp
  • Partnership - General or Limited Partnership
  • Sole Proprietorship - Individual business owner
  • Non-Profit - 501(c)(3) or equivalent
  • Other - Provide description in entityTypeDescription

Common Business Types

  • Technology - Software, SaaS, IT services
  • Retail - E-commerce, physical stores
  • Finance - Financial services, fintech
  • Healthcare - Medical services, health tech
  • Manufacturing - Production, distribution
  • Professional Services - Consulting, legal, accounting
  • Other - Provide description in businessTypeDescription

Next Steps

After creating a business customer:

  1. Create a wallet - Set up multi-chain wallet infrastructure
  2. Initiate pay-in - Fund the wallet via crypto or fiat payment methods
  3. Manage customer - Update profile, check balance, manage lifecycle

Individual

Create individual customers with optional profile information

Add Wallet

Create blockchain wallets for customers

On this page