Ask AI or search...
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.

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 #

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 between 18 to 125 years of age.
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.
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 #

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

Raw
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

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 beneficial owner'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?Description
Verifiedcustomer_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

Raw
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"
}

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.

Request and Response - update beneficial owner

Raw
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"
}

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 after being placed in incomplete status and submitting a second verification attempt, 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 camera captured image 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.

You can provide the following best practices to the Customer in order to reduce the chances of a document being rejected:

  • All 4 Edges of the document should be visible
  • A dark/high contrast background should be used
  • At least 90% of the image should be the document
  • Should be at least 300dpi
  • Capture image from directly above the document
  • Make sure that the image is properly aligned, not rotated, tilted or skewed
  • No flash to reduce glare
  • No black and white documents
  • No expired IDs

Determining verification documents needed #

US persons

A colored camera captured image 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 colored camera captured image 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

Raw
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

Update Beneficial Owner Information #

Information can only be edited or updated when the Beneficial Owner has a status of incomplete.

If an individual beneficial owner with a status of verified needs to update their information, that beneficial owner will first need to be removed and re-added.

Request and Response

Raw
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

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
2024 All Rights Reserved
Financial institutions play an important role in our network.

All funds transfers made using the Dwolla Platform are performed by a financial institution partner, and any funds held in a Dwolla Balance are held by a financial institution partner. Learn more about our financial institution partners.