This endpoint enables you to create business (company) customers. Once a customer is created, we initiate verification. You can then retrieve the customer object or listen to webhooks (coming soon) to track the status change from PENDING_AGREEMENTS to VERIFIED or REJECTED.

How Embedded Partner Customer creation works

Embedded Wallets allow Embedded Partners (EP) to offer seamless payment and fund management capabilities directly within their platform while maintaining their branding. This guide provides a step-by-step process to create Embedded Partner Customer (EPC) accounts utilising Embedded Wallets via the BVNK Portal.

This product is available to businesses (with support for Consumers / Individuals coming soon) based in the US, UK, EEA, and other countries supported by BVNK outside of these regions.

EPC State transition diagram

The creation and verification lifecycle of an EPC follows a series of states—Pending Agreements, Info Required, Pending, Verified, and Rejected—which are illustrated and explained in this section.

Understanding these states (and how an EPC transitions between them) is key to a smooth onboarding process.

1. Pending Agreements
   • The EPC has been created but must consent to BVNK’s Terms of Service.
   • An agreements link is generated and must be shared with the EPC to collect consent.
2. Info Required
   • After Terms are signed, BVNK requires additional verification information (KYB/KYC).
   • A verification link is provided for the EP to provide their Customer's (EPC) data and documents.
3. Pending
   • Once verification flow is submitted, BVNK performs compliance checks.
   • During this time, you can monitor the EPC’s status in the portal.
4. Verified
   • The EPC has successfully passed the compliance review.
   • Wallets can now be created and used.
5. Rejected
   • The EPC has failed compliance checks or provided invalid information.
   • The flow halts unless additional data is requested and submitted for reconsideration.

Important

• Gathering and validating customer data (IDs, address proofs, etc.) before creating the customer is crucial for a smooth KYC/KYB flow.
• A successful customer creation returns a CustomerReference you will use to track verification status.
• Documents are not uploaded in this request. They must be added separately via a dedicated documents endpoint.

🚧

BETA endpoint

Please note that this endpoint is currently in beta, and it may undergo changes as we continue to improve and refine the functionality.

📘

Idempotency supported endpoint

This means you can retry a request without worrying about it being processed multiple times.

To use this feature, add the X-Idempotency-Key header with a unique value (a UUID). This ensures the request is only processed once, even if it's sent multiple times.

Endpoints

Create a Business (Company) Customer

Use this to create a business (company) customer. You can associate multiple beneficial owners, controlling persons, and signers (often referred to collectively as “associates”).

Request

Example – business customer creation with associates:

curl --location 'https://api.sandbox.bvnk.com/platform/v1/customers' \
--header 'X-Idempotency-Key: 0b3ed172-e24f-43f5-a901-4f7b6d138ebe' \
--header 'Content-Type: application/json' \
--header 'Authorization: Hawk id="YourHawkID", ts="1728655954", nonce="MdPBLt", mac="jGEwZvz7rVO3lM3Ose8Ww1PtgnsHBe7eFph3Nzj5H6Y="' \
--data-raw '{
  "type": "COMPANY",
  "company": {
    "name": "The Walt Disney Company",
    "description": "Entertainment business",
    "taxResidenceCountryCode": "US",
    "registrationNumber": "26-4532998",
    "industryCode": "74101",
    "address": {
      "addressLine1": "500 S Buena Vista St",
      "city": "Burbank",
      "postalCode": "91521",
      "state": "CA",
      "countryCode": "US"
    },
    "associates": [
      {
        "person": {
          "firstName": "Donald",
          "lastName": "Duck",
          "dateOfBirth": "1908-11-29",
          "address": {
            "addressLine1": "1313 Webfoot Street",
            "city": "Duckburg",
            "postalCode": "4587",
            "state": "CA",
            "countryCode": "US"
          },
          "contactInfo": {
            "emailAddress": "[email protected]"
          },
          "taxIdentification": {
            "number": "384-37-3429",
            "taxResidenceCountryCode": "US"
          }
        },
        "title": "COO",
        "riskScore": "MEDIUM",
        "controls": {
          "hasOwnership": true,
          "hasControl": false,
          "isSigner": true
        }
      }
    ]
  },
  "signedAgreementSessionReference": "78eedde1-2402-4a59-8bbd-ccecb6d612d1",
  "riskScore": "LOW"
}'

Request Body Parameters (Company)

Response

Success Example:

{
  "reference": "a7e21c62-27b8-4b3b-b51e-eb10edeb1731",
  "status": "PENDING"
}

Failure Example:

{
  "code": "ACCOUNTS-2000",
  "status": "BAD_REQUEST",
  "message": "Invalid request",
  "details": {
    "errors": {
      "industryReference": [
        "Industry with reference: 56e65ebc-06fa-11ef-bbf8-02d3d923cf2b does not exist"
      ]
    }
  }
}

Add Documents to a Customer

Use this endpoint to attach documents to an existing customer—either at the company level or for a specific associate (beneficial owner, director, or signer). Each call uploads a single document. Call the endpoint multiple times if you need to attach more than one file.

Important

• Make sure to reference the correct customerReference.
• Use personReference when the document belongs to a specific associate. If omitted (or null), the document is attached at the company level for business customers.
• Files must be base64-encoded before sending.

Endpoint

Request

Example – uploading a document for an associate:

curl --location --request PUT 'https://api.sandbox.bvnk.com/platform/v1/customers/123e4567-e89b-12d3-a456-426614174000/documents' \
--header 'Content-Type: application/json' \
--header 'Authorization: Hawk id="YourHawkID", ts="1678900000", nonce="abc123", mac="xyz789..."' \
--data-raw '{
  "personReference": "9b2c3d4e-567f-48f0-abc1-03a4e3df12ab",
  "type": "PASSPORT",
  "name": "John Smith ID.pdf",
  "content": "JVBERi0xLjUKJeLjz9MKMSAwIG9iago8PC9UeXBlIC9QYWdl..."
}'

Path Parameter

Request Body Parameters

Response

Success Example:

{
  "reference": "d42e1c62-27b8-4b3b-b51e-eb10edeb1731",
  "message": "Document uploaded successfully.",
  "status": "ACCEPTED"
}

Failure Example:

{
  "code": "DOCUMENTS-4000",
  "status": "BAD_REQUEST",
  "message": "Invalid document content",
  "details": {
    "errors": {
      "content": [
        "Document file content is not valid base64"
      ]
    }
  }
}

Good to know

1. Check Document Status

   • Once uploaded, we run checks on the document. You can retrieve the customer or associated person object to see if it’s recognised.

2. Retain Document References

   • The reference returned in the success response may be used for future queries or audits.

3. Combine with KYC

   • Document verification may be necessary before the customer can move from PENDING to VERIFIED.

Verification & Next Steps

1. Verification Process
   Once created, the customer enters a PENDING_AGREEMENTS (or similar) state while we wait for required agreements and checks. After that, verification may proceed in a PENDING state until KYC/KYB is complete. The time to verify can vary from seconds to hours, depending on risk profiles and document completeness.

2. Retrieving Customer Status

   • GET /platform/v1/customers/{reference} to fetch the current status.
   • Or configure BVNK webhooks to receive updates when a verification result is determined.

3. Possible Statuses

   • PENDING_AGREEMENTS: Awaiting agreement acceptance or further inputs.
   • INFO_REQUIRED: Customer information is needed for verification.
   • PENDING: Verification in progress.
   • VERIFIED: Customer has been verified.
   • REJECTED: Customer has been rejected during verification. see details for more info.