Language

Adding beneficial owner(s)

The Basics

To help the government fight financial crime, the existing United States Federal customer due diligence rules were amended to clarify and strengthen customer due diligence requirements.The customer due diligence rule imposes a new requirement for verifying the identity of beneficial owner(s) of Dwolla’s partners and users that are not natural persons. These legal entities can be abused to disguise involvement in terrorist financing, money laundering, tax evasion, corruption, fraud, and other financial crimes. Requiring the disclosure of key individuals who ultimately own or control a legal entity (i.e., the beneficial owners) helps law enforcement investigate and prosecute these crimes.

Exemptions and non-exemptions

Business types required to provide beneficial owner information and certify beneficial ownership

A beneficial owner is someone that owns, directly or indirectly, 25% or more of the equity interests of the business. Businesses that are not exempt from beneficial owner requirements and need to submit beneficial owner information include:

  • Corporations
  • LLC’s
  • Partnerships

To learn how to add beneficial owners to your Customer, read on in the next section.

Business types exempt from providing beneficial owner information, but must certify beneficial ownership

Businesses types that are classified in one of the categories below are exempt from beneficial owner requirements. However, the individual creating the business verified Customer account will be still be required to explicitly certify no owners to attest to the exemption. Depending on what the legal entity is, the following business types will designate the businessType as either corporation or llc in the create a Customer API request:

  • Non-profits
  • Public corporations

Business types are exempt from providing beneficial owner information and exempt from certifying beneficial ownership

The following business types will not need to add beneficial owners or explicitly certify beneficial ownership:

  • Sole proprietorships
  • Unincorporated association - will sign up as a sole proprietorship
  • Trusts - will sign up as a sole proprietorship
  • Business verified Customer accounts created prior to May 11th, 2018 - These Customers are “grandfathered” into the updated customer due diligence rules.

If your business is exempt or if there is no individual with at least 25% ownership, your Customer can go straight to certifying that there is no beneficial owner.

Create a beneficial owner for a Business Verified Customer

To create a beneficial owner, use the create a beneficial owner endpoint.

Events

As a developer, you can expect these events to be triggered when a beneficial owner is successfully created and systematically verified:

  1. customer_beneficial_owner_created
  2. customer_beneficial_owner_verified

Request Parameters

ParameterRequiredTypeDescription
firstNameyesstringThe legal first name of the Beneficial Owner.
lastNameyesstringThe legal last name of the Beneficial Owner.
ssnconditionalstringFull nine digits of Beneficial Owner’s social security number.
dateOfBirthYesstringBeneficial owner’s date of birth in YYYY-MM-DD format. Must be 18 years or older.
addressYesobjectStreet number, street name of Beneficial Owner’s physical address
passportconditionalobjectAn optional passport JSON object. Required for foreign individuals. Includes passport identification number and country.

Address JSON object

ParameterRequiredTypeDescription
address1yesstringFirst line of the street address of the beneficial owner’s permanent residence. Note: PO Boxes are not allowed.
address2nostringSecond line of the street address of the beneficial owner’s permanent residence. Note: PO Boxes are not allowed.
address3nostringSecond line of the street address of the beneficial owner’s permanent residence. Note: PO Boxes are not allowed.
cityyesstringCity of beneficial owner’s permanent residence.
stateProvinceRegionyesstringTwo-letter US state or territory abbreviation code of Beneficial Owner’s physical address. For two-letter abbreviation reference, check out the US Postal Service guide.
countryyesstringCountry of beneficial owner’s permanent residence. Two digit ISO code, e.g. US.
postalCodeyesstringPostal code of beneficial owner’s permanent residence. Should be a five digit postal code, e.g. 50314.

Passport JSON object

ParameterRequiredTypeDescription
numberconditionalstringRequired if Beneficial resides outside of United States and has no Social Security number.
countryconditionalstringCountry of issued passport. Two digit ISO code, e.g. US.

Request and Response

POST https://api-sandbox.dwolla.com/customers/07d59716-ef22-4fe6-98e8-f3190233dfb8/beneficial-owners
Content-Type: application/vnd.dwolla.v1.hal+json
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY

{
  "firstName": "Jane",
  "lastName": "Doe",
  "ssn": "123-56-7890",
  "dateOfBirth": "1960-11-30",
  "address": {
    "address1": "123 Main St.",
    "address2": "Apt 12",
    "city": "New York",
    "stateProvinceRegion": "NY",
    "country": "US",
    "postalCode": "10005"
  }
}

HTTP/1.1 201 Created
Location: https://api.dwolla.com/beneficial-owners/FC451A7A-AE30-4404-AB95-E3553FCD733F
<?php
$customersApi = new DwollaSwagger\CustomersApi($apiClient);
$verified_customer = 'https://api-sandbox.dwolla.com/customers/07d59716-ef22-4fe6-98e8-f3190233dfb8';

$addOwner = $customersApi->addBeneficialOwner([
      'firstName' => 'Jane',
      'lastName'=> 'Doe',
      'dateOfBirth' => '1960-11-30',
      'ssn' => '123-56-7890',
      'address' =>
      [
          'address1' => '123 Main St',
          'address2' => 'Apt 12',
          'city' => 'New York',
          'stateProvinceRegion' => 'NY',
          'postalCode' => '10005',
          'country' => 'US'
      ],
  ], $verified_customer);
?>
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
customer_url = 'https://api-sandbox.dwolla.com/customers/AB443D36-3757-44C1-A1B4-29727FB3111C'
request_body = {
  :firstName => 'Jane',
  :lastName => 'Doe',
  :ssn => '123-56-7890',
  :dateOfBirth => '1960-11-30',
  :address => {
    :address1 => '123 Main St',
    :address2 => 'Apt 12'
    :city => 'New York',
    :stateProvinceRegion => 'NY',
    :country => 'US',
    :postalCode => '10005'
  }
}

beneficial_owner = app_token.post "#{customer_url}/beneficial-owners", request_body
beneficial_owner.response_headers[:location] # => "https://api-sandbox.dwolla.com/beneficial-owners/AB443D36-3757-44C1-A1B4-29727FB3111C"
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
customer_url = 'https://api-sandbox.dwolla.com/customers/AB443D36-3757-44C1-A1B4-29727FB3111C'
request_body = {
  'firstName': 'Jane',
  'lastName': 'Doe',
  'dateOfBirth': '1960-11-30'
  'ssn': '123-56-7890'
  'address': {
    'address1': '99-99 33rd St',
    'address2': 'Apt 12',
    'city': 'New York',
    'stateProvinceRegion': 'NY',
    'country': 'US'
    'postalCode': '10005'
  }
}

beneficial_owner = app_token.post('%s/beneficial-owners' % customer_url, request_body)
beneficial_owner.headers['location'] # => 'https://api-sandbox.dwolla.com/beneficial-owners/AB443D36-3757-44C1-A1B4-29727FB3111C'
var customerUrl = 'https://api-sandbox.dwolla.com/customers/07d59716-ef22-4fe6-98e8-f3190233dfb8';
var requestBody = {
  firstName: 'Jane',
  lastName: 'Doe',
  dateOfBirth: '1960-11-30',
  ssn: '123-56-7890',
  address: {
    address1: '99-99 33rd St',
    address2: 'Apt 12',
    city: 'Some City',
    stateProvinceRegion: 'NY',
    country: 'US'
    postalCode: '10005'
  }
};

appToken
  .post(`${customerUrl}/beneficial-owners`, requestBody)
  .then(res => res.headers.get('location')); // => 'https://api-sandbox.dwolla.com/beneficial-owners/FC451A7A-AE30-4404-AB95-E3553FCD733F'

Check the status of an individual Beneficial Owner

After a beneficial owner has been created, the beneficial owner’s identity needs to go through a verification process. A beneficial owner that has a status of incomplete or document will impact the business verified Customer’s eligibility to send or receive funds. When a beneficial owner has been successfully verified by Dwolla, the business verified Customer’s status will be set to verified. Reference the table below for more information on the events that correspond to each of the beneficial owner statuses:

Individual Beneficial Owner statuses and events

Individual Beneficial Owner StatusDescriptionEvent topic name
VerifiedBeneficial owner has been identity verified.customerbeneficialowner_verified
DocumentBeneficial owner must upload a document in order to be verified.customerbeneficialownerdocumentneeded
IncompleteThe initial verification attempt failed because the information provided did not satisfy our verification check. You can make one additional attempt by changing some or all the attributes of the existing Customer with an update request.customerbeneficialownerreverificationneeded

Let’s check to see if the Owner was successfully verified or not. We are going to use the location of the Beneficial Owner resource that was just created.

Request and response - retrieve a beneficial owner status

GET https://api-sandbox.dwolla.com/beneficial-owners/07D59716-EF22-4FE6-98E8-F3190233DFB8
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY

...

{
    "_links": {
        "self": {
            "href": "https://api-sandbox.dwolla.com/beneficial-owners/00cb67f2-768c-4ee3-ac81-73bc4faf9c2b",
            "type": "application/vnd.dwolla.v1.hal+json",
            "resource-type": "beneficial-owner"
        },
        "retry-verification": {
            "href": "https://api-sandbox.dwolla.com/beneficial-owners/00cb67f2-768c-4ee3-ac81-73bc4faf9c2b",
            "type": "application/vnd.dwolla.v1.hal+json",
            "resource-type": "beneficial-owner"
        }
    },
    "id": "00cb67f2-768c-4ee3-ac81-73bc4faf9c2b",
    "firstName": "Jane",
    "lastName": "Owner",
    "address": {
        "address1": "123 Main St.",
        "city": "New York",
        "stateProvinceRegion": "NY",
        "country": "US",
        "postalCode": "10005"
    },
    "verificationStatus": "verified"
}
$beneficialOwnersApi = new DwollaSwagger\BeneficialownersApi($apiClient);
$owner = 'https://api-sandbox.dwolla.com/beneficial-owners/00cb67f2-768c-4ee3-ac81-73bc4faf9c2b';
$ownerStatus = $beneficialOwnersApi->getById($owner);
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
beneficial_owner_url = 'https://api-sandbox.dwolla.com/beneficial-owners/07d59716-ef22-4fe6-98e8-f3190233dfb8'

beneficial_owner = app_token.get beneficial_owner_url
beneficial_owner.verificationStatus # => "verified"
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
beneficial_owner_url = 'https://api-sandbox.dwolla.com/beneficial-owners/07d59716-ef22-4fe6-98e8-f3190233dfB8'

beneficial_owner = app_token.get(beneficial_owner_url)
beneficial_owner.body['verificationStatus']
var beneficialOwnerUrl = 'https://api-sandbox.dwolla.com/beneficial-owners/07d59716-ef22-4fe6-98e8-f3190233dfb8';

appToken
  .get(beneficialOwnerUrl)
  .then(res => res.body.verificationStatus); // => 'verified'

Handling an individual beneficial owner Status

Congrats! You have created a beneficial owner for a business verified Customer, however, the successful creation of a beneficial Owner doesn’t necessarily mean they are identity verified. You will want to ensure that the beneficial Owner is verified, as the business verified Customer will be unable to send or receive funds until the owner has a verified status.

Handling incomplete status

An incomplete status occurs when a beneficial owner’s identity scores are too low during the initial verification attempt. Dwolla will trigger a customer_beneficial_owner_reverification_needed event which notifies your application to prompt the Customer to submit another identity verification attempt for the beneficial owner. The second attempt will give our identity vendor more accurate information in an attempt to receive a sufficient score to approve the beneficial owner. The Customer will only have one opportunity to correct any mistakes.

Please note: you need to gather new information if the beneficial owner is placed into the incomplete status; simply passing the same information will result in the same insufficient scores. All fields that were required in the initial beneficial owner creation attempt will be required in the incomplete attempt.

Request and Response - update beneficial owner

POST https://api-sandbox.dwolla.com/beneficial-owners/07d59716-ef22-4fe6-98e8-f3190233dfb8
Content-Type: application/vnd.dwolla.v1.hal+json
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY

{
  "firstName": "beneficial",
  "lastName": "owner",
  "ssn": "123-54-6789",
  "dateOfBirth": "1963-11-11",
  "address": {
    "address1": "123 Corrected St.",
    "address2": "Apt 123",
    "city": "Des Moines",
    "stateProvinceRegion": "IA",
    "country": "US",
    "postalCode": "50309"
  }
}

...

{
    "_links": {
        "self": {
            "href": "https://api-sandbox.dwolla.com/beneficial-owners/07d59716-ef22-4fe6-98e8-f3190233dfb8",
            "type": "application/vnd.dwolla.v1.hal+json",
            "resource-type": "beneficial-owner"
        }
    },
    "id": "00cb67f2-768c-4ee3-ac81-73bc4faf9c2b",
    "firstName": "beneficial",
    "lastName": "owner",
    "address": {
        "address1": "123 Corrected St.",
        "address2": "Apt 123",
        "city": "Des Moines",
        "stateProvinceRegion": "IA",
        "country": "US",
        "postalCode": "50309"
    },
    "verificationStatus": "verified"
}
<?php
$beneficialOwnersApi = new DwollaSwagger\BeneficialownersApi($apiClient);

$beneficialOwnerUrl = 'https://api-sandbox.dwolla.com/beneficial-owners/07d59716-ef22-4fe6-98e8-f3190233dfb8';
$updateBeneficialOwner = $beneficialOwnersApi->update([
      'firstName' => 'beneficial',
      'lastName'=> 'owner',
      'dateOfBirth' => '1963-11-11',
      'ssn' => '123-54-6789',
      'address' =>
      [
          'address1' => '123 Corrected St.',
          'address2' => 'Apt 123',
          'city' => 'Des Moines',
          'stateProvinceRegion' => 'IA',
          'postalCode' => '50309',
          'country' => 'US'
      ],
  ], $beneficialOwnerUrl);

$updateBeneficialOwner->id; # => "07d59716-ef22-4fe6-98e8-f3190233dfb"
?>
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
beneficial_owner_url = 'https://api-sandbox.dwolla.com/beneficial-owners/07d59716-ef22-4fe6-98e8-f3190233dfb8'
request_body = {
  :firstName => 'beneficial',
  :lastName => 'owner',
  :ssn => '123-54-6789',
  :dateOfBirth => '1963-11-11',
  :address => {
    :address1 => '123 Corrected St',
    :city => 'Des Moines',
    :stateProvinceRegion => 'IA',
    :country => 'US',
    :postalCode => '50309'
  }
}

update_beneficial_owner = app_token.post beneficial_owner_url, request_body
update_beneficial_owner.id # => "07d59716-ef22-4fe6-98e8-f3190233dfb8"
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
beneficial_owner_url = 'https://api-sandbox.dwolla.com/beneficial-owners/07d59716-ef22-4fe6-98e8-f3190233dfb8'
request_body = {
  'firstName': 'beneficial',
  'lastName': 'owner',
  'dateOfBirth': '1963-11-11'
  'ssn': '123-54-6789'
  'address': {
    'address1': '123 Corrected St',
    'city': 'Des Moines',
    'stateProvinceRegion': 'IA',
    'country': 'US'
    'postalCode': '50309'
  }
}

update_beneficial_owner = app_token.post(beneficial_owner_url, request_body)
update_beneficial_owner.body.id # => '07d59716-ef22-4fe6-98e8-f3190233dfb8'
var beneficialOwnerUrl = 'https://api-sandbox.dwolla.com/beneficial-owners/07d59716-ef22-4fe6-98e8-f3190233dfb8';
var requestBody = {
  firstName: 'beneficial',
  lastName: 'owner',
  dateOfBirth: '1963-11-11',
  ssn: '123-54-6789',
  address: {
    address1: '123 Corrected St',
    city: 'Des Moines',
    stateProvinceRegion: 'IA',
    country: 'US'
    postalCode: '50309'
  }
};

appToken
  .post(beneficialOwnerUrl, requestBody)
  .then(res => res.body.id); // => '07d59716-ef22-4fe6-98e8-f3190233dfb8'

Check the beneficial owner’s status again. The beneficial owner will either be in the verified or document state of verification.

Handling document status

If a beneficial owner is not verified, the only other state the beneficial owner can be in is document. If the beneficial owner has a status of document, they will need to upload additional pieces of information in order to verify their identity. Use the create a document endpoint when uploading a colored scan of the identifying document. The document(s) will then be reviewed by Dwolla; this review may take up to 1-2 business days to approve or reject.

Determining verification documents needed

US persons

A scanned photo of the Beneficial Owner’s identifying document can be specified as documentType: license (state issued driver’s license), or idCard (other U.S. government-issued photo id card).

Non-US persons

A scanned photo of the Beneficial Owner’s identifying document can be specified as documentType: passport

Uploading a document

To upload a photo of the document, you’ll initiate a multipart form-data POST request from your backend server to the beneficial owners documents endpoint. The file must be either a .jpg, .jpeg, .png, .tif, or .pdf. Files must be no larger than 10MB in size.

You’ll also get a beneficial_owner_verification_document_uploaded event to let you know the document was successfully uploaded.

Request and Response

curl -X POST
\ -H "Authorization: Bearer tJlyMNW6e3QVbzHjeJ9JvAPsRglFjwnba4NdfCzsYJm7XbckcR"
\ -H "Accept: application/vnd.dwolla.v1.hal+json"
\ -H "Cache-Control: no-cache"
\ -H "Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW"
\ -F "documentType=passport"
\ -F "file=@foo.png"
\ 'https://api-sandbox.dwolla.com/beneficial-owners/1de32ec7-ff0b-4c0c-9f09-19629e6788ce/documents'

...

HTTP/1.1 201 Created
Location: https://api-sandbox.dwolla.com/documents/11fe0bab-39bd-42ee-bb39-275afcc050d0

No example for this language yet
beneficial_owner_url = 'https://api-sandbox.dwolla.com/beneficial-owners/1DE32EC7-FF0B-4C0C-9F09-19629E6788CE'

file = Faraday::UploadIO.new('mclovin.jpg', 'image/jpeg')
document = app_token.post "#{beneficial_owner_url}/documents", file: file, documentType: 'license'
document.response_headers[:location] # => "https://api.dwolla.com/documents/fb919e0b-ffbe-4268-b1e2-947b44328a16"
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
beneficial_owner_url = 'https://api-sandbox.dwolla.com/beneficial-owners/1DE32EC7-FF0B-4C0C-9F09-19629E6788CE'

document = app_token.post('%s/documents' % beneficial_owner_url, file = open('janedoe.jpg', 'rb'), documentType = 'license')
document.headers['location'] # => 'https://api-sandbox.dwolla.com/documents/fb919e0b-ffbe-4268-b1e2-947b44328a16'
var beneficialOwnerUrl = 'https://api-sandbox.dwolla.com/beneficial-owners/1DE32EC7-FF0B-4C0C-9F09-19629E6788CE';

var requestBody = new FormData();
body.append('file', fs.createReadStream('mclovin.jpg'), {
  filename: 'mclovin.jpg',
  contentType: 'image/jpeg',
  knownLength: fs.statSync('mclovin.jpg').size
});
body.append('documentType', 'license');

appToken
  .post(`${beneficialOwnerUrl}/documents`, requestBody)
  .then(res => res.headers.get('location')); // => "https://api-sandbox.dwolla.com/documents/fb919e0b-ffbe-4268-b1e2-947b44328a16"

Remove and update a Beneficial Owner

If an individual beneficial owner wants to update their information, that individual beneficial owner will first need to be removed.

Request and Response

DELETE https://api-sandbox.dwolla.com/beneficial-owners/692486f8-29f6-4516-a6a5-c69fd2ce854c
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY

...

{
    "_links": {
        "self": {
            "href": "https://api-sandbox.dwolla.com/beneficial-owners/0f394602-d714-4d77-9d58-3a3e8394bcdd",
            "type": "application/vnd.dwolla.v1.hal+json",
            "resource-type": "beneficial-owner"
        }
    },
    "id": "0f394602-d714-4d77-9d58-3a3e8394bcdd",
    "firstName": "B",
    "lastName": "Owner",
    "address": {
        "address1": "123 Main St.",
        "city": "New York",
        "stateProvinceRegion": "NY",
        "country": "US",
        "postalCode": "10005"
    },
    "verificationStatus": "verified"
}

...

HTTP 200 OK
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
beneficial_owner_url = 'https://api-sandbox.dwolla.com/beneficial-owners/692486f8-29f6-4516-a6a5-c69fd2ce854c'

app_token.delete beneficial_owner_url
var beneficialOwnerUrl = 'https://api-sandbox.dwolla.com/beneficial-owners/692486f8-29f6-4516-a6a5-c69fd2ce854c';

appToken.delete(beneficialOwnerUrl);
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
beneficial_owner_url = 'https://api-sandbox.dwolla.com/beneficial-owners/692486f8-29f6-4516-a6a5-c69fd2ce854c'

app_token.delete(beneficial_owner_url)
<?php
$beneficialOwnersApi = new DwollaSwagger\BeneficialownersApi($apiClient);
$beneficialOwner = 'https://api-sandbox.dwolla.com/beneficial-owners/692486f8-29f6-4516-a6a5-c69fd2ce854c';
$deletedBeneficialOwner = $beneficialOwnersApi->deleteById($beneficialOwner);
?>

After removal of a Beneficial Owner, they can be re-added and go through the verification process again. You can also remove a beneficial owner if they no longer own 25% or more of the business.

The successful creation and verification of a beneficial owner doesn’t necessarily mean the business verified Customer is verified and ready to send or receive funds. The final step in creating a business verified Customer is to certify that all information provided is correct. Read on to view the procedures on how to certify your owners.

To learn how to certify beneficial owners to your Customer, read on to our next article.


Next steps

Review previous steps


Status
Production: Operational

Financial institutions play an important role in the Dwolla network.

Dwolla, Inc. is an agent of Veridian Credit Union and all funds associated with your account in our network are held in one or more pooled accounts at Veridian Credit Union. These funds may not be eligible for share insurance by the National Credit Union Share Insurance Fund. Dwolla, Inc. is the operator of a software platform that communicates user instructions for funds transfers to Veridian Credit Union.