Demandes KYB

Le KYB (« Know Your Business », connaissance du client entreprise) vérifie l'identité et la structure d'une entité commerciale. Le cycle de vie est le même que pour le KYC — création, envoi des documents justificatifs, soumission, réception d'une décision — avec une étape supplémentaire : vous soumettez une charge utile d'entité KYB décrivant l'entreprise et ses dirigeants principaux.

Créez la demande avec type: "BUSINESS", puis envoyez un POST vers le point de terminaison /kyb pour rattacher les données de l'entité.

L'extension KYB

POST /api/v1/kyc/requests/:id/kyb    Portée : kyc:write

Rattache les coordonnées de l'entreprise, les administrateurs et les bénéficiaires effectifs ultimes (UBO) à une demande BUSINESS existante.

Corps de la requête

{
  "companyName": "Acme Holdings Ltd",
  "registrationNo": "12345678",
  "countryOfIncorp": "GB",
  "companyType": "private_limited",
  "directors": [
    {
      "fullName": "Jane Doe",
      "dateOfBirth": "1975-06-22",
      "nationality": "GB",
      "appointedAt": "2018-01-15"
    }
  ],
  "ubos": [
    {
      "fullName": "Jane Doe",
      "dateOfBirth": "1975-06-22",
      "nationality": "GB",
      "ownershipPercentage": 100
    }
  ]
}

Chaque administrateur et chaque UBO comporte fullName, dateOfBirth, nationality, ainsi que des champs propres à son rôle (appointedAt pour les administrateurs, ownershipPercentage pour les UBO).

Réponse (201)

{ "id": "req_...", "status": "PENDING_UPLOAD" }

La réponse déclenche également une recherche dans le registre en arrière-plan : Certivant interroge le registre du commerce pertinent (Companies House pour le Royaume-Uni, OpenCorporates pour de nombreux autres pays) et enregistre les résultats sur la demande. Les résultats du registre sont consultables à GET /kyb.

Obtenir les données KYB

GET /api/v1/kyc/requests/:id/kyb    Portée : kyc:read

Renvoie les données d'entité soumises, ainsi que les résultats de toute recherche dans le registre.

Réponse

{
  "id": "kyb_...",
  "requestId": "req_...",
  "companyName": "Acme Holdings Ltd",
  "registrationNo": "12345678",
  "countryOfIncorp": "GB",
  "companyType": "private_limited",
  "directors": [...],
  "ubos": [...],
  "registryLookup": {
    "status": "verified",
    "registryName": "Companies House",
    "registryUrl": "https://find-and-update.company-information.service.gov.uk/company/12345678",
    "registeredName": "Acme Holdings Ltd",
    "registeredAddress": "1 Example St, London",
    "status": "active",
    "incorporatedAt": "2018-01-15",
    "officerDelta": [],
    "raw": { ... }
  }
}

registryLookup.officerDelta liste les dirigeants trouvés dans le registre mais non déclarés dans votre tableau directors : utile pour repérer les informations manquantes.

Documents requis

Une demande BUSINESS exige en général un ensemble de documents différent de celui d'un particulier :

• CERTIFICATE_OF_INCORPORATION : preuve de l'existence de l'entreprise.
• PROOF_OF_ADDRESS : pour le siège social.
• GOVERNMENT_ID et SELFIE pour chaque UBO et administrateur (ceux-ci passent par des sous-demandes par personne dans certaines configurations).
• COMPANY_OWNERSHIP_STRUCTURE : organigramme ou registre des actionnaires.

La liste exacte figure dans pendingDocTypes de la demande une fois l'entité KYB rattachée. Les paramètres KYB de votre organisation déterminent ce qui est exigé.

Sous-demandes KYC par dirigeant

Selon les paramètres de votre organisation, Certivant peut créer automatiquement des sous-demandes KYC individuelles pour chaque UBO et chaque administrateur. Elles apparaissent comme des demandes distinctes, rattachées à la demande BUSINESS parente par le champ parentRequestId. Vous envoyez les documents de chaque sous-demande exactement comme pour une demande KYC autonome : voir Documents.

graph LR
  Parent[BUSINESS request<br/>req_parent] --> Co[Company docs<br/>incorporation, address]
  Parent --> Ubo1[UBO 1 sub-request<br/>req_ubo1]
  Parent --> Ubo2[UBO 2 sub-request<br/>req_ubo2]
  Parent --> Dir1[Director sub-request<br/>req_dir1]
  Ubo1 --> Id1[GOVERNMENT_ID + SELFIE]
  Ubo2 --> Id2[GOVERNMENT_ID + SELFIE]
  Dir1 --> Id3[GOVERNMENT_ID + SELFIE]

La demande parente reste à l'état PENDING_UPLOAD jusqu'à ce que chaque sous-demande soit au moins PROCESSING, puis elle suit le même cycle de vie qu'une demande de particulier : PROCESSING → APPROVED / REJECTED / ESCALATED.

Soumission et décision

Une fois les documents de l'entreprise envoyés et chaque sous-demande soumise, soumettez la demande parente :

curl -X POST https://app.certivant.com/api/v1/kyc/requests/req_parent/submit \
  -H "Authorization: Bearer ck_live_..."

Le moteur de risque agrège les contrôles de l'entreprise et le verdict de chaque sous-demande en une décision unique. Les événements webhook sont émis pour la demande parente : vous n'avez pas besoin de suivre séparément chaque sous-demande, sauf si vous souhaitez une vue détaillée.

Erreurs

• 400 BAD_REQUEST : la demande n'est pas de type BUSINESS. Les points de terminaison KYB ne fonctionnent que sur les demandes d'entreprise.
• 409 CONFLICT : les données KYB ont déjà été rattachées. Pour les modifier, contactez le support : les données d'entité font partie de la piste d'audit et ne peuvent pas être modifiées librement.

Voir aussi

• Demandes KYC : les points de terminaison de demande sous-jacents, avec le même cycle de vie.
• Documents : envoi de la preuve de constitution et des documents par dirigeant.
• Webhooks : les mêmes événements kyc.request.* s'appliquent.