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:

Create a UBO: Add a UBO to a merchant account.
List UBOs: Retrieve all UBOs for a merchant account.
Get UBO: Retrieve a specific UBO by its identifier.
Update UBO: Update a UBO.

Add and retrieve UBO identification documents:

Add identity document: Add an identity document to an existing UBO.
List identity documents: Retrieve all identity documents for a UBO.
Get identity document: Retrieve a specific identity document for a UBO.

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 .

Add bank accounts

Add websites

Feedback

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

Other languages

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