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? #

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 #

Address JSON object #

Passport JSON object #

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

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

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

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

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

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

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

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.