Create a Customer via API

Once a customer is created, we initiate verification. You can then retrieve the customer object or listen to webhooks to track the status change.

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 and individuals based in the US, 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.

Pending Agreements (only for Portal, not applicable to customers created via API)
- 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.
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.
Pending
- Once verification flow is submitted, BVNK performs compliance checks.
- During this time, you can monitor the EPC’s status in the portal.
Verified
- The EPC has successfully passed the compliance review.
- Wallets can now be created and used.
Rejected
- The EPC has failed compliance checks or provided invalid information.
- The flow halts unless additional data is requested and submitted for reconsideration.

📘
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.

Prerequisites

Collect and validate customer data (IDs, address proofs, and so on) before creating the customer. This is crucial for a smooth KYC/KYB flow.
Remember to obtain the verified reference from the signed agreement session and include it in the request payload as the signedAgreementSessionReference field. This ensures the agreements are properly linked and recognized in your new customer creation and onboarding.

Create customer

Select a type of customer you want to create:

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

To create a business EPC, send the POST /platform/v1/customers request with the following request body:

{
    "type": "COMPANY",
    "company": {
        "name": "The Walt company",
        "description": "Entertainment Business",
        "entityType": "CORPORATION",
        "taxResidenceCountryCode": "US",
        "taxNumber": "98-7654321",
        "registrationNumber": "123456789",
        "industryReference": "30ea5818-06d8-11ef-b6e1-027612b7f6b5",
        "monthlyExpectedVolumesReference": "ef779c41-547e-11ef-8b9c-027612b7f6b5",
        "address": {
            "addressLine1": "Waterloo Bridge 13",
            "city": "London",
            "postalCode": "12345",
            "countryCode": "UK"
        },
        "operationalAddress": {
            "addressLine1": "Aldersgate Street 120",
            "city": "London",
            "postalCode": "EC1A 4JQ",
            "countryCode": "UK"
        },
        "associates": [
            {
                "person": {
                    "firstName": "Donald",
                    "lastName": "Duck",
                    "dateOfBirth": "1908-11-29",
                    "nationality": "US",
                    "address": {
                        "addressLine1": "1313 Webfoot Street",
                        "city": "Duckburg",
                        "postalCode": "12345",
                        "stateCode": "CA",
                        "countryCode": "US"
                    },
                    "contactInfo": {
                        "emailAddress": "[email protected]"
                    },
                    "taxIdentification": {
                        "number": "384-37-3429",
                        "taxResidenceCountryCode": "US"
                    }
                },
                "titles": [
                    "BUSINESS_OWNER",
                    "DIRECTOR"
                ]
            }
        ]
    },
    "riskScore": "LOW",
    "signedAgreementSessionReference": "f6541903-a0b4-4da3-99eb-f36608a6e857"
}

In the successful response you receive a unique customer reference CustomerReference for tracking the verification status.

{
  "reference": "b0ef182b-202d-4365-b69d-98dcb225fd62",
  "status": "INFO_REQUIRED",
  "infoRequired": {
      "questionnaireCodes": ["financialServicesQuestionnaireFull"]
  }
}

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

Attribute	Type	Description
reference	string	A unique identifier for the customer.
status	string	The current status of the customer. Possible values include: • `INFO_REQUIRED` – customer information is needed for verification. Note that in this case the code for a related questionnaire is sent. For more information, see Retrieve Compliance Data • `PENDING` – pending customer verification • `VERIFIED` – customer has been verified • `REJECTED` – verification has been unsuccessful.