BVbvnk
Onboarding

Create business customer

Changed on

Creates a business customer onboarding application in a single request. Submit company details, associates, and business profile together. BVNK enriches the submission and routes it to the onboarding orchestrator.

Jurisdiction guidance:

  • EU flows require associate nationality, birth country, and biometric/selfie evidence.
  • US flows require US tax identifiers where applicable and may require additional fields for control persons.
  • stateCode for US addresses is planned for a future release and is not yet enforced.

Onboarding completes automatically once required company documents, associate identification documents, required questionnaires, and assigned agreements are all submitted and accepted for processing.

post/onboarding/v1/applications

Request

Request body

onboardingType'EMBEDDED' required

Onboarding mode. Must be EMBEDDED for the onboarding of your customers.

Example request

{
  "onboardingType": "EMBEDDED",
  "embeddedPartnerCustomer": {
    "partnerAccountReference": "partner-ref-001",
    "company": {
      "name": "Krause Fintech GmbH",
      "entityType": "CORPORATION",
      "taxNumber": "DE123456789",
      "registrationNumber": "HRB 123456",
      "incorporationDate": "2019-01-15",
      "address": {
        "addressLine1": "Heidestrasse 19",
        "city": "Koeln",
        "postalCode": "51247",
        "countryCode": "DE",
        "stateCode": "NY"
      },
      "businessProfile": {
        "naicsCode": "5239",
        "monthlyExpectedVolumes": "FROM_100K_TO_1M",
        "website": "https://www.krause-fintech.de",
        "customerTypes": "Both",
        "annualIncomingTransactionValue": "500000",
        "annualOutgoingTransactionValue": "250000",
        "jurisdictionalPortfolioDistribution": [
          {
            "country": "DE",
            "percentage": 45
          }
        ],
        "isRegulated": true,
        "sourceOfFunds": "COMMERCIAL_ACTIVITIES",
        "intendedUseOfAccount": "SUPPLIER_VENDOR_PAYMENTS"
      },
      "associates": [
        {
          "person": {
            "nationality": "DE",
            "birthCountryCode": "DE",
            "address": {
              "addressLine1": "Heidestrasse 19",
              "city": "Koeln",
              "postalCode": "51247",
              "countryCode": "DE",
              "stateCode": "NY"
            },
            "contactInfo": {
              "emailAddress": "freya.krause@krause-fintech.de"
            },
            "taxIdentification": {
              "taxResidenceCountryCode": "DE"
            },
            "position": "CEO"
          },
          "ownership": {
            "percentage": 100,
            "type": "DIRECT"
          }
        }
      ]
    },
    "useCase": "STABLECOIN_PAYOUTS",
    "externalReference": "ext-ref-001",
    "attestation": {
      "riskScore": "LOW",
      "eddCompleted": true
    },
    "reliance": {
      "identityDocumentMetadata": {
        "type": "PASSPORT",
        "number": "AB1234567",
        "expiryDate": "2030-12-31",
        "issueDate": "2015-10-01",
        "issuingCountryCode": "DE",
        "kycTimestamp": "2025-11-20T15:30:45.123Z"
      },
      "biometricLiveness": {
        "livenessTimestamp": "2025-11-20T15:30:45.123Z"
      },
      "addressVerification": {
        "type": "NON_DOC"
      }
    }
  }
}

Response

Onboarding application created successfully

idstring uuid required

Onboarding application ID used in subsequent onboarding API calls. Save this value for further use.

status'NOT_STARTED' | 'IN_PROGRESS' | 'SUBMITTED' | 'REQUIRED_ACTIONS' | 'APPROVED' | 'REJECTED' | 'SUSPENDED' required

Initial onboarding status.

Example response

{
  "status": "NOT_STARTED"
}

Changes