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.

A beneficial owner is someone that owns, directly or indirectly, 25% or more of the equity interests of the business. 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.

Retrieve beneficial owner(s) status

To determine if a business verified Customer is exempt from beneficial owner(s), your business verified Customer will need to indicate its type of business classification.

Exempt and Non-exempt

Certain business types are exempt from beneficial ownership requirements. These include:

  • Sole proprietorships
  • Public corporations

Businesses that are not exempt from the beneficial ownership requirements are as follows:

  • Corporations
  • LLC’s
  • Partnerships
  1. If a business is not exempt, a business verified Customer cannot transact or initiate transfers until the beneficial owners have been verified.

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

Create a beneficial owner for a Business Verified Customer

To create a beneficial owner, use the 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.

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-456-7890",
  "dateOfBirth": "1960-11-30",
  "address": {
    "address1": "123 Main St.",
    "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
No example for this language yet
# 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 => 'John',
  :lastName => 'Doe',
  :ssn => '123-456-7890',
  :dateOfBirth => '1970-01-01',
  :address => {
    :address1 => '99-99 33rd St',
    :city => 'Some City',
    :stateProvinceRegion => 'NY',
    :country => 'US',
    :postalCode => '11101'
  }
}

beneficial_owner = app_token.post "#{customer_url}/beneficial-owners", request_body
beneficial_owner.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': 'John',
  'lastName': 'Doe',
  'dateOfBirth': '1970-01-01'
  'ssn': '123-456-7890'
  'address': {
    'address1': '99-99 33rd St',
    'city': 'Some City',
    'stateProvinceRegion': 'NY',
    'country': 'US'
    'postalCode': '11101'
  }
}

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: 'John',
  lastName: 'Doe',
  dateOfBirth: '1970-01-01',
  ssn: '123-456-7890',
  address: {
    address1: '99-99 33rd St',
    city: 'Some City',
    stateProvinceRegion: 'NY',
    country: 'US'
    postalCode: '11101'
  }
};

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 who is unverified cascades to the business verified Customer, thus making the business verified Customer ineligible 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.

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.

Individual Beneficial Owner Status

Individual Beneficial Owner StatusDescription
VerifiedBeneficial owner has been identity verified
DocumentBeneficial owner must upload a document in order to be verified
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 a POST request

Individual 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
no example for this language yet.
# 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.firstName # => "Jane"
# 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['firstName']
var beneficialOwnerUrl = 'https://api-sandbox.dwolla.com/beneficial-owners/07d59716-ef22-4fe6-98e8-f3190233dfb8';

appToken
  .get(beneficialOwnerUrl)
  .then(res => res.body.firstName); // => 'Jane'

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 then.

  1. Your business verified Customer will stay in `document` status until all beneficial owner information has been provided and verified.

Handling incomplete status

An incomplete status occurs when a beneficial owner’s identity scores are too low during the initial verification attempt. You will submit another identity verification attempt for the beneficial owner via the Dwolla API in order to give our identity vendor more accurate information in an attempt to receive a sufficient score to approve the beneficial owner. You will only l have one opportunity to correct any mistakes.

Please note: you need to gather new information if the beneficial owner is placed into the retry 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

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-456-7890",
  "dateOfBirth": "1960-11-30",
  "address": {
    "address1": "123 Main St.",
    "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
no example for this language yet
# 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 => 'John',
  :lastName => 'Doe',
  :ssn => '123-456-7890',
  :dateOfBirth => '1970-01-01',
  :address => {
    :address1 => '99-99 33rd St',
    :city => 'Some City',
    :stateProvinceRegion => 'NY',
    :country => 'US',
    :postalCode => '11101'
  }
}

beneficial_owner = app_token.post "#{customer_url}/beneficial-owners", request_body
beneficial_owner.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': 'John',
  'lastName': 'Doe',
  'dateOfBirth': '1970-01-01'
  'ssn': '123-456-7890'
  'address': {
    'address1': '99-99 33rd St',
    'city': 'Some City',
    'stateProvinceRegion': 'NY',
    'country': 'US'
    'postalCode': '11101'
  }
}

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: 'John',
  lastName: 'Doe',
  dateOfBirth: '1970-01-01',
  ssn: '123-456-7890',
  address: {
    address1: '99-99 33rd St',
    city: 'Some City',
    stateProvinceRegion: 'NY',
    country: 'US'
    postalCode: '11101'
  }
};

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 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.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' % customer_url, file = open('mclovin.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 an Individual 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

POST https://api-sandbox.dwolla.com/beneficial-owners/692486f8-29f6-4516-a6a5-c69fd2ce854c
Content-Type: application/vnd.dwolla.v1.hal+json
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY
{
    "removed": true
}

...

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

request_body = {
  :removed => true
}

app_token.post "#{beneficial_owner_url}", request_body
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
beneficial_owner_url = 'https://api-sandbox.dwolla.com/beneficial-owners/692486f8-29f6-4516-a6a5-c69fd2ce854c'
request_body = {
  "removed": True
}

beneficial_owner = app_token.post(beneficial_owner_url, request_body)
var beneficialOwnerUrl = 'https://api-sandbox.dwolla.com/beneficial-owners/692486f8-29f6-4516-a6a5-c69fd2ce854c';
var requestBody = {
  removed: true
};

appToken.post(beneficialOwnerUrl, requestBody);

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

GET https://api-sandbox.dwolla.com/customers/56502f7a-fa59-4a2f-8579-0f8bc9d7b9cc
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY
...


No example for this language yet
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
customer_url = 'https://api-sandbox.dwolla.com/customers/692486f8-29f6-4516-a6a5-c69fd2ce854c'

beneficial_ownership = app_token.get "#{customer_url}/beneficial-ownership"
beneficial_ownership.status # => "failed"
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
customer_url = 'https://api-sandbox.dwolla.com/customers/692486f8-29f6-4516-a6a5-c69fd2ce854c'

beneficial_ownership = app_token.get('%s/beneficial-ownership' % customer_url)
beneficial_ownership.body['status'] # => 'failed'
var customerUrl = 'https://api-sandbox.dwolla.com/customers/692486f8-29f6-4516-a6a5-c69fd2ce854c';

appToken
  .get(`${customer_url}/beneficial-ownership`)
  .then(res => res.body.status); // => "failed"

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.

  1. If owners are not certified, a business verified Customer cannot transact or initiate transfers until the beneficial owners and controllers have been verified

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


Next steps


Financial institutions play an important role in the Dwolla network.

Dwolla, Inc. is an agent of Veridian Credit Union and Compass Bank and all funds associated with your account in the Dwolla network are held in pooled accounts at Veridian Credit Union and Compass Bank. These funds are not eligible for individual insurance, including FDIC insurance and 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 and Compass Bank.