Personal Verified Customer - Dwolla Developer Portal

Overview

This guide will walk through the identity verification process for personal verified Customers within the Dwolla API. A personal verified Customer represents an individual that intends to send or receive funds on your platform. In any transaction, at least one party—either the sender or the receiver—must complete the identity verification process as outlined in this guide.

Create a personal verified Customer

To create a personal verified Customer, use the create a Customer endpoint. A personal verified Customer is determined by setting the value of the type request parameter to personal and including additional fields required for identifying the individual.

Events

As a developer, you can expect these events to be triggered when a personal verified Customer is successfully created and systematically verified:

customer_created
customer_verified

Request parameters - personal verified Customer

firstName

Type: string
Required: Yes
An individual Customer’s first name. Must be ≤ 50 characters and contain no special characters <[<>="`!?%~${}\]>.

lastName

Type: string
Required: Yes
An individual Customer’s last name. Must be ≤ 50 characters and contain no special characters <[<>="`!?%~${}\]>.

email

Type: string
Required: Yes
Customer’s email address. Must be a valid email format (e.g., example@domain.com).

ipAddress

Type: string
Customer’s IP address.

type

Type: string
Required: Yes
The Verified Customer type. Set to personal if creating a verified personal Customer.

address1

Type: string
Required: Yes
First line of the street address of the Customer’s permanent residence. Must be ≤ 50 characters, contain no special characters <[<>="`!?%~${}\]>, and cannot be a PO Box.

address2

Type: string
Second line of the street address of the Customer’s permanent residence. Must be ≤ 50 characters, contain no special characters <[<>="`!?%~${}\]>, and cannot be a PO Box.

city

Type: string
Required: Yes
City of Customer’s permanent residence. Must be ≤ 50 characters and cannot contain numbers or special characters <[<>="`!?%~${}\]>.

state

Type: string
Required: Yes
Two-letter abbreviation of the state in which the Customer resides, e.g., CA. Must be a valid U.S. state.

postalCode

Type: string
Required: Yes
Postal code of Customer’s permanent residence. Must be a US 5-digit ZIP code (e.g., 50314) or ZIP+4 (e.g., 50314-1234).

dateOfBirth

Type: string
Required: Yes
Customer’s date of birth in YYYY-MM-DD format. Must be between 18 to 125 years old at the time of submission.

ssn

Type: string
Required: Yes
Last four or full 9 digits of the Customer’s Social Security Number. Must contain only numbers (e.g., 1234 or 123456789).

phone

Type: string
Customer’s 10-digit phone number. Must contain only numbers, no hyphens, spaces, or separators (e.g., 3334447777).

correlationId

Type: string
A unique string value attached to a customer which can be used for traceability between Dwolla and your application. Must be ≤ 255 characters and contain no spaces. Acceptable characters: a-z, 0-9, -, ., and _. Note: Do not use sensitive Personal Identifying Information (PII). Uniqueness is enforced across Customers.

Once you submit this request, Dwolla will perform some initial validation to check for formatting issues such as an invalid date of birth, invalid email format, etc. If successful, the response will be an HTTP 201/Created with the URL of the new Customer resource contained in the Location header.

Request and response

POST https://api-sandbox.dwolla.com/customers
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@email.net",
  "ipAddress": "10.10.10.10",
  "type": "personal",
  "address1": "99-99 33rd St",
  "city": "Some City",
  "state": "NY",
  "postalCode": "11101",
  "dateOfBirth": "1970-01-01",
  "ssn": "1234"
}

HTTP/1.1 201 Created
Location: https://api.dwolla.com/customers/FC451A7A-AE30-4404-AB95-E3553FCD733F

Check the status of the personal verified Customer

The successful creation of a Customer doesn’t necessarily mean the Customer is verified and eligible to send or receive funds. When a Customer has been successfully verified by Dwolla, their status will be set to verified. Let’s check to see if the Customer was successfully verified or not. We are going to use the location of the Customer resource that was just created, which is in new_customer.

GET https://api-sandbox.dwolla.com/customers/FC451A7A-AE30-4404-AB95-E3553FCD733F
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY

{
  "_links": {
    "self": {
      "href": "https://api-sandbox.dwolla.com/customers/FC451A7A-AE30-4404-AB95-E3553FCD733F",
      "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/FC451A7A-AE30-4404-AB95-E3553FCD733F",
      "type": "application/vnd.dwolla.v1.hal+json; profile=\"https://github.com/dwolla/hal-forms\"",
      "resource-type": "customer"
    }
  },
  "id": "FC451A7A-AE30-4404-AB95-E3553FCD733F",
  "firstName": "John",
  "lastName": "Doe",
  "email": "jdoe@nomail.net",
  "type": "personal",
  "status": "verified",
  "created": "2016-11-28T19:51:48.050Z",
  "address1": "99-99 33rd St",
  "address2": "Apt 8",
  "city": "Some City",
  "state": "NY",
  "postalCode": "11101",
  "phone": "5554321234"
}

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

Customer status	Event	Description
verified	customer_verified	The identifying information submitted was sufficient in verifying the Customer account.
retry	customer_reverification_needed	The initial identity verification attempt failed because the information provided did not satisfy Dwolla’s verification check. You can make one additional attempt by changing some or all the attributes of the existing Customer with a POST request. All fields are required on the retry attempt. If the additional attempt fails, the resulting status will be either `document` or `suspended`.
kba	customer_kba_verification_needed	The `retry` identity verification attempt failed due to insufficient scores on the submitted data. The end user will have a single kba attempt to answer a set of “out of wallet” questions about themselves for identity verification. Note: KBA is a premium feature. Please contact Sales or your account manager for more information on enabling KBA functionality.
document	customer_verification_document_needed	Dwolla requires additional documentation to identify the Customer in the document status. Once a document is uploaded it will be reviewed for verification.
suspended	customer_suspended	The Customer is suspended and may neither send nor receive funds. Contact Account Management for more information.

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.

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.

You need to gather new information if the Customer is placed into the retry status; simply passing the same information will result in the same insufficient scores. All fields that were required in the initial Customer creation attempt will be required in the retry attempt, along with the full 9-digit SSN.

Example Request

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@email.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"
}

Handling status - `kba`

This section outlines a premium feature for the Dwolla API. Please contact Sales or your account manager for more information on enabling KBA functionality.

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 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 camera captured image 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.