Documentation

Pre-registering via API

Digiteal KYC API - Pre-Registration Guide

This guide outlines the process for pre-registering companies as well as submitting Know Your Customer (KYC) documentation using the Digiteal API. Integrating these endpoints allows you to seamlessly embed Digiteal's verification compliance directly into your platform.


1. Company Pre-Registration

To pre-register a company or update its missing information, submit a payload containing the company's KYC details and the associated contact person.

Pre-register a company: POST /api/v1/kyc/company

Payload Structure

The payload must conform to the CompanyCustomerKYCInfo schema:

  • customerCompany: Contains the legal company details (e.g., VAT number, IBANs, company name, pack type) and the nested contactPerson object.
  • customerInfo: Contains the basic customer association, including customerId, product type, and an optional welcomeMessage.
  • contractApproval: (Optional) Contains the IP address, User-Agent, and approval date for terms and conditions acceptance.
🚧

Important Uniqueness Requirements

To successfully pre-register a company without throwing a validation error, the following fields must be strictly unique across your integration:

  • Company Identity: The vatNumber (or alternatively, the identificationNumber) within customerCompany.
  • Contact Identity: The email address within the nested contactPerson object.
  • System Identity: The customerId within customerInfo.

Example Request

{
    "customerCompany": {
        "companyName": "Example Company LLC",
        "creationDate": "2020-01-01",
        "vatNumber": "BE0123456789",
        "integratorVATNumber": "BE9876543210",
        "pack": "START",
        "paymentMethods": ["BANCONTACT"],
        "ibans": ["BE00000000000000"],
        "contactPerson": {
            "firstName": "John",
            "lastName": "Doe",
            "email": "[email protected]",
            "language": "EN",
            "nationalities": ["BE"],
            "integratorVat": "BE9876543210",
            "ibans": ["BE00000000000000"]
        }
    },
    "customerInfo": {
        "customerId": "123e4567-e89b-12d3-a456-426614174000",
        "vatNumber": "BE9876543210",
        "welcomMessage": "Welcome to Digiteal!"
    },
    "contractApproval": {
        "approvalDate": "2026-05-13",
        "ipAddress": "192.0.2.1",
        "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"
    }
}

Company Registration Webhooks

We have webhooks you can subscribe to as an integrator to track account creation, validation after registration etc. More information here.

2. Uploading KYC Documents

After pre-registering an entity, you will need to upload supporting KYC documentation to attach to the contact person of the company.

Send a KYC document: POST /api/v1/kyc/document

🚧

Important

This endpoint requires a multipart/form-data request. The file binary MUST be passed in the document form field.

Query Parameters

When uploading a document, pass the following query parameters in the URL:

ParameterTypeRequiredDescription
emailStringYesThe email of the contact person to which the document should be attached.
typeEnumYesThe document type. Common values include: ID, ID_FRONT, ID_BACK, SELFIE_WITH_ID, BANK_MANDATE, BANK_ACCOUNT_VALIDATION, BY_LAWS.
nameStringYesThe file name (e.g., id_front.jpeg or mandate.pdf).
requesterVATStringNo*The VAT number of the company requesting the upload.
requesterIdentificationNumberStringNo*The identification number of the company requesting the upload.

** Note: Either requesterVAT or requesterIdentificationNumber must be provided.*

Examples

Uploading an ID Card (Front)

POST /api/v1/kyc/[email protected]&name=id_front.jpeg&type=ID_FRONT&requesterVAT=BE9876543210
Content-Type: multipart/form-data

[Attached binary image file in "document" field]

Uploading a Selfie with ID

POST /api/v1/kyc/[email protected]&name=selfie.jpeg&type=SELFIE_WITH_ID&requesterVAT=BE9876543210
Content-Type: multipart/form-data

[Attached binary image file in "document" field]

Uploading a Bank Mandate (PDF)

POST /api/v1/kyc/[email protected]&name=mandate.pdf&type=BANK_MANDATE&requesterVAT=BE9876543210
Content-Type: multipart/form-data

[Attached binary PDF file in "document" field]

3. Retrieving Contracts for Approval

To retrieve the latest contracts or terms and conditions that a company or person must approve before becoming an active Digiteal customer, use the following endpoints:

Retrieve Company Contracts: GET /api/v1/kyc/contractForCompany

These endpoints accept an optional language query parameter (defaulting to EN) and will return an array of ContractDetails. This array includes the localized name and URL to the respective contract documents.

4. Configuring Merchant Webhooks

Once a new account is pre-registered, the integrator - mechant relationship is established. You can now leverage this by creating an isolated webhook configuration specifically for them. This allows you to segregate payment notifications per customer environment instead of pooling all notifications into your overarching integrator webhook.

  • Webhook Configuration Endpoint: here
  • Get Webhook Configuration Endpoint: here

By passing the merchant's vatNumber or IdentificationNumber during the webhook setup request, Digiteal links that new webhook configuration exclusively to that specific merchant.

Benefits for Integrators:

  • Dual-Firing: Your central integrator webhook can still fire to give you an overview of all operations, while the merchant's specific webhook fires directly to their distinct environment.
  • Environment Isolation: Ideal for creating completely separated test instances for your clients without overwriting your primary integration settings.

Updated 16 days ago

Did this page help you?