Handling verification statuses #

After successfully creating a personal identity-verified Customer, they will immediately be given a status. There are various reasons a Customer status can be something other than verified; you will want to account for this after the Customer is created.

A Customer’s verification status is determined by an identity verification score based on the data submitted; this score is returned from Dwolla’s identity vendor. Therefore, it is important that the user enters accurate and complete identifying data, and that you exercise best practices in input field validation to ensure the best possible success rate. As an example, the retry status can occur when an individual mis-keys or uses incorrect identifying information upon Customer creation (i.e. submitting a date of birth that differs from the user’s actual date of birth).

It is recommended to have an active webhook subscription to listen for Customer verification related events. Reference the table below for Customer verification statuses and the related events.

Verification statuses #

Testing verification statuses in Sandbox #

Dwolla’s Sandbox environment allows you to submit verified, retry, kba, document, or suspended as the value of the firstName parameter to create a new verified Customer with their respective status. To simulate transitioning a verified Customer with a retry status to verified, you’ll need to call the Update a Customer endpoint and submit full identifying information with an updated firstName value and full SSN. To simulate transitioning a verified Customer with a document status to verified in the Sandbox, you’ll need to upload a test document as outlined in the Testing in the Sandbox resource article.

Handling status: retry #

A retry status occurs when a Customer’s identity scores are too low during the initial verification attempt. Dwolla will require the full 9-digits of the individual's SSN on the retry attempt in order to give our identity vendor more information in an attempt to receive a sufficient score to approve the Customer account. The Customer will have one more opportunity to correct any mistakes.

POST https://api.dwolla.com/customers/132681fa-1b4d-4181-8ff2-619ca46235b1
Content-Type: application/vnd.dwolla.v1.hal+json
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY

{
  "firstName": "John",
  "lastName": "Doe",
  "email": "johndoe@nomail.net",
  "ipAddress": "10.10.10.10",
  "type": "personal",
  "address1": "221 Corrected Address St.",
  "address2": "Fl 8",
  "city": "Ridgewood",
  "state": "NY",
  "postalCode": "11385",
  "dateOfBirth": "1990-07-11",
  "ssn ": "202-99-1516"
}

Check the Customer’s status again. The Customer will either be in the verified, kba, document, or suspended state of verification.

Handling status: kba #

A KBA status occurs when a Customer’s identity scores are too low after the retry verification attempt. Knowledge based authentication (KBA), is used to identify end users by asking them to answer specific security questions about themselves pulled from a set of known data. These questions are also known as “out of wallet” questions which are dynamically generated on the spot. The Customer must answer at least three out of four (total) questions correctly in order to pass verification, which translates to a score of 75%. If the end user fails to pass KBA verification, they will be placed in a document status. The KBA flow is a three step process which includes: initiating the KBA session, retrieving the question set and answering the question set. Learn more on testing KBA in the sandbox environment.

Initiating the KBA session #

The first step in the KBA flow is to make a request to the Dwolla API to generate a unique KBA ID which is used to represent the KBA session.

Example request and response

POST https://api.dwolla.com/customers/33aa88b1-97df-424a-9043-d5f85809858b/kba
Authorization: Bearer cRahPzURfaIrTKL18tmslWPqKdzkLeYJm0oB1hGJ1vMPArft1v
Content-Type: application/json
Accept: application/vnd.dwolla.v1.hal+json

...

HTTP/1.1 201 Created\
Location: https://api.dwolla.com/kba/33aa88b1-97df-424a-9043-d5f85809858b

Retrieve KBA Question set #

Once the KBA ID is created, your application will have a single attempt to retrieve and answer the question set returned from the Dwolla API. Upon a successful request to retrieve the question set, your end user will have two minutes to complete the submission of their selected answers.

Example request and response

GET https://api.dwolla.com/kba/33aa88b1-97df-424a-9043-d5f85809858b
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer cRahPzURfaIrTewKL18tmslWPqKdzkLeYJm0oB1hGJ1vMPArft1v

...

{
    "_links": {
        "answer": {
            "href": "https://api-sandbox.dwolla.com/kba/33aa88b1-97df-424a-9043-d5f85809858b",
            "type": "application/vnd.dwolla.v1.hal+json",
            "resource-type": "kba"
        }
    },
    "id": "33aa88b1-97df-424a-9043-d5f85809858b",
    "questions": [
        {
            "id": "2355953375",
            "text": "In what county do you currently live?",
            "answers": [
                {
                    "id": "2687969295",
                    "text": "Pulaski"
                },
                {
                    "id": "2687969305",
                    "text": "St. Joseph"
                },
                {
                    "id": "2687969315",
                    "text": "Daviess"
                },
                {
                    "id": "2687969325",
                    "text": "Jackson"
                },
                {
                    "id": "2687969335",
                    "text": "None of the above"
                }
            ]
        },
        {
            "id": "2355953385",
            "text": "Which team nickname is associated with a college you attended?",
            "answers": [
                {
                    "id": "2687969345",
                    "text": "Colts"
                },
                {
                    "id": "2687969355",
                    "text": "Eagles"
                },
                {
                    "id": "2687969365",
                    "text": "Gator"
                },
                {
                    "id": "2687969375",
                    "text": "Sentinels"
                },
                {
                    "id": "2687969385",
                    "text": "None of the above"
                }
            ]
        },
        {
            "id": "2355953395",
            "text": "What kind of IA license plate has been on your 1996 Acura TL?",
            "answers": [
                {
                    "id": "2687969395",
                    "text": "Antique"
                },
                {
                    "id": "2687969405",
                    "text": "Disabled Veteran"
                },
                {
                    "id": "2687969415",
                    "text": "Educational Affiliation"
                },
                {
                    "id": "2687969425",
                    "text": "Military Honor"
                },
                {
                    "id": "2687969435",
                    "text": "I have never been associated with this vehicle"
                }
            ]
        }
    ]
}

Answer KBA Questions #

Questions and answers will have their own unique identifiers. Questions and answers are submitted via an answers array that contains a list of four JSON objects that include key-value pairs for specifying a questionId and answerId.

Example request and response

POST https://api.dwolla.com/kba/33aa88b1-97df-424a-9043-d5f85809858b
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer cRahPzURfaIrTewKL18tmslWPqKdzkLeYJm0oB1hGJ1vMPArft1v

...

{
    "answers": [
        {
            "questionId": "2355953375",
            "answerId": "2687969335"
        },
        {
            "questionId": "2355953385",
            "answerId": "2687969385"
        },
        {
            "questionId": "2355953395",
            "answerId": "2687969435"
        },
        {
            "questionId": "2355953405",
            "answerId": "2687969485"
        }
    ]
}

KBA Success

If your Customer is able to correctly answer at least three of the four (total) KBA questions, your Customer will be moved into verified status. You will receive the customer_kba_verification_passed and customer_verified webhooks to indicate that your Customer has passed the KBA attempt and has been successfully verified.

KBA Failure

A Customer that is unable to answer at least three questions correctly will be moved into document status. You will receive the customer_kba_verification_failed and customer_verification_document_needed webhooks to indicate that your Customer has failed the KBA attempt and must upload a photo Id in order to become verified.

Handling status: document #

If the Customer has a status of document, the Customer will need to upload additional pieces of information in order to verify the account. 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.

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

Document types #

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

When a Customer is placed in the document verification status, Dwolla will return a link in the API response after retrieving a Customer which will be used by an application to determine if documentation is needed.

Example response

{
  "_links": {
    "document-form": {
      "href": "https://api-sandbox.dwolla.com/customers/64dd2beb-fe56-4cdc-80dd-82a3d7f5b921/documents",
      "type": "application/vnd.dwolla.v1.hal+json; profile=\"https://github.com/dwolla/hal-forms\"",
      "resource-type": "document"
    },
    "self": {
      "href": "https://api-sandbox.dwolla.com/customers/64dd2beb-fe56-4cdc-80dd-82a3d7f5b921",
      "type": "application/vnd.dwolla.v1.hal+json",
      "resource-type": "customer"
    },
    "funding-sources": {
      "href": "https://api-sandbox.dwolla.com/customers/64dd2beb-fe56-4cdc-80dd-82a3d7f5b921/funding-sources",
      "type": "application/vnd.dwolla.v1.hal+json",
      "resource-type": "funding-source"
    },
    "transfers": {
      "href": "https://api-sandbox.dwolla.com/customers/64dd2beb-fe56-4cdc-80dd-82a3d7f5b921/transfers",
      "type": "application/vnd.dwolla.v1.hal+json",
      "resource-type": "transfer"
    },
    "verify-with-document": {
      "href": "https://api-sandbox.dwolla.com/customers/64dd2beb-fe56-4cdc-80dd-82a3d7f5b921/documents",
      "type": "application/vnd.dwolla.v1.hal+json",
      "resource-type": "document"
    }
  },
  "id": "64dd2beb-fe56-4cdc-80dd-82a3d7f5b921",
  "firstName": "document",
  "lastName": "doctest",
  "email": "docTest@email.com",
  "type": "personal",
  "status": "document",
  "created": "2017-08-31T14:28:11.047Z",
  "address1": "99-99 33rd St",
  "address2": "Apt 8",
  "city": "Some City",
  "state": "NY",
  "postalCode": "11101"
}

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 https://api.dwolla.com/customers/{id}/documents. The file must be either a .jpg, .jpeg, or .png. Files must be no larger than 10MB in size.

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"
\ -F "documentType=passport"
\ -F "file=@foo.png"
\ 'https://api-sandbox.dwolla.com/customers/132681fa-1b4d-4181-8ff2-619ca46235b1/documents'

HTTP/1.1 201 Created
Location: https://api-sandbox.dwolla.com/documents/11fe0bab-39bd-42ee-bb39-275afcc050d0

If the document was successfully uploaded, the response will be a HTTP 201 Created with the URL of the new document resource contained in the Location header.

HTTP/1.1 201 Created
Location: https://api-sandbox.dwolla.com/documents/11fe0bab-39bd-42ee-bb39-275afcc050d0

You’ll also get a webhook with a customer_verification_document_uploaded event to let you know the document was successfully uploaded.

Document review process #

Once created, the document will be reviewed by Dwolla. When the document has been reviewed, which may take anywhere from a few seconds up to 1-2 business days if manual verification is required to approve or reject, we’ll create either a customer_verification_document_approved or customer_verification_document_failed event.

If the document was sufficient, the Customer may be verified in this process. If not, we may need additional documentation. Note: Reference the determining verification documents needed section for more information on determining if additional documents are needed after an approved or failed event is triggered.

If the document was found to be fraudulent or doesn’t match the identity of the Customer, the Customer will be suspended.

Document failure #

A document can fail if, for example, the Customer uploaded the wrong type of document or the .jpg or .png file supplied was not readable (i.e. blurry, not well lit, not in color, or cuts off a portion of the identifying image). If you receive a customer_verification_document_failed webhook, you’ll need to upload another document. To retrieve the failure reason for the document upload, you’ll retrieve the document by its ID. Contained in the response will be a failureReason field which corresponds to one or more of the following values. In case of a failure due to multiple reasons, an additional allFailureReasons array of reasons and descriptions is also returned :

Request and response

GET https://api-sandbox.dwolla.com/documents/11fe0bab-39bd-42ee-bb39-275afcc050d0
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer tJlyMNW6e3QVbzHjeJ9JvAPsRglFjwnba4NdfCzsYJm7XbckcR

...

{
  "_links": {
    "self": {
      "href": "https://api-sandbox.dwolla.com/documents/11fe0bab-39bd-42ee-bb39-275afcc050d0"
    }
  },
  "id": "11fe0bab-39bd-42ee-bb39-275afcc050d0",
  "status": "reviewed",
  "type": "license",
  "created": "2016-01-29T21:22:22.000Z",
  "failureReason": "ScanNotReadable",
  "allFailureReasons": [
      {
          "reason": "ScanDobMismatch",
          "description": "Date of Birth mismatch"
      },
      {
          "reason": "ScanIdExpired",
          "description": "ID is expired"
      }
  ]
}

Handling status: suspended #

If the Customer is suspended, there’s no further action you can take to correct this using the API. You’ll need to contact support@dwolla.com or your account manager for assistance.