Add UBOs


Use the following requests to add, retrieve or update ultimate beneficial owner (UBO) details for an affiliated merchant account:

Add, retrieve, and update UBOs:

Add and retrieve UBO identification documents:

Authentication

All the UBO requests require a partner account API key. This is not the same as a site API key. For more information, email your partner manager.

All URLs on this page are directed to our test API. To use the live API, change the subdomain in the URL from testapi to api and use the corresponding API key.


Create a UBO

POST https://testapi.multisafepay.com/v1/json/accounts/{affiliate_account_id}/ubos?api_key={your-account-api-key}

Add a new UBO to a merchant account.

Path parameters

Parameter Description
affiliate_account_id
string
The affiliated merchant ID.
Format: 8 character string, e.g. 12345678. Required.
Request body parameters
Parameter Description
name
string
The UBO’s full name.
Format: Max 200 characters. Required.
title
string
The UBO’s title.
Options: mr or mrs. Required.
address
string
The UBO’s address.
Format: Max 100 characters. Optional.
address_apartment
string
The UBO’s apartment number.
Format: Max 15 characters. Optional.
city
string
The UBO’s city of residence.
Format: Max 100 characters. Optional.
state
string
The UBO’s province or state of residence.
Format: Max 100 characters. Optional.
country
string
The UBO’s country of residence.
Format: ISO 3166-1 alpha-2, e.g. NL. Required.
zipcode
string
The UBO’s ZIP code.
Format: max 20 characters. Optional.
birthday
string
The UBO’s date of birth.
Format: yyyy-mm-dd, e.g. 1980-01-31. Required.
country_of_birth
string
The UBO’s country of birth.
Format: ISO 3166-1 alpha-2, e.g. NL. Required.
email
string
The UBO’s email address.
Format: Max 100 characters. Required.
mobile_phone
string
The UBO’s mobile phone number.
Format: Max 25 characters. Optional.
office_phone
string
The UBO’s office phone number.
Format: Max 25 characters. Optional.
job_title
string
The UBO’s job title.
Format: Max 100 characters. Required.
percentage
integer
The UBO’s percentage of equity.
Format: Non-fractional number from 25 to 100. Required.
type
string
The UBO’s type of equity.
Options: control_rights, shareholder, voting_rights or other. Required.
Response body parameters

The following are in addition to the request body parameters.

Parameter Description
account_id
string
The affiliated merchant ID.
Format: 8 character string, e.g. 12345678.
id
string
The unique identifier of the UBO. Referred to as ubo_id.
Sample request
curl -X POST "https://testapi.multisafepay.com/v1/json/accounts/{affiliate_account_id}/ubos?api_key={your-account-api-key}" \
--header "accept: application/json" \
--header "Content-Type: application/json" \
--data-raw '{
  "name": "Firstname Lastname",
  "title": "mrs",
  "address": "Mainstreet 123",
  "address_apartment": "",
  "city": "Funtown",
  "state": "Noord-Holland",
  "country": "NL",
  "zipcode": "1234 ZP",
  "birthday": "1980-01-31",
  "country_of_birth": "NL",
  "email": "[email protected]",
  "mobile_phone": "0123456789",
  "office_phone": "0123456789",
  "job_title": "CEO",
  "percentage": 100,
  "type": "control_rights"
}'
Sample response
{
  "data": {
    "account_id": {affiliate_account_id},
    "address": "Mainstreet 123",
    "address_apartment": "",
    "birthday": "1980-01-31",
    "city": "Funtown",
    "country": "NL",
    "country_of_birth": "NL",
    "email": "[email protected]",
    "id": "glmqo15bces6n",
    "job_title": "CEO",
    "mobile_phone": "0123456789",
    "name": "Firstname Lastname",
    "office_phone": "0123456789",
    "percentage": 100,
    "state": "Noord-Holland",
    "title": "mrs",
    "type": "control_rights",
    "zipcode": "1234 ZP"
  },
  "success": true
}

List UBOs

GET https://testapi.multisafepay.com/v1/json/accounts/{affiliate_account_id}/ubos

Retrieve an array of all UBOs linked to a merchant account.

Path parameters

Parameter Description
affiliate_account_id
string
The affiliated merchant ID.
Format: 8 character string, e.g. 12345678. Required.
Response body parameters
Parameter Description
account_id
string
The affiliated merchant ID.
Format: 8 character string, e.g. 12345678.
address
string
The UBO’s address.
Format: Max 100 characters.
address_apartment
string
The UBO’s apartment number.
Format: Max 15 characters.
birthday
string
The UBO’s date of birth.
Format: yyyy-mm-dd (e.g., 1980-01-31).
city
string
The UBO’s city of residence.
Format: Max 100 characters.
country
string
The UBO’s country of residence.
Format: ISO 3166-1 alpha-2, e.g. NL.
country_of_birth
string
The UBO’s country of birth.
Format: ISO 3166-1 alpha-2, e.g. NL.
email
string
The UBO’s email address.
Format: Max 100 characters.
id
string
The unique identifier of the UBO. Referred to as ubo_id.
job_title
string
The UBO’s job title.
Format: Max 100 characters.
mobile_phone
string
The UBO’s mobile phone number.
Format: Max 25 characters.
name
string
The UBO’s full name.
Format: Max 200 characters.
office_phone
string
The UBO’s office phone number.
Format: Max 25 characters.
percentage
integer
The UBO’s percentage of equity.
Format: Non-fractional number from 25 to 100.
state
string
The UBO’s province or state of residence.
Format: Max 100 characters.
title
string
The UBO’s title.
Options: mr or mrs.
type
string
The UBO’s type of equity.
Options: control_rights, shareholder, voting_rights or other.
zipcode
string
The UBO’s ZIP code.
Format: Max 20 characters.
Sample request
curl -X GET "https://testapi.multisafepay.com/v1/json/accounts/{affiliate_account_id}/ubos?api_key={your-account-api-key}" \
--header "accept: application/json" \
Sample response
{
  "data": [
    {
      "account_id": {affiliate_account_id},
      "address": "Mainstreet 123",
      "address_apartment": "",
      "birthday": "1980-01-31",
      "city": "Funtown",
      "country": "NL",
      "country_of_birth": "NL",
      "email": "[email protected]",
      "id": "glmqo15bces6n",
      "job_title": "CEO",
      "mobile_phone": "0123456789",
      "name": "Firstname Lastname",
      "office_phone": "0123456789",
      "percentage": 100,
      "state": "Noord-Holland",
      "title": "mrs",
      "type": "control_rights",
      "zipcode": "1234 ZP"
    }
  ],
  "page": {
    "total": 1
  },
  "success": true
}

Get a UBO

GET https://testapi.multisafepay.com/v1/json/ubos/{ubo_id}?api_key={your-account-api-key}

Retrieve a specific UBO.

Path parameters

Parameter Description
ubo_id string The unique identifier of the UBO you want to retrieve.

The ubo_id is returned as id in the create a UBO and list UBOs requests.
Response body parameters
Parameter Description
account_id
string
The affiliated merchant ID.
Format: 8 character string, e.g. 12345678.
address
string
The UBO’s address.
Format: Max 100 characters.
address_apartment
string
The UBO’s apartment number.
Format: Max 15 characters.
birthday
string
The UBO’s date of birth.
Format: yyyy-mm-dd, e.g. 1980-01-31.
city
string
The UBO’s city of residence.
Format: Max 100 characters.
country
string
The UBO’s country of residence.
Format: ISO 3166-1 alpha-2, e.g. NL.
country_of_birth
string
The UBO’s country of birth.
Format: ISO 3166-1 alpha-2, e.g. NL.
email
string
The UBO’s email address.
Format: Max 100 characters.
id
string
The unique identifier of the UBO. Referred to as ubo_id.
job_title
string
The UBO’s job title.
Format: Max 100 characters.
mobile_phone
string
The UBO’s mobile phone number.
Format: Max 25 characters.
name
string
The UBO’s full name.
Format: Max 200 characters.
office_phone
string
The UBO’s office phone number.
Format: Max 25 characters.
percentage
integer
The UBO’s percentage of equity.
Format: Non-fractional number from 25 to 100.
state
string
The UBO’s province or state of residence.
Format: Max 100 characters.
title
string
The UBO’s title.
Options: mr or mrs.
type
string
The UBO’s type of equity.
Options: control_rights, shareholder, voting_rights or other.
zipcode
string
The UBO’s ZIP code.
Format: Max 20 characters.
Sample request
curl -X GET "https://testapi.multisafepay.com/v1/json/ubos/{ubo_id}?api_key={your-account-api-key}" \
--header "accept: application/json" \
Sample response
{
  "data": {
    "account_id": {affiliate_account_id},
    "address": "Mainstreet 123",
    "address_apartment": "",
    "birthday": "1980-01-31",
    "city": "Funtown",
    "country": "NL",
    "country_of_birth": "NL",
    "email": "[email protected]",
    "id": "{ubo_id}",
    "job_title": "CEO",
    "mobile_phone": "0123456789",
    "name": "Firstname Lastname",
    "office_phone": "0123456789",
    "percentage": 100,
    "state": "Noord-Holland",
    "title": "mrs",
    "type": "control_rights",
    "zipcode": "1234 ZP"
  },
  "success": true
}

Update a UBO

PATCH https://testapi.multisafepay.com/v1/json/ubos/{ubo_id}?api_key={your-account-api-key}

Update information about an existing UBO.

Path parameters

Parameter Description
ubo_id string The unique identifier of the UBO you want to update.

The ubo_id is returned as id in the create a UBO and list UBOs requests.
Request body parameters
Parameter Description
name
string
The UBO’s full name.
Format: Max 200 characters. Optional.
title
string
The UBO’s title.
Options: mr or mrs. Optional.
address
string
The UBO’s address.
Format: Max 100 characters. Optional.
address_apartment
string
The UBO’s apartment number.
Format: Max 15 characters. Optional.
city
string
The UBO’s city of residence.
Format: Max 100 characters. Optional.
state
string
The UBO’s province or state of residence.
Format: Max 100 characters. Optional.
country
string
The UBO’s country of residence.
Format: ISO 3166-1 alpha-2, e.g. NL. Optional.
zipcode
string
The UBO’s ZIP code.
Format: Max 20 characters. Optional.
birthday
string
The UBO’s date of birth.
Format: yyyy-mm-dd, e.g. 1980-01-31. Optional.
country_of_birth
string
The UBO’s country of birth.
Format: ISO 3166-1 alpha-2, e.g. NL. Optional.
email
string
The UBO’s email address.
Format: Max 100 characters. Optional.
mobile_phone
string
The UBO’s mobile phone number.
Format: Max 25 characters. Optional.
office_phone
string
The UBO’s office phone number.
Format: Max 25 characters. Optional.
job_title
string
The UBO’s job title.
Format: Max 100 characters. Optional.
percentage
integer
The UBO’s percentage of equity.
Format: Non-fractional number from 25 to 100. Optional.
type
string
The UBO’s type of equity.
Options: control_rights, shareholder, voting_rights or other. Optional.
Response body parameters

The following are in addition to the request body parameters.

Parameter Description
account_id
string
The affiliated merchant ID.
Format: 8 character string, e.g., 12345678.
id
string
The unique identifier of the UBO. Referred to as ubo_id.
Sample request
curl -X PATCH "https://testapi.multisafepay.com/v1/json/ubos/glmqo15bces6n?api_key={your-account-api-key}" \
--header "accept: application/json" \
--header "Content-Type: application/json" \
--data-raw '{
  "email": "[email protected]" 
}'
Sample response
{
  "data": {
    "account_id": {affiliate_account_id},
    "address": "Mainstreet 123",
    "address_apartment": "",
    "birthday": "1980-01-31",
    "city": "Funtown",
    "country": "NL",
    "country_of_birth": "NL",
    "email": "[email protected]",
    "id": "{ubo_id}",
    "job_title": "CEO",
    "mobile_phone": "0123456789",
    "name": "Firstname Lastname",
    "office_phone": "0123456789",
    "percentage": 100,
    "state": "Noord-Holland",
    "title": "mrs",
    "type": "control_rights",
    "zipcode": "1234 ZP"
  },
  "success": true
}

Add identity document

POST https://testapi.multisafepay.com/v1/json/ubos/{ubo_id}/identitydocs?api_key={your-account-api-key}

Upload an identity document to verify a UBO.

Path parameters

Parameter Description
ubo_id string The unique identifier of the UBO you want to verify.

The ubo_id is returned as id in the create a UBO and list UBOs requests.
Request body parameters
Parameter Description
document_type
string
The type of identity document.
Options: id, passport, driverslicense, proof_of_address
encoded_content
string
Base64 encoded content. Required.
filename
string
The identity document filename.
Format: Max 250 characters. Required.
mime_type
string
The media type of the identity document file.
Options: application/pdf,image/jpeg
Response body parameters

The following are in addition to the request body parameters.

Parameter Description
id
string
The unique identifier of the identity document. Referred to as identitydoc_id.
ubo_id string The unique identifier of a UBO.
Sample request

curl -X POST "https://testapi.multisafepay.com/v1/json/ubos/{ubo_id}/identitydocs?api_key={your-account-api-key}" \
--header "accept: application/json" \
--header "Content-Type: application/json" \
--data-raw '{
  "document_type":"id",
  "encoded_content":"string",
  "filename":"identity-of-ubo.pdf",
  "mime_type":"application/pdf"
}'
Sample response
{
  "data": {
    "document_type": "id",
    "filename": "identity-of-ubo.pdf",
    "id": "agi6ehoreex6a",
    "merchant_id": {affiliate_account_id},
    "mime_type": "application/pdf",
    "ubo_id": "{ubo_id}"
  },
  "success": true
}

List identity documents

GET https://testapi.multisafepay.com/v1/json/ubos/{ubo_id}/identitydocs?api_key={your-account-api-key}

Retrieve an array of all identity documents for a UBO.

Path parameters

Parameter Description
ubo_id string The unique identifier of the UBO you want to retrieve identity documents for.

The ubo_id is returned as id in the create a UBO and list UBOs requests.
Response body parameters
Parameter Description
document_type
string
The type of identity document.
Options: id, passport, driverslicense, proof_of_address
filename
string
The identity document filename.
Format: Max 250 characters.
id
string
The unique identifier of the identity document. Referred to as identitydoc_id.
merchant_id
string
The affiliated merchant ID.
Format: 8 character string, e.g. 12345678.
mime_type
string
The media type of the identity document file.
Options: application/pdf,image/jpeg
ubo_id
string
The unique identifier of a UBO.
Sample request
curl -X GET "https://testapi.multisafepay.com/v1/json/ubos/{ubo_id}/identitydocs?api_key={your-account-api-key}" \
--header "accept: application/json" \
Sample response
{
  "data": [
    {
      "document_type": "identity",
      "filename": "identity-of-ubo.pdf",
      "id": "agi6ehoreex6a",
      "merchant_id": {affiliate_account_id},
      "mime_type": "application/pdf",
      "ubo_id": "{ubo_id}"
    }
  ],
  "page": {
    "total": 1
  },
  "success": true
}

Get identity document

GET https://testapi.multisafepay.com/v1/json/identitydocs/{identitydoc_id}?api_key={your-account-api-key}

Retrieve a specific identity document.

Path parameters

Parameter Description
identitydoc_id
string
The unique identifier of the identity document you want to retrieve.
The identitydoc_id is returned as id in the add identity document and list identity documents requests.
Response body parameters
Parameter Description
document_type
string
The type of identity document.
Options: id, passport, driverslicense, proof_of_address
filename
string
The identity document filename.
Format: Max 250 characters.
id
string
The unique identifier of the identity document. Referred to as identitydoc_id.
merchant_id
string
The affiliated merchant ID.
Format: 8 character string (e.g., 12345678).
mime_type
string
The media type of the identity document file.
Options: application/pdf,image/jpeg
ubo_id
string
The unique identifier of the UBO the identity document is for.
Sample request
curl -X GET https://testapi.multisafepay.com/v1/json/identitydocs/{identitydoc_id}?api_key={your-account-api-key}
--header "accept: application/json" \
Sample response
{
  "data": {
    "document_type": "identity",
    "filename": "identity-of-ubo.pdf",
    "id": "{identitydoc_id}",
    "merchant_id": {affiliate_merchant_id},
    "mime_type": "application/pdf",
    "ubo_id": "{ubo_id}"
  },
  "success": true
}

Next steps

Now that you have created an affiliated merchant account and added one or multiple bank account and UBOs, complete the onboarding by adding one or multiple websites using the unique affiliated merchant id .

Feedback

Propose a change on GitHubexternal-link-icon or
send an email to [email protected]

Other languages

For an explanation in another language, contact your account manager.