Create business customers

• Embedded model
• Global Money Platform

This guide describes how to create and onboard your customers.

Customers API v.2

This is a new customer onboarding flow, which is recommended for all new integrations.

If you already have an existing integration with Customers API v.1, you can continue using it. BVNK will continue to support this API v.1 going forward.

The onboarding flow is asynchronous: after you create a customer, BVNK processes the application and notifies you via webhooks when action is required or when verification is complete.

You can customize the customer creation and onboarding according to your own platform flow. The modular approach allows you to call endpoints for adding documents or sharing data in any order.

The data and documents you must submit depend on your use case and on the BVNK entity (US or EU) your account is assigned to. See the compliance requirements for the full list.

Business customer creation and onboarding is only available for the embedded delivery model. This flow requires verification of the legal entity (KYB) and related individuals, including directors, UBOs, and authorised signatories (KYC). The specific data and document requirements depend on jurisdiction (US or EU) and onboarding model:

• BVNK-Managed: You submit structured data and raw identity documents (ID front/back, selfie, proof of address) via BVNK's Onboarding API. BVNK performs identity verification (ID&V) via partner services. Recommended when you don't have an existing KYC/KYB programme or want BVNK to handle the full verification lifecycle.
• Partner-Managed: Available to regulated partners with an appropriate AML programme. You perform ID&V using your own processes and pass verification metadata (document type, number, expiry, liveness timestamp, address verification type) along with a customer risk score and EDD attestation to BVNK. Separate document upload steps for identity verification are not part of the happy path, but company-level document requirements can still apply. To learn more, contact your BVNK account manager.

When onboarding a customer, they pass through the following stages:

Status	Description
AGREEMENTS_PENDING	The customer was created through agreements and the agreements are not signed yet.
INFO_REQUIRED	Customer data, documents, or agreements are still missing. Check requiredActions.
PENDING	All information is submitted and the customer is under review.
ACTIONS_REQUIRED	BVNK needs additional information during or after the review. Check requiredActions.
VERIFIED	The customer is verified.
REJECTED	The customer failed verification. Customer onboarding is not possible.
TERMINATED	The customer was offboarded by BVNK or by you.

Prerequisites

Before you start, make sure you have:

• A BVNK account with Embedded Partner capabilities enabled.
• API keys generated via the BVNK Portal.
• Webhook endpoint configured to receive status change events from BVNK.
• Familiarity with BVNK's compliance requirements for business customers.

warning

Before running the onboarding flow, make sure you are not onboarding customers from restricted jurisdictions, and that your platform has collected all required KYB, KYC, screening, and risk assessment data. For more information, see BVNK Acceptable Use Policy.

Create agreements

Agreements must be presented, signed, and stored before a customer record exists. This is useful when you want your prospect to accept the terms during sign-up, and only commit a customer to BVNK once the paperwork is in order.

Each agreement has one of the following statuses:

Status	Description
PENDING	Agreement created and awaiting a response from the customer.
ACCEPTED	Customer accepted the agreement.
REJECTED	Customer rejected the agreement.

1. Create an agreement working set for the prospective customer by sending the POST platform/v2/agreements request.

   In the request, provide the data that will help BVNK determine the agreements relevant to your use case. Supply a reference that is unique within your account. You will reuse it to retrieve the set, to bulk-respond, and to bind the working set to a customer later.

   BVNK-Managed

   {
       "reference": "b3a4c1e2-9a1f-4c2b-8f11-7c2e5d4f9a01",
       "useCase": "STABLECOIN_PAYOUTS",
       "customerType": "COMPANY",
       "countryCode": "DE"
   }

   Partner-Managed

   For Partner-Managed onboarding, include the model field set to RELIANCE:

   {
       "reference": "b3a4c1e2-9a1f-4c2b-8f11-7c2e5d4f9a01",
       "useCase": "STABLECOIN_PAYOUTS",
       "customerType": "COMPANY",
       "countryCode": "DE",
       "model": "RELIANCE"
   }

   The response returns the following values:

   • Each agreement's id inside the agreements array. Use this ID to fetch or act on a specific agreement.
   • Current status. PENDING on creation.
   • signingUrl: a URL where the customer can review and sign the agreements.

   Save the reference and the returned id values for the subsequent steps.

2. Optional. Redirect customers after agreement signing.

   When presenting the hosted agreement page to your customer, you can redirect them back to your platform automatically once they complete signing. To enable this, append a redirectUri query parameter to the signingUrl returned in the Create Agreements response.

   The redirectUri value must be URL-encoded.
   • URL format: {signingUrl}&redirectUri={your-encoded-redirect-url}.
   • Example: https://onboarding.layer1.com#token={}&userId={}&redirectUri={your-encoded-redirect-url}.

   Once the customer signs the agreement, they are automatically redirected to the URL you specified.

   Environment	Hosted agreement base URL
   Sandbox	https://onboarding.sandbox.layer1.com
   Production	https://onboarding.layer1.com

   The signing link expires once the customer has completed signing. If you need to send the customer back to complete additional onboarding steps, generate a new link.

   This behaviour is supported for both BVNK-Managed and Partner-Managed (Reliance) models.

   Also see Sign agreements via hosted URL (v1).

3. Share the agreements with your customer and collect their responses. When you need to refresh the document URLs (for example, if the presigned URL has expired), use any of the following:

   • GET platform/v2/agreements to list the full customer agreements along with their actual status.
   • GET platform/v2/agreements/{id} to fetch a single agreement.
   • GET platform/v2/agreements/{id}/content to get the content of an agreement available for download via a link. Use this to share the agreement in the text form with your customer.

   The agreements are valid for one year.

4. Submit the customer's decisions by sending the POST platform/v2/agreements/actions request. The call is scoped by reference and accepts up to 50 ACCEPT / REJECT actions in one request.

   The response is a paginated list of per-item outcomes: successful items carry the updated status, and failed items carry an error.

5. When you subsequently create the customer via POST platform/v2/customers, pass the same reference so the signed agreements are bound to the new customer record. You do not need to re-sign or reassign them.

Idempotency and conflicts

Reusing an Idempotency-Key with a different payload returns 409. The same 409 is returned if the reference is already bound to an existing customer. If the agreements upstream is temporarily unavailable, both the create and bulk-actions endpoints return 502 — retry with the same Idempotency-Key.

Create business customers

After the relevant agreements are accepted, create a customer.

BVNK-Managed

The typical BVNK-Managed flow for a business customer follows these steps:

tip

You can perform steps 3-5 in any order.

1. Create a customer by sending the POST platform/v2/customers request with the company object and the minimum required fields. The company and individual objects are mutually exclusive, so don't include individual in the same request. In practice you should still send a complete businessProfile and jurisdiction-specific associates fields so onboarding is not stalled.

   {
       "useCase": "STABLECOIN_PAYOUTS",
       "reference": "b3a4c1e2-9a1f-4c2b-8f11-7c2e5d4f9a01",
       "company": {
           "name": "Krause Fintech GmbH",
           "entityType": "CORPORATION",
           "taxIdentification": { ... },
           "registrationNumber": "HRB 123456",
           "incorporationDate": "2019-01-15",
           "address": { ... },
           "isOperationalAddressDifferent": false,
           "businessProfile": { ... },
           "associates": [
               {
                   "person": {
                       "firstName": "Freya",
                       "lastName": "Krause",
                       "dateOfBirth": "1982-03-24",
                       "nationality": "DE",
                       "birthCountryCode": "DE",
                       "address": { ... },
                       "contactInfo": { ... },
                       "taxIdentification": { ... },
                       "position": "Geschaeftsfuehrer"
                   },
                   "titles": ["UBO", "DIRECTOR", "SIGNATORY", "ACCOUNT_REPRESENTATIVE"],
                   "ownership": { "percentage": "100", "type": "DIRECT" }
               }
           ]
       }
   }

   The response includes the customer's id and current status (for example INFO_REQUIRED while documents are still missing). Save the returned associate, agreement, and customer IDs, and your external references for later steps.

2. Retrieve the customer's status and the list of documents required for compliance by sending the GET platform/v2/customers/{id} request with the customer's ID you received in the response from step 1.

   In the response, you will receive the ID and the status of the customer.

   {
       "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
       "reference": "b3a4c1e2-9a1f-4c2b-8f11-7c2e5d4f9a01",
       "status": "PENDING",
       "type": "COMPANY",
       "model": "EMBEDDED",
       "useCase": "FIAT",
       "name": "Krause Fintech GmbH",
       "createdAt": "2026-04-28T11:39:12.788Z",
       "updatedAt": "2026-04-28T11:39:12.788Z",
       "requiredActions": [
           {
               "type": "DATA",
               "code": "CERTIFICATE_OF_INCORPORATION",
               "category": "DOCUMENT_REQUIREMENTS",
               "description": "Business Formation Document",
               "status": "REQUIRED",
               "target": { "kind": "DOCUMENT", "docSetType": "CERTIFICATE_OF_INCORPORATION", "types": ["CERTIFICATE_OF_INCORPORATION"], "subTypes": [], "associateId": null }
           },
           {
               "type": "DATA",
               "code": "REQUIRED_ALL_ASSOCIATES_VALID",
               "category": "ASSOCIATES",
               "description": "All associates must have valid status prior to submission."
           }
       ],
       "company": { ... }
   }

3. Upload the required company documents by sending the POST platform/v2/customers/{customerId}/documents request with the customer's ID you received in the response from step 1.

   Upload documents sequentially. You can add up to three documents in a batch. Add a one-second delay between uploads to stay within rate limits. For the list of the required documents, see Business documents (KYB) in the Compliance requirements reference.

   tip

   For documents in unsupported languages, a professionally notarised English translation is permitted.

   In the response, you will see the documents accepted for processing.

   {
       "id": "9b0c4f1d-7aa2-4c7e-8d55-f8b4a1d6c210",
       "customerId": "0a184641-30e2-4414-871f-3db1c683900e",
       "totalDocuments": 3,
       "successCount": 3,
       "failureCount": 0,
       "documents": [
           {
               "documentId": "b8f8a6b5-8f44-4b7c-8d1e-4a6a5a9b4a21",
               "type": "CERTIFICATE_OF_INCORPORATION",
               "filename": "certificate.pdf",
               "description": "Certificate of Incorporation",
               "status": "STORED",
               "uploadedAt": "2026-04-22T10:58:35.056865Z"
           }
       ],
       "createdAt": "2026-04-22T10:58:35.056865Z"
   }

4. Upload associate ID documents by sending the POST platform/v2/customers/{customerId}/associates/{associateId}/identification-documents request with the associate ID you received in the response from step 2.

   For the list of the required documents, see Identity verification (associates) in the Compliance requirements reference.

   {
   	"metadata": [
   		{
   			"type": "PASSPORT",
   			"name": "passport.pdf",
   			"countryCode": "DE"
   		}
   	]
   }

   In the response, you will receive the associate ID and the number of documents accepted for processing.

   {
   	"id": "4b0b8e2e-2f4e-4bfa-86d2-95aed0512c5f",
   	"associateId": "07b099fa-e1ee-4ad4-9cc4-6f2513a5a240",
   	"acceptedDocumentCount": 1,
   	"createdAt": "2026-04-22T11:00:35.056865Z"
   }

5. Wait for the webhook or poll the status by sending the GET platform/v2/customers/{id} request. The response includes the customer's status and requiredActions: the data, documents, and agreements that are still needed. See Resolve required actions for how to handle each action.

Partner-Managed

The Partner-Managed flow for a business customer differs from the BVNK-Managed flow in the following ways:

• Associates (Directors/UBOs): you perform identity verification on your side and pass verification metadata via API. You do not need to upload ID or selfie documents.
• Entity (Company): company-level document requirements can still apply depending on jurisdiction. For example, CERTIFICATE_OF_INCORPORATION is required when the legal entity is US-based, and PROOF_OF_OPERATIONAL_ADDRESS is required for EEA legal entities when isOperationalAddressDifferent is true.
• Risk: you attest to the risk scoring and screening results using the reliance.attestation object at the company level and individual associate level.

Completion trigger: onboarding progresses automatically once all required customer data and metadata are submitted and all agreements linked to the reference are accepted.

1. Create a customer by sending the POST platform/v2/customers request. Set model to RELIANCE and include the verification metadata in the request body.

   Use the same reference from the agreement step so accepted agreements are bound to the customer.

   {
       "useCase": "STABLECOIN_PAYOUTS",
       "reference": "b3a4c1e2-9a1f-4c2b-8f11-7c2e5d4f9a01",
       "model": "RELIANCE",
       "company": {
           "name": "Krause Fintech GmbH",
           "entityType": "CORPORATION",
           "taxIdentification": { ... },
           "registrationNumber": "HRB 123456",
           "incorporationDate": "2019-01-15",
           "address": { ... },
           "isOperationalAddressDifferent": false,
           "businessProfile": { ... },
           "associates": [
               {
                   "person": {
                       "firstName": "Freya",
                       "lastName": "Krause",
                       "dateOfBirth": "1982-03-24",
                       "birthCountryCode": "DE",
                       "nationality": "DE",
                       "address": { ... },
                       "contactInfo": { ... },
                       "taxIdentification": { ... },
                       "position": "Geschaeftsfuehrer",
                       "reliance": {
                           "identityDocumentMetadata": {
                               "type": "PASSPORT",
                               "number": "AB123456C",
                               "expiryDate": "2030-12-31",
                               "issueDate": "2020-01-01",
                               "issuingCountryCode": "DE",
                               "kycTimestamp": "2024-11-24T10:30:00Z"
                           },
                           "biometricLiveness": {
                               "livenessTimestamp": "2024-11-24T10:30:00Z"
                           },
                           "addressVerification": {
                               "type": "DOC"
                           },
                           "attestation": {
                               "riskScore": "LOW",
                               "eddCompleted": true
                           }
                       }
                   },
                   "titles": ["BUSINESS_OWNER", "DIRECTOR", "SIGNATORY", "ACCOUNT_REPRESENTATIVE"],
                   "ownership": { "percentage": "100", "type": "DIRECT" }
               }
           ],
           "cdd": {
               "expectedMonthlyVolume": { "amount": 500, "currency": "EUR" },
               "pepStatus": "NOT_PEP",
               "intendedUseOfAccount": "SUPPLIER_VENDOR_PAYMENTS"
           },
           "reliance": {
               "attestation": {
                   "riskScore": "LOW",
                   "eddCompleted": true
               }
           }
       }
   }

   The response includes the customer's id and initial status. Save the customer ID, associate IDs, and the external reference for follow-up requests.

   Key payload rules for Partner-Managed

   • Include at least one valid associate with required roles. For EU business onboarding, at least one director and one signatory must be present, and all beneficial owners above the threshold must be included.
   • Send full businessProfile data up front to reduce requests for information.
   • Use company.reliance.attestation and associates[].person.reliance.attestation objects to pass risk and EDD completion outcomes.
   • When isOperationalAddressDifferent is true, include the operationalAddress block.

2. Retrieve the customer's status and any outstanding requirements by sending the GET platform/v2/customers/{id} request. Inspect the requiredActions array: if a required action has category set to DOCUMENT_REQUIREMENTS and targets a company-level document, you need to upload it in the next step.

   {
       "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
       "reference": "b3a4c1e2-9a1f-4c2b-8f11-7c2e5d4f9a01",
       "status": "INFO_REQUIRED",
       "type": "COMPANY",
       "model": "RELIANCE",
       "useCase": "STABLECOIN_PAYOUTS",
       "name": "Krause Fintech GmbH",
       "createdAt": "2026-04-28T11:39:12.788Z",
       "updatedAt": "2026-04-28T11:39:12.788Z",
       "requiredActions": [
           {
               "type": "DATA",
               "code": "PROOF_OF_OPERATIONAL_ADDRESS",
               "category": "DOCUMENT_REQUIREMENTS",
               "description": "Proof of Operational Address",
               "status": "REQUIRED"
           }
       ],
       "company": { ... }
   }

3. If requiredActions includes company-level documents, upload them by sending the POST platform/v2/customers/{customerId}/documents request. Upload documents sequentially — you can add up to three documents in a batch.

   For Partner-Managed business onboarding, the common company-level document requirements are:

   • CERTIFICATE_OF_INCORPORATION when the legal entity is US-based.
   • PROOF_OF_OPERATIONAL_ADDRESS for EEA legal entities when isOperationalAddressDifferent is true.
   warning

   Do not upload identity documents for Associates (Directors/UBOs). Their verification is handled via the reliance metadata submitted in step 1.

   {
       "documents": [
           {
               "type": "PROOF_OF_OPERATIONAL_ADDRESS",
               "filename": "proof-of-operational-address.pdf",
               "description": "Proof of Operational Address"
           }
       ]
   }

   In the response, you will see the documents accepted for processing.

   {
       "id": "9b0c4f1d-7aa2-4c7e-8d55-f8b4a1d6c210",
       "customerId": "0a184641-30e2-4414-871f-3db1c683900e",
       "totalDocuments": 1,
       "successCount": 1,
       "failureCount": 0,
       "documents": [
           {
               "documentId": "b8f8a6b5-8f44-4b7c-8d1e-4a6a5a9b4a21",
               "type": "PROOF_OF_OPERATIONAL_ADDRESS",
               "filename": "proof-of-operational-address.pdf",
               "description": "Proof of Operational Address",
               "status": "STORED",
               "uploadedAt": "2026-04-22T10:58:35.056865Z"
           }
       ],
       "createdAt": "2026-04-22T10:58:35.056865Z"
   }

4. Wait for the webhook or poll the status by sending the GET platform/v2/customers/{id} request.

Metadata reference

The reliance metadata objects replace the raw identity verification uploads used in the BVNK-Managed flow.

Field	Where	Purpose
identityDocumentMetadata	Associate person block	Provides the identity document details used during the partner's KYC checks.
biometricLiveness	Associate person block	Confirms a liveness check was completed and when it occurred.
addressVerification	Associate person block	Indicates how address verification was performed.
attestation	Associate person and company blocks	Passes the partner's risk outcome and whether EDD has already been completed.

For field-level details on each metadata object, see Identity verification (associates) in the compliance requirements reference.

Customer review

Onboarding completes automatically once all of the conditions are met:

BVNK-Managed

• You uploaded company documents, and they are accepted for processing.
• You uploaded associate identity documents, and they are accepted for processing.
• All assigned agreements accepted.

There is no separate "complete" or "submit" API call. Once all conditions are met, BVNK triggers verification for all associates and the company entity. The customer transitions through processing states, and you receive the final outcome via webhook.

Partner-Managed

• You submitted all required business and associate data.
• You included all required associate and company reliance metadata.
• You uploaded any required company-level documents.
• All assigned agreements linked by reference are accepted.

There is no separate "submit" or "complete" endpoint. Once these conditions are satisfied, BVNK progresses the application through review and final decisioning.

Once BVNK completes the review, the customer reaches one of these terminal statuses:

Status	Description
VERIFIED	Customer verified and approved. Wallets and products can be provisioned.
REJECTED	Verification failed. The customer cannot proceed.

If BVNK needs more information during or after the review, the status changes to ACTIONS_REQUIRED and requiredActions lists what to provide. A customer who is offboarded later moves to TERMINATED.

Document rejection and resubmission

When BVNK declines a document, you receive a platform:accounts:customer:document-status-change webhook for company documents, or a platform:accounts:customer:associate-document-status-change webhook for associate documents, with the document's status set to DECLINED. The customer's requiredActions then lists the documents that are still needed, as actions with target.kind set to DOCUMENT:

Required action for a document

{
  "type": "DATA",
  "code": "PROOF_OF_DIRECTORSHIP",
  "category": "DOCUMENT_REQUIREMENTS",
  "description": "Proof of directorship dated within the past 6 months",
  "status": "REQUIRED",
  "target": {
    "kind": "DOCUMENT",
    "docSetType": "PROOF_OF_DIRECTORSHIP",
    "types": ["PROOF_OF_DIRECTORSHIP"],
    "subTypes": []
  }
}

To resubmit, upload a new document of one of the target.types. Send company documents to POST platform/v2/customers/{customerId}/documents. When target.associateId is set, the document belongs to that associate: send it to POST platform/v2/customers/{customerId}/associates/{associateId}/identification-documents.

Webhooks

Webhooks must be used as the primary mechanism for tracking status changes. Use polling only as a fallback.

To receive updates on each step of the onboarding process, configure your webhook endpoint in the BVNK Portal. BVNK sends notifications for key lifecycle events.

Event URN	Trigger
platform:accounts:customer:status-change	Customer's onboarding status changes.
platform:accounts:customer:agreement-status-change	Agreement is accepted or rejected by the customer.
platform:accounts:customer:associate-status-change	Associate's onboarding validation state changes.
platform:accounts:customer:associate-deleted	An associate is removed from the customer.
platform:accounts:customer:document-status-change	Status of one or more company-level documents changes.
platform:accounts:customer:associate-document-status-change	Status of one or more associate documents changes.

Use platform:accounts:customer:status-change as the primary driver for your onboarding flow. When you receive a status change, call GET platform/v2/customers/{id} to retrieve the current status and requiredActions.

note

The older bvnk:customers:* events are deprecated. BVNK still sends them alongside the platform:accounts:customer:* events, so subscribe to one set only, or you'll process each change twice.

Error handling

Scenario	Response status code	Resolution
Missing required field	400	Check the error message for the specific missing field.
Invalid industry / volume value	400	Use accepted enum values from the API definitions.
No associates provided	400	Include at least one associate with a valid title.
Associate missing required role	400	At least one associate must hold BUSINESS_OWNER or DIRECTOR title.
Reference already bound or idempotency conflict	409	Reuse the same payload for the same idempotency key and ensure the reference is not already attached to another customer.
Upstream agreements service temporarily unavailable	502	Retry with the same Idempotency-Key.