You are viewing the docs for an old API version (v2) → View v2.01

The UBO Declaration object

An UBO Declaration is an electronic version of the previous KYC document "Shareholder Declaration", in order to declare all the Ultimate Beneficial Owners of a BUSINESS-typed legal User (ie the shareholders with >25% of capital or voting rights).

  1. Create an UBO Declaration for your legal user.
  2. Declare your UBOs (ie. Ultimate Beneficial Owner that owns more than 25% of this company or the legal respresentative in case of you don't have UBO).
  3. Edit the UBO Declaration object and set the Status field to "VALIDATION_ASKED" (instead of "CREATED")
  4. The demand is received by our team and once processed, it will either get a
    • "VALIDATED" status: if all other required parameters and KYC documents are validated, the user will pas on the KYCLevel REGULAR
    • "INCOMPLETE" status: complete the UBO Declaration or create a new one
    • "REFUSED" status with more information provided in the Reason and Message parameters

As mentionned above, this is a new functionality that will soon be compulsory. Here are the deadline for implementation:

I. Sandbox functionality activation

  • For all new client created after 06/04
  • By request anytime between 06/04 and 15/08
  • All clients will be switch to this new functionality by 20/08

II. Production functionality activation

  • For all new client created after 30/04
  • By request anytime between 06/04 and 15/09
  • All clients will be switch to this new functionality by 15/09

For any question or a request of switch, please contact our support team

Parameters

Id
string

string:

Maximum length is 255 characters

The item's ID

CreationDate
timestamp

timestamp

When the item was created

ProcessedDate
timestamp

timestamp

The date when the document was processed by MANGOPAY

Status
UBODeclarationStatus

UBODeclarationStatus:

CREATED, VALIDATION_ASKED, INCOMPLETE,VALIDATED, REFUSED

Status of a UBO Declaration

Reason
UBOReasonType

UBOReasonType:

MISSING_UBO,WRONG_UBO_INFORMATION,UBO_IDENTITY_NEEDED, SHAREHOLDERS_DECLARATION_NEEDED, ORGANIZATION_CHART_NEEDED,DOCUMENTS_NEEDED, DECLARATION_DO_NOT_MATCH_UBO_INFORMATION,SPECIFIC_CASE

ReasonType for UBO declaration

Refused or incomplete Reason for a UBO Declaration

Message
string

string:

Maximum length is 255 characters

Refused or incomplete Message for a UBO Declaration

Ubos
DeclaredUbos

DeclaredUbos

An array of UBOs declared as Ultimate Beneficial Owners of a BUSINESS Legal User.

{
"Id": "8494514",
"CreationDate": 12926321,
"ProcessedDate": 1501675794,
"Status": "INCOMPLETE",
"Reason": "MISSING_UBO",
"Message": "Two more UBOs are missing",
"Ubos": "["187928","187928"]"
}

Create a UBO Declaration

POST .../v2/ClientId

The ID of your client account

/users/UserId

A Mangopay user's ID

/kyc/ubodeclarations/
  • View
  • Code
    Code samples are only available for the latest API version
  • Run
  • View
  • Code
    Code samples are only available for the latest API version
  • Run
POST .../users/:UserId/kyc/ubodeclarations/ HTTP/1.1
POST .../users//kyc/ubodeclarations/ HTTP/1.1

Create a UBO

  • UBO declaration has to be in "CREATED" Status
  • You should create at least 1 UBO (maximum 4 UBOs)
  • Remember to change Status to "VALIDATION_ASKED" to submit your declaration
POST .../v2/ClientId

The ID of your client account

/users/UserId

A Mangopay user's ID

/kyc/ubodeclarations/UboDeclarationId

ID of a UBO Declaration

/ubos

Parameters

FirstName
string

string:

Maximum length is 255 characters
required

The name of the UBO

LastName
string

string:

Maximum length is 255 characters
required

The last name of the UBO

Address
Address

Address:

View Sub-parameters
required

The address

Address.AddressLine1
string

string:

Maximum length is 255 characters
required

The first line of the address

Address.AddressLine2
string

string:

Maximum length is 255 characters
optional

The second line of the address

Address.City
string

string:

Maximum length is 255 characters
required

The city of the address

Address.Region
string

string:

Maximum length is 255 characters
required

The region of the address - this is optional except if the Country is US, CA or MX

Address.PostalCode
string

string:

Maximum length is 50 characters
required

The postal code of the address - can be alphanumeric, dashes or spaces

Address.Country
CountryIso

CountryIso:

AD, AE, AF, AG, AI, AL, AM, AO, AQ, AR, AS, AT, AU, AW, AX, AZ, BA, BB, BD, BE, BF, BG, BH, BI, BJ, BL, BM, BN, BO, BQ, BR, BS, BT, BV, BW, BY, BZ, CA, CC, CD, CF, CG, CH, CI, CK, CL, CM, CN, CO, CR, CU, CV, CW, CX, CY, CZ, DE, DJ, DK, DM, DO, DZ, EC, EE, EG, EH, ER, ES, ET, FI, FJ, FK, FM, FO, FR, GA, GB, GD, GE, GF, GG, GH, GI, GL, GM, GN, GP, GQ, GR, GS, GT, GU, GW, GY, HK, HM, HN, HR, HT, HU, ID, IE, IL, IM, IN, IO, IQ, IR, IS, IT, JE, JM, JO, JP, KE, KG, KH, KI, KM, KN, KP, KR, KW, KY, KZ, LA, LB, LC, LI, LK, LR, LS, LT, LU, LV, LY, MA, MC, MD, ME, MF, MG, MH, MK, ML, MM, MN, MO, MP, MQ, MR, MS, MT, MU, MV, MW, MX, MY, MZ, NA, NC, NE, NF, NG, NI, NL, NO, NP, NR, NU, NZ, OM, PA, PE, PF, PG, PH, PK, PL, PM, PN, PR, PS, PT, PW, PY, QA, RE, RO, RS, RU, RW, SA, SB, SC, SD, SE, SG, SH, SI, SJ, SK, SL, SM, SN, SO, SR, SS, ST, SV, SX, SY, SZ, TC, TD, TF, TG, TH, TJ, TK, TL, TM, TN, TO, TR, TT, TV, TW, TZ, UA, UG, UM, US, UY, UZ, VA, VC, VE, VG, VI, VN, VU, WF, WS, YE, YT, ZA, ZM, ZW

A valid ISO 3166-1 alpha-2 format
required

The Country of the Address

Nationality
CountryIso

CountryIso:

AD, AE, AF, AG, AI, AL, AM, AO, AQ, AR, AS, AT, AU, AW, AX, AZ, BA, BB, BD, BE, BF, BG, BH, BI, BJ, BL, BM, BN, BO, BQ, BR, BS, BT, BV, BW, BY, BZ, CA, CC, CD, CF, CG, CH, CI, CK, CL, CM, CN, CO, CR, CU, CV, CW, CX, CY, CZ, DE, DJ, DK, DM, DO, DZ, EC, EE, EG, EH, ER, ES, ET, FI, FJ, FK, FM, FO, FR, GA, GB, GD, GE, GF, GG, GH, GI, GL, GM, GN, GP, GQ, GR, GS, GT, GU, GW, GY, HK, HM, HN, HR, HT, HU, ID, IE, IL, IM, IN, IO, IQ, IR, IS, IT, JE, JM, JO, JP, KE, KG, KH, KI, KM, KN, KP, KR, KW, KY, KZ, LA, LB, LC, LI, LK, LR, LS, LT, LU, LV, LY, MA, MC, MD, ME, MF, MG, MH, MK, ML, MM, MN, MO, MP, MQ, MR, MS, MT, MU, MV, MW, MX, MY, MZ, NA, NC, NE, NF, NG, NI, NL, NO, NP, NR, NU, NZ, OM, PA, PE, PF, PG, PH, PK, PL, PM, PN, PR, PS, PT, PW, PY, QA, RE, RO, RS, RU, RW, SA, SB, SC, SD, SE, SG, SH, SI, SJ, SK, SL, SM, SN, SO, SR, SS, ST, SV, SX, SY, SZ, TC, TD, TF, TG, TH, TJ, TK, TL, TM, TN, TO, TR, TT, TV, TW, TZ, UA, UG, UM, US, UY, UZ, VA, VC, VE, VG, VI, VN, VU, WF, WS, YE, YT, ZA, ZM, ZW

A valid ISO 3166-1 alpha-2 format
required

The UBO's nationality. ISO 3166-1 alpha-2 format is expected

Birthday
timestamp

timestamp
required

The date of birth of the UBO – make sure to set the right timezone (UTC) to avoid midnight becoming 11 p.m (and hence interpreted as the day before)

Birthplace
Birthplace

Birthplace:

View Sub-parameters
required

The UBO's birthplace

Birthplace.City
string

string:

Maximum length is 255 characters
required

The city of the address

Birthplace.Country
CountryIso

CountryIso:

AD, AE, AF, AG, AI, AL, AM, AO, AQ, AR, AS, AT, AU, AW, AX, AZ, BA, BB, BD, BE, BF, BG, BH, BI, BJ, BL, BM, BN, BO, BQ, BR, BS, BT, BV, BW, BY, BZ, CA, CC, CD, CF, CG, CH, CI, CK, CL, CM, CN, CO, CR, CU, CV, CW, CX, CY, CZ, DE, DJ, DK, DM, DO, DZ, EC, EE, EG, EH, ER, ES, ET, FI, FJ, FK, FM, FO, FR, GA, GB, GD, GE, GF, GG, GH, GI, GL, GM, GN, GP, GQ, GR, GS, GT, GU, GW, GY, HK, HM, HN, HR, HT, HU, ID, IE, IL, IM, IN, IO, IQ, IR, IS, IT, JE, JM, JO, JP, KE, KG, KH, KI, KM, KN, KP, KR, KW, KY, KZ, LA, LB, LC, LI, LK, LR, LS, LT, LU, LV, LY, MA, MC, MD, ME, MF, MG, MH, MK, ML, MM, MN, MO, MP, MQ, MR, MS, MT, MU, MV, MW, MX, MY, MZ, NA, NC, NE, NF, NG, NI, NL, NO, NP, NR, NU, NZ, OM, PA, PE, PF, PG, PH, PK, PL, PM, PN, PR, PS, PT, PW, PY, QA, RE, RO, RS, RU, RW, SA, SB, SC, SD, SE, SG, SH, SI, SJ, SK, SL, SM, SN, SO, SR, SS, ST, SV, SX, SY, SZ, TC, TD, TF, TG, TH, TJ, TK, TL, TM, TN, TO, TR, TT, TV, TW, TZ, UA, UG, UM, US, UY, UZ, VA, VC, VE, VG, VI, VN, VU, WF, WS, YE, YT, ZA, ZM, ZW

A valid ISO 3166-1 alpha-2 format
required

The Country of the Address

  • View
  • Code
    Code samples are only available for the latest API version
  • Run
  • View
  • Code
    Code samples are only available for the latest API version
  • Run
POST .../users/:UserId/kyc/ubodeclarations/:UboDeclarationId/ubos HTTP/1.1
Body Parameters :
{
"FirstName": "Bob",
"LastName": "Snow",
"Address": {
"AddressLine1": "1 Mangopay Street",
"AddressLine2": "The Loop",
"City": "Paris",
"Region": "Ile de France",
"PostalCode": "75001",
"Country": "FR"
},
"Nationality": "BE",
"Birthday": 1463496101,
"Birthplace": {
"City": "Namur",
"Country": "BE"
}
}
POST .../users//kyc/ubodeclarations//ubos HTTP/1.1
Body Parameters :
{
"FirstName": "",
"LastName": "",
"Address": {
"AddressLine1": "",
"AddressLine2": "",
"City": "",
"Region": "",
"PostalCode": "",
"Country": ""
},
"Nationality": "",
"Birthday": ,
"Birthplace": {
"City": "",
"Country": ""
}
}

Submit a UBO Declaration

Once your UBO declaration submitted, you will not be allowed to modify it. Our compliance team will analyse your declaration and will REFUSE it, VALIDATE it or mark it as INCOMPLETE with a Reason and a Message.

  • REFUSED is a final status, your declaration is wrong and you have to recreate a new declaration
  • VALIDATED is a final status, your declaration is correct. If your UBOs change you should recreate a new declaration
  • INCOMPLETE is not a final status, there is some mistakes in your declaration and you can modify it before ask a new validation

Exemple:

Status Reason Message
VALIDATED null null
REFUSED DECLARATION_DO_NOT_MATCH_UBO_INFORMATION None of the information provided do not match legal document data
INCOMPLETE MISSING_UBO Please provide information on UBO NAME XXX FIRSTNAME XXXXX
PUT .../v2/ClientId

The ID of your client account

/users/UserId

A Mangopay user's ID

/kyc/ubodeclarations/UboDeclarationId

ID of a UBO Declaration

Parameters

Status
UBODeclarationStatus

UBODeclarationStatus:

CREATED, VALIDATION_ASKED, INCOMPLETE,VALIDATED, REFUSED
required

Status of a UBO Declaration

  • View
  • Code
    Code samples are only available for the latest API version
  • Run
  • View
  • Code
    Code samples are only available for the latest API version
  • Run
PUT .../users/:UserId/kyc/ubodeclarations/:UboDeclarationId HTTP/1.1
Body Parameters :
{
"Status": "VALIDATION_ASKED"
}
PUT .../users//kyc/ubodeclarations/ HTTP/1.1
Body Parameters :
{
"Status": ""
}

Update a UBO

PUT .../v2/ClientId

The ID of your client account

/users/UserId

A Mangopay user's ID

/kyc/ubodeclarations/UboDeclarationId

ID of a UBO Declaration

/ubos/UboId

A UBO's ID

Parameters

FirstName
string

string:

Maximum length is 255 characters
optional

The name of the UBO

LastName
string

string:

Maximum length is 255 characters
optional

The last name of the UBO

Address
Address

Address:

View Sub-parameters
optional

The address

Address.AddressLine1
string

string:

Maximum length is 255 characters
required

The first line of the address

Address.AddressLine2
string

string:

Maximum length is 255 characters
optional

The second line of the address

Address.City
string

string:

Maximum length is 255 characters
required

The city of the address

Address.Region
string

string:

Maximum length is 255 characters
required

The region of the address - this is optional except if the Country is US, CA or MX

Address.PostalCode
string

string:

Maximum length is 50 characters
required

The postal code of the address - can be alphanumeric, dashes or spaces

Address.Country
CountryIso

CountryIso:

AD, AE, AF, AG, AI, AL, AM, AO, AQ, AR, AS, AT, AU, AW, AX, AZ, BA, BB, BD, BE, BF, BG, BH, BI, BJ, BL, BM, BN, BO, BQ, BR, BS, BT, BV, BW, BY, BZ, CA, CC, CD, CF, CG, CH, CI, CK, CL, CM, CN, CO, CR, CU, CV, CW, CX, CY, CZ, DE, DJ, DK, DM, DO, DZ, EC, EE, EG, EH, ER, ES, ET, FI, FJ, FK, FM, FO, FR, GA, GB, GD, GE, GF, GG, GH, GI, GL, GM, GN, GP, GQ, GR, GS, GT, GU, GW, GY, HK, HM, HN, HR, HT, HU, ID, IE, IL, IM, IN, IO, IQ, IR, IS, IT, JE, JM, JO, JP, KE, KG, KH, KI, KM, KN, KP, KR, KW, KY, KZ, LA, LB, LC, LI, LK, LR, LS, LT, LU, LV, LY, MA, MC, MD, ME, MF, MG, MH, MK, ML, MM, MN, MO, MP, MQ, MR, MS, MT, MU, MV, MW, MX, MY, MZ, NA, NC, NE, NF, NG, NI, NL, NO, NP, NR, NU, NZ, OM, PA, PE, PF, PG, PH, PK, PL, PM, PN, PR, PS, PT, PW, PY, QA, RE, RO, RS, RU, RW, SA, SB, SC, SD, SE, SG, SH, SI, SJ, SK, SL, SM, SN, SO, SR, SS, ST, SV, SX, SY, SZ, TC, TD, TF, TG, TH, TJ, TK, TL, TM, TN, TO, TR, TT, TV, TW, TZ, UA, UG, UM, US, UY, UZ, VA, VC, VE, VG, VI, VN, VU, WF, WS, YE, YT, ZA, ZM, ZW

A valid ISO 3166-1 alpha-2 format
required

The Country of the Address

Nationality
CountryIso

CountryIso:

AD, AE, AF, AG, AI, AL, AM, AO, AQ, AR, AS, AT, AU, AW, AX, AZ, BA, BB, BD, BE, BF, BG, BH, BI, BJ, BL, BM, BN, BO, BQ, BR, BS, BT, BV, BW, BY, BZ, CA, CC, CD, CF, CG, CH, CI, CK, CL, CM, CN, CO, CR, CU, CV, CW, CX, CY, CZ, DE, DJ, DK, DM, DO, DZ, EC, EE, EG, EH, ER, ES, ET, FI, FJ, FK, FM, FO, FR, GA, GB, GD, GE, GF, GG, GH, GI, GL, GM, GN, GP, GQ, GR, GS, GT, GU, GW, GY, HK, HM, HN, HR, HT, HU, ID, IE, IL, IM, IN, IO, IQ, IR, IS, IT, JE, JM, JO, JP, KE, KG, KH, KI, KM, KN, KP, KR, KW, KY, KZ, LA, LB, LC, LI, LK, LR, LS, LT, LU, LV, LY, MA, MC, MD, ME, MF, MG, MH, MK, ML, MM, MN, MO, MP, MQ, MR, MS, MT, MU, MV, MW, MX, MY, MZ, NA, NC, NE, NF, NG, NI, NL, NO, NP, NR, NU, NZ, OM, PA, PE, PF, PG, PH, PK, PL, PM, PN, PR, PS, PT, PW, PY, QA, RE, RO, RS, RU, RW, SA, SB, SC, SD, SE, SG, SH, SI, SJ, SK, SL, SM, SN, SO, SR, SS, ST, SV, SX, SY, SZ, TC, TD, TF, TG, TH, TJ, TK, TL, TM, TN, TO, TR, TT, TV, TW, TZ, UA, UG, UM, US, UY, UZ, VA, VC, VE, VG, VI, VN, VU, WF, WS, YE, YT, ZA, ZM, ZW

A valid ISO 3166-1 alpha-2 format
optional

The UBO's nationality. ISO 3166-1 alpha-2 format is expected

Birthday
timestamp

timestamp
optional

The date of birth of the UBO – make sure to set the right timezone (UTC) to avoid midnight becoming 11 p.m (and hence interpreted as the day before)

Birthplace
Birthplace

Birthplace:

View Sub-parameters
optional

The UBO's birthplace

Birthplace.City
string

string:

Maximum length is 255 characters
required

The city of the address

Birthplace.Country
CountryIso

CountryIso:

AD, AE, AF, AG, AI, AL, AM, AO, AQ, AR, AS, AT, AU, AW, AX, AZ, BA, BB, BD, BE, BF, BG, BH, BI, BJ, BL, BM, BN, BO, BQ, BR, BS, BT, BV, BW, BY, BZ, CA, CC, CD, CF, CG, CH, CI, CK, CL, CM, CN, CO, CR, CU, CV, CW, CX, CY, CZ, DE, DJ, DK, DM, DO, DZ, EC, EE, EG, EH, ER, ES, ET, FI, FJ, FK, FM, FO, FR, GA, GB, GD, GE, GF, GG, GH, GI, GL, GM, GN, GP, GQ, GR, GS, GT, GU, GW, GY, HK, HM, HN, HR, HT, HU, ID, IE, IL, IM, IN, IO, IQ, IR, IS, IT, JE, JM, JO, JP, KE, KG, KH, KI, KM, KN, KP, KR, KW, KY, KZ, LA, LB, LC, LI, LK, LR, LS, LT, LU, LV, LY, MA, MC, MD, ME, MF, MG, MH, MK, ML, MM, MN, MO, MP, MQ, MR, MS, MT, MU, MV, MW, MX, MY, MZ, NA, NC, NE, NF, NG, NI, NL, NO, NP, NR, NU, NZ, OM, PA, PE, PF, PG, PH, PK, PL, PM, PN, PR, PS, PT, PW, PY, QA, RE, RO, RS, RU, RW, SA, SB, SC, SD, SE, SG, SH, SI, SJ, SK, SL, SM, SN, SO, SR, SS, ST, SV, SX, SY, SZ, TC, TD, TF, TG, TH, TJ, TK, TL, TM, TN, TO, TR, TT, TV, TW, TZ, UA, UG, UM, US, UY, UZ, VA, VC, VE, VG, VI, VN, VU, WF, WS, YE, YT, ZA, ZM, ZW

A valid ISO 3166-1 alpha-2 format
required

The Country of the Address

isActive
bool

bool:

true, false
optional

To remove a UBO from your UBO declaration only put isActive to "false". You cannot activate back a UBO

  • View
  • Code
    Code samples are only available for the latest API version
  • Run
  • View
  • Code
    Code samples are only available for the latest API version
  • Run
PUT .../users/:UserId/kyc/ubodeclarations/:UboDeclarationId/ubos/:UboId HTTP/1.1
Body Parameters :
{
"FirstName": "Bob",
"LastName": "Snow",
"Address": {
"AddressLine1": "1 Mangopay Street",
"AddressLine2": "The Loop",
"City": "Paris",
"Region": "Ile de France",
"PostalCode": "75001",
"Country": "FR"
},
"Nationality": "GB",
"Birthday": 1463496101,
"Birthplace": {
"City": "Namur",
"Country": "BE"
},
"isActive": true
}
PUT .../users//kyc/ubodeclarations//ubos/ HTTP/1.1
Body Parameters :
{
"FirstName": "",
"LastName": "",
"Address": {
"AddressLine1": "",
"AddressLine2": "",
"City": "",
"Region": "",
"PostalCode": "",
"Country": ""
},
"Nationality": "",
"Birthday": ,
"Birthplace": {
"City": "",
"Country": ""
},
"isActive": ""
}

View a UBO Declaration

GET .../v2/ClientId

The ID of your client account

/users/UserId

A Mangopay user's ID

/kyc/ubodeclarations/UboDeclarationId

ID of a UBO Declaration
  • View
  • Code
    Code samples are only available for the latest API version
  • Run
  • View
  • Code
    Code samples are only available for the latest API version
  • Run
GET .../users/:UserId/kyc/ubodeclarations/:UboDeclarationId HTTP/1.1
GET .../users//kyc/ubodeclarations/ HTTP/1.1

View a UBO Declaration

GET .../v2/ClientId

The ID of your client account

/kyc/ubodeclarations/UboDeclarationId

ID of a UBO Declaration
  • View
  • Code
    Code samples are only available for the latest API version
  • Run
  • View
  • Code
    Code samples are only available for the latest API version
  • Run
GET .../kyc/ubodeclarations/:UboDeclarationId HTTP/1.1
GET .../kyc/ubodeclarations/ HTTP/1.1

View a UBO

GET .../v2/ClientId

The ID of your client account

/users/UserId

A Mangopay user's ID

/kyc/ubodeclarations/UboDeclarationId

ID of a UBO Declaration

/ubos/UboId

A UBO's ID

  • View
  • Code
    Code samples are only available for the latest API version
  • Run
  • View
  • Code
    Code samples are only available for the latest API version
  • Run
GET .../users/:UserId/kyc/ubodeclarations/:UboDeclarationId/ubos/:UboId HTTP/1.1
GET .../users//kyc/ubodeclarations//ubos/ HTTP/1.1

List UBO Declarations for a user

GET .../v2/ClientId

The ID of your client account

/users/UserId

A Mangopay user's ID

/kyc/ubodeclarations

Get parameters

Page
int

int
optional

The page number of results you wish to return

Per_Page
int

int
optional

The number of results to return per page

Sort
SortDirection

SortDirection:

ASC, DESC

The direction to sort the list
optional

The column to sort against and direction - only CreationDate (or Date for the events) is available and ASC or DESC for the direction

  • View
  • Code
    Code samples are only available for the latest API version
  • Run
  • View
  • Code
    Code samples are only available for the latest API version
  • Run
GET .../users/:UserId/kyc/ubodeclarations HTTP/1.1
Get Parameters :
{
"Page": 1,
"Per_Page": 25,
"Sort": "CreationDate:DESC"
}
GET .../users//kyc/ubodeclarations HTTP/1.1
Get Parameters :
{
"Page": ,
"Per_Page": ,
"Sort": ""
}
Share feedback