Skip to main content
The ApiUboDeclarations class provides methods to create and manage UBO (Ultimate Beneficial Owner) declarations. UBO declarations are required for legal entity users to declare individuals who ultimately own or control the business.

​
Methods

​
Create

Creates a new UBO declaration for a user (legal entity). 
public function Create($userId)
​
return
\MangoPay\UboDeclaration
The created UboDeclaration object

​
Example

$api = new \MangoPay\MangoPayApi();
$api->Config->ClientId = 'your-client-id';
$api->Config->ClientPassword = 'your-api-key';

$legalUserId = '12345678';
$declaration = $api->UboDeclarations->Create($legalUserId);

echo "Declaration ID: " . $declaration->Id . "\n";
echo "Status: " . $declaration->Status . "\n";

​
GetAll

Retrieves all UBO declarations for a specific user. 
public function GetAll(
    $userId,
    $pagination = null,
    $sorting = null
)
​
return
\MangoPay\UboDeclaration[]
Array of UboDeclaration objects

​
Example

$api = new \MangoPay\MangoPayApi();
$api->Config->ClientId = 'your-client-id';
$api->Config->ClientPassword = 'your-api-key';

$legalUserId = '12345678';
$declarations = $api->UboDeclarations->GetAll($legalUserId);

foreach ($declarations as $declaration) {
    echo "Declaration ID: " . $declaration->Id . "\n";
    echo "Status: " . $declaration->Status . "\n";
}

​
Get

Retrieves a specific UBO declaration by user ID and declaration ID. 
public function Get($userId, $uboDeclarationId)
​
return
\MangoPay\UboDeclaration
The UboDeclaration object

​
Example

$api = new \MangoPay\MangoPayApi();
$api->Config->ClientId = 'your-client-id';
$api->Config->ClientPassword = 'your-api-key';

$declaration = $api->UboDeclarations->Get('12345678', '87654321');

echo "Status: " . $declaration->Status . "\n";
echo "Number of UBOs: " . count($declaration->Ubos) . "\n";

​
GetById

Retrieves a UBO declaration directly by its ID (without requiring the user ID). 
public function GetById($uboDeclarationId)
​
return
\MangoPay\UboDeclaration
The UboDeclaration object

​
Example

$api = new \MangoPay\MangoPayApi();
$api->Config->ClientId = 'your-client-id';
$api->Config->ClientPassword = 'your-api-key';

$declaration = $api->UboDeclarations->GetById('87654321');

echo "User ID: " . $declaration->UserId . "\n";
echo "Status: " . $declaration->Status . "\n";

​
CreateUbo

Creates a new UBO (Ultimate Beneficial Owner) within a declaration. 
public function CreateUbo(
    $userId,
    $uboDeclarationId,
    $ubo
)
​
return
\MangoPay\Ubo
The created Ubo object

​
Example

$api = new \MangoPay\MangoPayApi();
$api->Config->ClientId = 'your-client-id';
$api->Config->ClientPassword = 'your-api-key';

$ubo = new \MangoPay\Ubo();
$ubo->FirstName = 'John';
$ubo->LastName = 'Doe';
$ubo->Nationality = 'US';
$ubo->Birthday = mktime(0, 0, 0, 1, 15, 1980);

$address = new \MangoPay\Address();
$address->AddressLine1 = '123 Main Street';
$address->City = 'New York';
$address->PostalCode = '10001';
$address->Country = 'US';
$ubo->Address = $address;

$birthplace = new \MangoPay\Birthplace();
$birthplace->City = 'Boston';
$birthplace->Country = 'US';
$ubo->Birthplace = $birthplace;

$ubo->isActive = true;

$createdUbo = $api->UboDeclarations->CreateUbo(
    '12345678',
    '87654321',
    $ubo
);

echo "UBO ID: " . $createdUbo->Id . "\n";

​
UpdateUbo

Updates an existing UBO within a declaration. 
public function UpdateUbo(
    $userId,
    $uboDeclarationId,
    $ubo
)
​
return
\MangoPay\Ubo
The updated Ubo object

​
Example

$api = new \MangoPay\MangoPayApi();
$api->Config->ClientId = 'your-client-id';
$api->Config->ClientPassword = 'your-api-key';

$ubo = $api->UboDeclarations->GetUbo('12345678', '87654321', 'ubo123');
$ubo->isActive = false;

$updatedUbo = $api->UboDeclarations->UpdateUbo(
    '12345678',
    '87654321',
    $ubo
);

echo "UBO status: " . ($updatedUbo->isActive ? 'Active' : 'Inactive') . "\n";

​
GetUbo

Retrieves a specific UBO from a declaration. 
public function GetUbo(
    $userId,
    $uboDeclarationId,
    $uboId
)
​
return
\MangoPay\Ubo
The Ubo object

​
Example

$api = new \MangoPay\MangoPayApi();
$api->Config->ClientId = 'your-client-id';
$api->Config->ClientPassword = 'your-api-key';

$ubo = $api->UboDeclarations->GetUbo('12345678', '87654321', 'ubo123');

echo "Name: " . $ubo->FirstName . " " . $ubo->LastName . "\n";
echo "Nationality: " . $ubo->Nationality . "\n";

​
SubmitForValidation

Submits a UBO declaration for validation by Mangopay. 
public function SubmitForValidation(
    $userId,
    $uboDeclarationId
)
​
return
\MangoPay\UboDeclaration
The UboDeclaration object with status updated to VALIDATION_ASKED

​
Example

$api = new \MangoPay\MangoPayApi();
$api->Config->ClientId = 'your-client-id';
$api->Config->ClientPassword = 'your-api-key';

$declaration = $api->UboDeclarations->SubmitForValidation('12345678', '87654321');

echo "Declaration submitted with status: " . $declaration->Status . "\n";

​
GetUboDeclarationById

Retrieves a UBO declaration by its ID (alias for GetById). 
public function GetUboDeclarationById($uboDeclarationId)
​
return
\MangoPay\UboDeclaration
The UboDeclaration object

​
UboDeclaration Object

The UboDeclaration object represents a declaration of ultimate beneficial owners.
​
Id
string
The unique identifier of the declaration
​
UserId
string
The unique identifier of the legal entity user
​
Status
string
The current status of the declaration. See \MangoPay\UboDeclarationStatus:
  • CREATED - Declaration created but not yet submitted
  • VALIDATION_ASKED - Declaration submitted for validation
  • VALIDATED - Declaration has been approved
  • REFUSED - Declaration has been rejected
  • INCOMPLETE - Declaration is missing information
​
ProcessedDate
int
Unix timestamp of when the declaration was processed
​
Reason
string
The reason why the declaration was refused or marked incomplete. See \MangoPay\UboDeclarationRefusedOrIncompleteReasonType
​
Message
string
Additional explanation of why the declaration was refused or marked incomplete
​
Ubos
\MangoPay\Ubo[]
Array of Ubo objects representing the beneficial owners declared
​
CreationDate
int
Unix timestamp of when the declaration was created

​
Ubo Object

The Ubo object represents an individual ultimate beneficial owner.
​
Id
string
The unique identifier of the UBO
​
FirstName
string
The first name of the beneficial owner
​
LastName
string
The last name of the beneficial owner
​
Address
\MangoPay\Address
The address of the beneficial owner
​
Nationality
string
The nationality of the beneficial owner (ISO 3166-1 alpha-2 format)
​
Birthday
int
Unix timestamp of the beneficial owner’s date of birth
​
Birthplace
\MangoPay\Birthplace
The birthplace of the beneficial owner
​
isActive
bool
Indicates whether this person is currently a UBO. Set to false if they are no longer a beneficial owner

​
Workflow

1

Create declaration

Call Create() with the legal entity user ID to create a new UBO declaration.
2

Add UBOs

Use CreateUbo() to add each beneficial owner to the declaration. You must add all individuals who own or control more than 25% of the business.
3

Update if needed

Use UpdateUbo() to modify UBO information or set isActive to false if they are no longer a beneficial owner.
4

Submit for validation

Call SubmitForValidation() when all UBOs have been added. The declaration status will change to VALIDATION_ASKED.
5

Monitor status

Use Get() or GetById() to check the declaration status. Mangopay will review and either validate or refuse the declaration.

​
Best Practices

Ensure that the uboDeclarationId is not null or empty when calling CreateUbo(). The method will throw a ResponseException if the ID is missing.
Always retrieve the latest declaration using Get() before submitting for validation to ensure all UBOs are properly configured.
If a declaration is refused or marked incomplete, check the Reason and Message fields to understand what needs to be corrected before resubmitting.

Build docs developers (and LLMs) love

Get started for freeTalk to us