Dwolla Developers Logo
Back
Guides
  • Getting Started
    Testing in the Sandbox
    Generate an OAuth Access Token
    Send Money to Users
    Receive Money from Users
    Transfer Money Between Users
    Transfer Money Me-to-Me
  • Customers
    Create a Business Verified Customer
    OverviewStep 1: Create a business Verified CustomerStep 2: Handle verification statusesStep 3: Add beneficial ownersStep 4: Certify beneficial ownershipFrequently asked questions
    Create a Personal Verified Customer
  • Funding Sources
    Add a Bank Using Dwolla.js
    Add a Bank Using Dwolla.js + IAV
    Verify Bank with Micro-deposits
    Add Bank via Dwolla + Plaid Integration
  • Webhooks
    Create a Webhook Subscription
API DocsOpen in new tabChangelog
Get API Keys
API DocsOpen in new tabChangelog
JavaScript
Get API Keys

Step 3: 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 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.

Info
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 are no beneficial owners

How do I know what business structure is required to add Beneficial Owners?

If my Customer's business structure is......are they required to add beneficial owners?Sole proprietorshipsNo (exempt)Unincorporated associationNo (exempt)TrustNo (exempt)CorporationYes (if owns 25% or more)Publicly traded corporationsNo (exempt)Non-profitsNo (exempt)LLCsYes (if owns 25% or more)Partnerships, LP's, LLP'sYes (if owns 25% or more)

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

ParameterRequiredTypeDescriptionfirstNameyesstringThe 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 addresspassportconditionalobjectAn optional passport JSON object. Required for foreign individuals. Includes passport identification number and country.

Address JSON object

ParameterRequiredTypeDescriptionaddress1yesstringFirst 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.postalCodeconditionalstringPostal code of beneficial owner’s permanent residence. Should be a five digit postal code, e.g. 50314. Optional if beneficial owner is a non-US person.

Passport JSON object

ParameterRequiredTypeDescriptionnumberconditionalstringRequired 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

JavaScript
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 StatusEvent Topic NameTransaction Restricted?DescriptionVerifiedcustomer_beneficial_owner_verifiedNoBeneficial owner has been identity verified.Documentcustomer_beneficial_owner_document_neededYes - Cannot send fundsBeneficial owner must upload a document in order to be verified.Incompletecustomer_beneficial_owner_reverification_neededYes - Cannot send fundsThe 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.

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

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

Info
You need to gather new information if the beneficial owner is placed into theincomplete 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 incompleteattempt.

Request and Response - update beneficial owner

JavaScript
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 anywhere from a few seconds up to 1-2 business days if manual verification is required to approve or reject.

Determining verification documents needed

US persons

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

  • Non-expired State Issued Driver’s License/Identification Card
  • Non-expired US Passport
  • Federal Employment Authorization Card
  • US Visa

Non-US persons

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

  • Non-expired Foreign Passport Note: Foreign Passports are only accepted when the individual does not have an ITIN or SSN and the user must alternatively enter the Passport number.

Uploading a document

To upload a color 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, or .png. 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

JavaScript
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

JavaScript
var beneficialOwnerUrl =
  "https://api-sandbox.dwolla.com/beneficial-owners/692486f8-29f6-4516-a6a5-c69fd2ce854c";

appToken.delete(beneficialOwnerUrl);

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 the next step.

Test in the Sandbox for free today.

Use sandbox environment to test API requests.

Get API Keys
2020 All Rights Reserved

Dwolla

  • About
  • Blog
  • Pricing
  • Contact Sales
  • Terms of Service
  • Privacy Policy
Financial institutions play an important role in our 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.