Verified Status and Documentation for Beneficial Owners

API Support
1

When a Beneficial Owner is in the ‘document’ status - the status is returned as verified when retrieving that particular Customer. I remember reading in the documentation that if a Beneficial Owner is in document status, that funds are not able to be sent. Based on the response below, how am I supposed to know that there is an issue with the Beneficial Owner?

{
  "_links": {
    "verify-beneficial-owners": {
      "href": "https://api-sandbox.dwolla.com/customers/138bde4f-787a-400c-b0e5-6fd5d10faba7/beneficial-owners",
      "type": "application/vnd.dwolla.v1.hal+json",
      "resource-type": "beneficial-owner"
    },
    "beneficial-owners": {
      "href": "https://api-sandbox.dwolla.com/customers/138bde4f-787a-400c-b0e5-6fd5d10faba7/beneficial-owners",
      "type": "application/vnd.dwolla.v1.hal+json",
      "resource-type": "beneficial-owner"
    },
    "deactivate": {
      "href": "https://api-sandbox.dwolla.com/customers/138bde4f-787a-400c-b0e5-6fd5d10faba7",
      "type": "application/vnd.dwolla.v1.hal+json",
      "resource-type": "customer"
    },
    "self": {
      "href": "https://api-sandbox.dwolla.com/customers/138bde4f-787a-400c-b0e5-6fd5d10faba7",
      "type": "application/vnd.dwolla.v1.hal+json",
      "resource-type": "customer"
    },
    "receive": {
      "href": "https://api-sandbox.dwolla.com/transfers",
      "type": "application/vnd.dwolla.v1.hal+json",
      "resource-type": "transfer"
    },
    "edit-form": {
      "href": "https://api-sandbox.dwolla.com/customers/138bde4f-787a-400c-b0e5-6fd5d10faba7",
      "type": "application/vnd.dwolla.v1.hal+json; profile=\"https://github.com/dwolla/hal-forms\"",
      "resource-type": "customer"
    },
    "edit": {
      "href": "https://api-sandbox.dwolla.com/customers/138bde4f-787a-400c-b0e5-6fd5d10faba7",
      "type": "application/vnd.dwolla.v1.hal+json",
      "resource-type": "customer"
    },
    "certify-beneficial-ownership": {
      "href": "https://api-sandbox.dwolla.com/customers/138bde4f-787a-400c-b0e5-6fd5d10faba7/beneficial-ownership",
      "type": "application/vnd.dwolla.v1.hal+json",
      "resource-type": "beneficial-ownership"
    },
    "funding-sources": {
      "href": "https://api-sandbox.dwolla.com/customers/138bde4f-787a-400c-b0e5-6fd5d10faba7/funding-sources",
      "type": "application/vnd.dwolla.v1.hal+json",
      "resource-type": "funding-source"
    },
    "transfers": {
      "href": "https://api-sandbox.dwolla.com/customers/138bde4f-787a-400c-b0e5-6fd5d10faba7/transfers",
      "type": "application/vnd.dwolla.v1.hal+json",
      "resource-type": "transfer"
    }
  },
  "id": "138bde4f-787a-400c-b0e5-6fd5d10faba7",
  "firstName": "AdminFirst",
  "lastName": "AdminLast",
  "email": "testuser@testing.com",
  "type": "business",
  "status": "verified",
  "created": "2020-05-29T12:38:52.917Z",
  "address1": "200 Business Drive",
  "city": "Business City",
  "state": "AR",
  "postalCode": "09230",
  "businessName": "Rio Plaza LLC",
  "controller": {
    "firstName": "Joseph",
    "lastName": "Controller",
    "title": "CEO",
    "address": {
      "address1": "500 Control Drive",
      "address2": "",
      "city": "ControlTown",
      "stateProvinceRegion": "AL",
      "country": "US",
      "postalCode": "93023"
    }
  },
  "businessType": "corporation",
  "businessClassification": "9ED35A39-7D6F-11E3-96AD-5404A6144203"
}

Also - in one section of the docs indicate there are 3 statuses for a Beneficial Owner (incomplete, verified, or document), and then that there are only 2 possible statuses (verified or document). Which is correct?

https://developers.dwolla.com/resources/business-verified-customer/adding-beneficial-owners.html

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.

And immediately after (below the code samples)…

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.

2

Hi @jmtichell – The verification of a the Business account and that of the Beneficial-owners are separate. The status on the Customer can show verified while the the BO may have a different status (incomplete/document/verified).

In order to check the status of the BO, you’d have to follow the "beneficial-owners" link in the response above. You can also determine if the BO hasn’t been fully verified if the Customer response has a "verify-beneficial-owners" link in the “_links” object as in the response above. Once the BO has been verified and certified, the link is removed from the Customer resource.

The three statuses that a BO can be in are incomplete, document and verified. Thanks for pointing that out in the docs! We essentially meant that the only status other than "verified" can be "document" after the second attempt has been made to update the "incomplete" BO. We can update that section of the docs to clarify that! Thanks!

3

As always, you’ve been very helpful @shreya. I appreciate the quick response and hope you have a great weeked. :slight_smile:

One follow-up question…is there any indicator that Dwolla returns in the get customer endpoint (or any other endpoint) if a document is under review? What does the response for a Beneficial Owner or Customer look like when documents are pending? This is not something I can test in the sandbox as far as I can tell.

4

Hi @jmtichell, There is a status on the document resource you could check to see if the document has been reviewed or pending review. Here’s what the response looks like to the GET /documents/{id}

{
  "_links": {
    "self": {
      "href": "https://api.dwolla.com/documents/56502f7a-fa59-4a2f-8579-0f8bc9d7b9cc"
    }
  },
  "id": "56502f7a-fa59-4a2f-8579-0f8bc9d7b9cc",
  "status": "reviewed",
  "type": "passport",
  "created": "2015-09-29T21:42:16.000Z",
  "failureReason": "ScanDobMismatch",
  "allFailureReasons": [
      {
          "reason": "ScanDobMismatch",
          "description": "Date of Birth mismatch"
      },
      {
          "reason": "ScanIdExpired",
          "description": "ID is expired"
      }
  ]
}

When uploaded docs are pending review, the status of the Customer or Beneficial Owner should simply display document. Therefore, you’ll want to make sure your application is setup to receive document related webhooks to know when they’ve been approved or rejected. Those event topic names should be either customer_verification_document_failed or customer_verification_document_approved.