​
Introduction

This how-to guide will show you how to successfully submit a UBO Declaration for validation by Mangopay.
Prerequisites
The UBO Declaration object allows you to submit information concerning the beneficial owners of a legal user. Find out more about the process in the Beneficial owners article.
Best practice - Submit KYC Documents before UBO DeclarationBecause the information in the UBO Declaration is compared with the verification documents, it is necessary to submit all the required documents first before submitting the UBO Declaration.
How to submit a KYC Document →

​
1. Create the UBO Declaration

Create the UBO Declaration with the UserId.
POST /v2.01/{ClientId}/users/{UserId}/kyc/ubodeclarations 
<?php 

require_once 'vendor/autoload.php';

use MangoPay\MangoPayApi;
use MangoPay\Libraries\ResponseException as MGPResponseException;
use MangoPay\Libraries\Exception as MGPException;

$api = new MangoPayApi();

$api->Config->ClientId = 'your-client-id';
$api->Config->ClientPassword = 'your-api-key';
$api->Config->TemporaryFolder = 'tmp/';

try {
    $userId = '199463368';

    $response = $api->UboDeclarations->Create($userId);

    print_r($response);
} catch(MGPResponseException $e) {
    print_r($e);
} catch(MGPException $e) {
    print_r($e);
}
The response shows the Status “CREATED” and contains an Id, which is the unique identifier of the UBO Declaration object. You need to save this for the next step.

​
2. Create the first UBO

With the Id of the UBO Declaration as the UboDeclarationId path parameter, create the first UBO, entering the required information.
POST /v2.01/{ClientId}/users/{UserId}/kyc/ubodeclarations/{UboDeclarationId}/ubos 
{
    "LastName": "Effertz",
    "FirstName": "Michaela",
    "Birthday": 652117514,
    "Nationality": "FR",
    "Address": {
        "AddressLine1": "804 Hane Mountains",
        "AddressLine2": "Adriel Overpass",
        "City": "Paris",
        "Region": "Île-de-France",
        "PostalCode": "75001",
        "Country": "FR"
    },
    "Birthplace": {
        "City": "Paris",
        "Country": "FR"
    }
}

​
3. Create additional UBOs as needed

Repeat Step 2 as many times as necessary. Your UBO Declaration can contain a minimum of 1 and a maximum of 15 UBOs.

​
4. Submit the UBO Declaration

Once all UBOs are created and correctly declared, submit the declaration for review by Mangopay’s teams by changing the Status from CREATED to VALIDATION_ASKED.
PUT /v2.01/{ClientId}/users/{UserId}/kyc/ubodeclarations/{UboDeclarationId} 
{
    "Status": "VALIDATION_ASKED",
}
There are dedicated hooks to provide notifications of the outcome of the review by Mangopay:
  • UBO_DECLARATION_VALIDATED, notifying that the UBO Declaration status has changed to VALIDATED.
  • UBO_DECLARATION_REFUSED, notifying that the UBO Declaration status has changed to REFUSED.
  • UBO_DECLARATION_INCOMPLETE, notifying that the UBO Declaration status has changed to INCOMPLETE.
Note - Only INCOMPLETE declarations can be reusedUBO Declarations can be resubmitted or not depending on their status:
  • REFUSED - The object can’t be re-submitted. You need to create a new declaration.
  • INCOMPLETE - The object can be modified and re-submitted.
    For more information about why the declaration wasn’t validated, see the Reason and Message parameters returned by the View a UBO Declaration endpoint.

​
6. Simulate the response from Mangopay in Sandbox

The outcome of Mangopay’s review is indicated by the change of status of the declaration. In the Dashboard, you can simulate the response from Mangopay:
  1. Go to the Sandbox operations section.
  2. Select Process a UBO declaration.
  3. Enter the identifiers of the declaration and the user, then select the action you want to simulate.
  4. Click Submit to send the response.

​
7. If incomplete, take any remedial action

If the response from Mangopay is that the UBO Declaration is INCOMPLETE, check the View a UBO Declaration endpoint for information on why. Take the necessary steps indicated by Mangopay in the Reason and Message parameters.
API Response example
{
   "Id": "160691001",
   "UserId": "160686549",
   "CreationDate": 1674491433,
   "ProcessedDate": null,
   "Status": "INCOMPLETE",
   "Reason": "SHAREHOLDERS_DECLARATION_NEEDED",
   "Message": null,
   "Ubos": [
       {
           "Id": "160691407",
           "CreationDate": 1674491528,
           "LastName": "Boulanger",
           "FirstName": "Marie",
           "Birthday": 652117514,
           "Nationality": "FR",
           "Address": {
               "AddressLine1": "16 rue de Paris",
               "AddressLine2": null,
               "City": "Paris",
               "Region": "Île-de-France",
               "PostalCode": "75001",
               "Country": "FR"
           },
           "Birthplace": {
               "City": "Paris",
               "Country": "FR"
           },
           "IsActive": true
       }
   ]
}

​
If further documents required

It may be that additional documentary evidence is required, such as the Shareholder Declaration form or another verification document. Any additional documents should be submitted in a KYC Document object. How to submit a KYC Document →

​
If UBO added in error

It may be that the declaration contains information about someone who is not in fact a beneficial owner. If this happens, change the IsActive parameter of the UBO object to false to have them disregarded from the declaration. This action is irreversible, but another UBO can be added in their place.
PUT /v2.01/{ClientId}/users/{UserId}/kyc/ubodeclarations/{UboDeclarationId}/ubos/{UboId}
REST
{
   "Id": "160691407",
   "CreationDate": 1674491528,
   "LastName": "Boulanger",
   "FirstName": "Marie",
   "Birthday": 652117514,
   "Nationality": "FR",
   "Address": {
       "AddressLine1": "16 rue de Paris",
       "AddressLine2": null,
       "City": "Paris",
       "Region": "Île-de-France",
       "PostalCode": "75001",
       "Country": "FR"
   },
   "Birthplace": {
       "City": "Paris",
       "Country": "FR"
   },
   "IsActive": false
}

​
8. Once remediated, re-submit the UBO Declaration

Once the reason that the declaration was marked INCOMPLETE has been addressed, re-submit the UBO Declaration by changing the Status to VALIDATED_ASKED (as in Step 4).
Caution - UBO Declaration must be consistent with documentsIf additional documentary evidence was supplied to support the declaration, you must still ensure that the information in the UBO Declaration object is consistent with the documents before re-submitting.