Add UBOs


Use the following requests to add, retrieve or update ultimate beneficial owner (UBO) details linked to a merchant account affiliated with your partner account:

  1. Create a UBO: Add a UBO to a merchant account.
  2. List UBOs: Retrieve all UBOs for a merchant account.
  3. Get UBO: Retrieve a single UBO by its identifier.
  4. Update UBO: Update a UBO.
  5. Add identity document: Add an identity document to an existing UBO.
  6. List identity documents: Retrieve all identity documents for a UBO.
  7. Get identity document: Retrieve a single identity document for a UBO.

The process

The requests above can be divided into the following steps:

  1. Add UBOs: Use the first four requests to add, retrieve and update UBOs linked to a merchant account.
  2. Add identity documents: Use the last three requests to add and retrieve identity documents of UBOs linked to a merchant account. These documents are used to perform our UBO verification.

About parameters

For every parameter, we specify whether it’s required or optional. However, this label refers only to the technical requirements for valid API requests. To perform our UBO verification, we may need optional parameters to be supplied.

Authentication

All seven UBO requests require a partner account API key. This is not the same as a website 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/{account_id}/ubos

Add a new UBO to a merchant account.

Path parameters

Key Description
account_id
string
Merchant ID.
Format: 8 character string (e.g., 12345678). Required.

Query parameters

Key Description
name
string
UBO’s full name.
Format: max 200 characters. Required.
title
string
UBO’s title.
Options: mr or mrs. Required.
address
string
UBO’s address.
Format: max 100 characters. Optional.
address_apartment
string
UBO’s apartment number.
Format: max 15 characters. Optional.
city
string
UBO’s city of residence.
Format: max 100 characters. Optional.
state
string
UBO’s province or state of residence.
Format: max 100 characters. Optional.
country
string
UBO’s country of residence.
Format: ISO 3166-1 alpha-2 (e.g., NL). Required.
zipcode
string
UBO’s zip code.
Format: max 20 characters. Optional.
birthday
string
UBO’s date of birth.
Format: yyyy-mm-dd (e.g., 1980-01-31). Required.
country_of_birth
string
UBO’s country of birth.
Format: ISO 3166-1 alpha-2 (e.g., NL). Required.
email
string
UBO’s email address.
Format: max 100 characters. Required.
mobile_phone
string
UBO’s mobile phone number.
Format: max 25 characters. Optional.
office_phone
string
UBO’s office phone number.
Format: max 25 characters. Optional.
fax
string
UBO’s fax number.
Format: max 15 characters. Optional.
job_title
string
UBO’s job title.
Format: max 100 characters. Required.
percentage
integer
UBO’s percentage of equity.
Format: non-fractional number from 25 to 100. Required.
type
string
UBO’s type of equity.
Options: control_rights, shareholder, voting_rights or other. Required.
Sample request
curl -X POST "https://testapi.multisafepay.com/v1/json/accounts/12345678/ubos" \
--header "accept: application/json" \
--header "Content-Type: application/json" \
--header "api_key: <your-account-api-key>" \
--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": "the Netherlands",
  "email": "[email protected]",
  "mobile_phone": "0123456789",
  "office_phone": "0123456789",
  "fax": "0123456789",
  "job_title": "CEO",
  "percentage": 100,
  "type": "control_rights",
}'
Sample response
{
  "data": {
    "account_id": 12345678,
    "address": "Mainstreet 123",
    "address_apartment": "",
    "birthday": "1980-01-31",
    "city": "Funtown",
    "country": "NL",
    "country_of_birth": "NL",
    "email": "[email protected]",
    "fax": "0123456789",
    "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
}

id → the unique identifier of the UBO


List UBOs

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

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

Path parameters

Key Description
account_id
string
Merchant ID.
Format: 8 character string (e.g., 12345678). Required.
Sample request
curl -X GET "https://testapi.multisafepay.com/v1/json/accounts/12345678/ubos" \
--header "accept: application/json" \
--header "api_key: <your-account-api-key>"
Sample response
{
  "data": [
    {
      "account_id": 12345678,
      "address": "Mainstreet 123",
      "address_apartment": "",
      "birthday": "1980-01-31",
      "city": "Funtown",
      "country": "NL",
      "country_of_birth": "NL",
      "email": "[email protected]",
      "fax": "0123456789",
      "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
}

id → the unique identifier of the UBO


Get a UBO

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

Retrieve a single UBO by its identifier.

Path parameters

Key Description
ubo_id
string
The unique identifier of a UBO.
Tip: The ubo_id is returned as id in the create a UBO, list UBOs, and get a UBO request.
Sample request
curl -X GET "https://testapi.multisafepay.com/v1/json/ubos/glmqo15bces6m" \
--header "accept: application/json" \
--header "api_key: <your-account-api-key>"
Sample response
{
  "data": {
    "account_id": 12345678,
    "address": "Mainstreet 123",
    "address_apartment": "",
    "birthday": "1980-01-31",
    "city": "Funtown",
    "country": "NL",
    "country_of_birth": "NL",
    "email": "[email protected]",
    "fax": "0123456789",
    "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
}

id → the unique identifier of the UBO


Update a UBO

PATCH https://testapi.multisafepay.com/v1/json/ubos/{ubo_id}

Update information about an existing UBO.

Path parameters

Key Description
ubo_id
string
The unique identifier of a UBO.
Tip: The ubo_id is returned as id in the create a UBO, list UBOs, and get a UBO request.

Query parameters

Key Description
name
string
UBO’s full name.
Format: max 200 characters. Optional.
title
string
UBO’s title.
Options: mr or mrs. Optional.
address
string
UBO’s address.
Format: max 100 characters. Optional.
address_apartment
string
UBO’s apartment number.
Format: max 15 characters. Optional.
city
string
UBO’s city of residence.
Format: max 100 characters. Optional.
state
string
UBO’s province or state of residence.
Format: max 100 characters. Optional.
country
string
UBO’s country of residence.
Format: ISO 3166-1 alpha-2 (e.g., NL). Optional.
zipcode
string
UBO’s zip code.
Format: max 20 characters. Optional.
birthday
string
UBO’s date of birth.
Format: yyyy-mm-dd (e.g., 1980-01-31). Optional.
country_of_birth
string
UBO’s country of birth.
Format: ISO 3166-1 alpha-2 (e.g., NL). Optional.
email
string
UBO’s email address.
Format: max 100 characters. Optional.
mobile_phone
string
UBO’s mobile phone number.
Format: max 25 characters. Optional.
office_phone
string
UBO’s office phone number.
Format: max 25 characters. Optional.
fax
string
UBO’s fax number.
Format: max 15 characters. Optional.
job_title
string
UBO’s job title.
Format: max 100 characters. Optional.
percentage
integer
UBO’s percentage of equity.
Format: non-fractional number from 25 to 100. Optional.
type
string
UBO’s type of equity.
Options: control_rights, shareholder, voting_rights or other. Optional.
Sample request
curl -X PATCH "https://testapi.multisafepay.com/v1/json/ubos/glmqo15bces6n" \
--header "accept: application/json" \
--header "api_key: <your-account-api-key>" \
--header "Content-Type: application/json" \
--data-raw '{
  "email": "[email protected]" 
}'
Sample response
{
  "data": {
    "account_id": 12345678,
    "address": "Mainstreet 123",
    "address_apartment": "",
    "birthday": "1980-01-31",
    "city": "Funtown",
    "country": "NL",
    "country_of_birth": "NL",
    "email": "[email protected]",
    "fax": "0123456789",
    "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
}

Add identity document

POST https://testapi.multisafepay.com/v1/json/ubos/{ubo_id}/identitydocs

Upload an identity document used to verify the UBO.

Path parameters

Key Description
ubo_id
string
The unique identifier of a UBO.
Tip: The ubo_id is returned as id in the create a UBO, list UBOs, and get a UBO request.

Query parameters

Key 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
Name of the identity document file.
Format: max 250 characters. Required.
mime_type
string
Media type of the identity document file.
Options: application/pdf,image/jpeg
Sample request

curl -X POST "https://testapi.multisafepay.com/v1/json/ubos/glmqo15bces6n/identitydocs" \
--header "accept: application/json" \
--header "Content-Type: application/json" \
--header "api_key: <your-account-api-key>" \
--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": 12345678,
    "mime_type": "application/pdf",
    "ubo_id": "glmqo15bces6n"
  },
  "success": true
}

id → the unique identifier of the identity document


List identity documents

GET https://testapi.multisafepay.com/v1/json/ubos/{ubo_id}/identitydocs

Retrieve an array of all identity documents linked to a UBO.

Path parameters

Key Description
ubo_id
string
The unique identifier of a UBO.
Tip: The ubo_id is returned as id in the create a UBO, list UBOs, and get a UBO request.
Sample request
curl -X GET "https://testapi.multisafepay.com/v1/json/ubos/glmqo15bces6n/identitydocs" \
--header "accept: application/json" \
--header "api_key: <your-account-api-key>"
Sample response
{
  "data": [
    {
      "document_type": "identity",
      "filename": "identity-of-ubo.pdf",
      "id": "agi6ehoreex6a",
      "merchant_id": 12345678,
      "mime_type": "application/pdf",
      "ubo_id": "glmqo15bces6n"
    }
  ],
  "page": {
    "total": 1
  },
  "success": true
}

id → the unique identifier of the identity document


Get identity document

GET https://testapi.multisafepay.com/v1/json/identitydocs/{identitydoc_id}

Description.

Path parameters

Key Description
identitydoc_id
string
The unique identifier of the identity document.
Tip: The identitydoc_id is returned as id in the add identity document and list identity documents request.
Sample request
curl -X GET https://testapi.multisafepay.com/v1/json/identitydocs/agi6ehoreex6a
--header "accept: application/json" \
--header "api_key: <your-account-api-key>"
Sample response
{
  "data": {
    "document_type": "identity",
    "filename": "identity-of-ubo.pdf",
    "id": "agi6ehoreex6a",
    "merchant_id": 11979097,
    "mime_type": "application/pdf",
    "ubo_id": "glmqo15bces6n"
  },
  "success": true
}

Next steps

Now that you have created a Merchant account and added one or multiple bank account and UBOs, complete the onboarding by adding one or multiple websites using the unique Merchant account 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.