Language

Step 1: Creating Business Verified Customers

The basics

Creating a business verified Customer will require you to provide information about the business entity as well as a Controller, if required.

How do I know what businessType to sign up as?

My Customer’s business structure……will sign up in Dwolla as businessType =Is a Controller required?
Sole proprietorshipssoleProprietorshipNo
Unincorporated associationsoleProprietorshipNo
TrustsoleProprietorshipNo
CorporationcorporationYes
Publicly traded corporationscorporationYes
Non-profitscorporation or llcYes
LLCsllcYes
Partnerships, LP’s, LLP’spartnershipYes

There are two types of business verified Customers that you can create, based on if they are required to add information on the Controller or not.

Create a Business Verified Customer

Request Parameters - Create a business verified Customer with no Controller

Follow these steps to create a business verified Customer where "businessType": "soleProprietorship"

Events

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

  1. customer_created
  2. customer_verified

What parties are identity verified by Dwolla?

Business TypeBusiness EntityControllerBusiness Owner
Sole ProprietorshipIdentity verifiedN/AIdentity verified

In order to create a business verified Customer with businessType of soleProprietorship, Dwolla only requires information to verify the identity of the the business and the Account Admin.

ParameterRequiredTypeDescription
firstNameyesstringThe legal first name of the Business Owner.
lastNameyesstringThe legal last name of the Business Owner.
emailyesstringemail address of the Business Owner.
ipAddressnostringipAddress of registering user is recommended.
typeyesstringValue of: business
dateOfBirthyesstringThe date of birth of the Business Owner. Formatted in YYYY-MM-DD format. Must be 18 years or older.
ssnyesstringLast four-digits of the Business Owner social security number.
address1yesstringStreet number, street name of business’ physical address.
address2nostringApartment, floor, suite, bldg. # of business’ physical address
cityyesstringCity of business’ physical address.
stateyesstringTwo-letter US state or territory abbreviation code of business’ physical address. For two-letter abbreviation reference, check out the US Postal Service guide.
postalCodeyesstringBusiness’ US five-digit ZIP or ZIP + 4 code.
businessNameyesstringRegistered business name.
doingBusinessAsnostringPreferred business name – also known as fictitious name, or assumed name.
businessTypeyesstringBusiness structure. Value of soleProprietorship.
businessClassificationyesstringThe industry classification Id that corresponds to Customer’s business. Reference our Dev Docs to learn how to generate this Id.
einnostringEmployer Identification Number. Optional for soleProprietorship business Customers
websitenostringBusiness’ website
phonenostringBusiness’s 10 digit phone number. No hyphens or other separators, e.g. 3334447777.

Sole Propreietorship - 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 0Sn0W6kzNic+oWhDbQcVSKLRUpGjIdl/YyrHqrDDoRnQwE7Q

{
    "firstName": "Business",
    "lastName": "Owner",
    "email": "solePropBusiness@email.com",
    "ipAddress": "143.156.7.8",
    "type": "business",
    "dateOfBirth": "1980-01-31",
    "ssn": "6789",
    "address1": "99-99 33rd St",
    "city": "Some City",
    "state": "NY",
    "postalCode": "11101",
    "businessClassification": "9ed3f670-7d6f-11e3-b1ce-5404a6144203",
    "businessType": "soleProprietorship",
    "businessName":"Jane Corp",
    "ein":"00-0000000"
}

HTTP/1.1 201 Created
Location: https://api-sandbox.dwolla.com/customers/62c3aa1b-3a1b-46d0-ae90-17304d60c3d5
<?php
$customersApi = new DwollaSwagger\CustomersApi($apiClient);
$new_customer = $customersApi->create([
    'firstName' => 'Business',
    'lastName' => 'Owner',
    'email' => 'solePropBusiness@email.com',
    'ipAddress' => '143.156.7.8',
    'type' => 'business',
    'dateOfBirth' => '1980-01-31',
    'ssn' => '6789',
    'address1' => '99-99 33rd St',
    'city' => 'Some City',
    'state' => 'NY',
    'postalCode' => '11101',
    'businessClassification' => '9ed3f670-7d6f-11e3-b1ce-5404a6144203',
    'businessType' => 'soleProprietorship',
    'businessName' => 'Jane Corp',
    'ein' => '00-0000000']);

?>
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby (Recommended)
request_body = {
    :firstName => 'Business',
    :lastName => 'Owner',
    :email => 'solePropBusiness@email.com',
    :ipAddress => '143.156.7.8',
    :type => 'business',
    :dateOfBirth => '1980-01-31',
    :ssn => '6789',
    :address1 => '99-99 33rd St',
    :city => 'Some City',
    :state => 'NY',
    :postalCode => '11101',
    :businessClassification => '9ed3f670-7d6f-11e3-b1ce-5404a6144203',
    :businessType => 'soleProprietorship',
    :businessName => 'Jane Corp',
    :ein => '00-0000000'
}

customer = app_token.post "customers", request_body
customer.response_headers[:location] # => "https://api-sandbox.dwolla.com/customers/62c3aa1b-3a1b-46d0-ae90-17304d60c3d5"
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python (Recommended)
request_body = {
  'firstName': 'Business',
  'lastName': 'Owner',
  'email': 'solePropBusiness@email.com',
  'ipAddress': '143.156.7.8',
  'type': 'business',
  'dateOfBirth': '1980-01-31',
  'ssn': '6789',
  'address1': '99-99 33rd St',
  'city': 'Some City',
  'state': 'NY',
  'postalCode': '11101',
  'businessClassification': '9ed3f670-7d6f-11e3-b1ce-5404a6144203',
  'businessType': 'soleProprietorship',
  'businessName': 'Jane Corp',
  'ein': '00-0000000'
}

customer = app_token.post('customers', request_body)
customer.headers['location'] # => 'https://api-sandbox.dwolla.com/customers/62c3aa1b-3a1b-46d0-ae90-17304d60c3d5'
var requestBody = {
    firstName: 'Business',
    lastName: 'Owner',
    email: 'solePropBusiness@email.com',
    ipAddress: '143.156.7.8',
    type: 'business',
    dateOfBirth: '1980-01-31',
    ssn: '6789',
    address1: '99-99 33rd St',
    city: 'Some City',
    state: 'NY',
    postalCode: '11101',
    businessClassification: '9ed3f670-7d6f-11e3-b1ce-5404a6144203',
    businessType: 'soleProprietorship',
    businessName: 'Jane Corp',
    ein: '00-0000000',
};

appToken
  .post('customers', requestBody)
  .then(res => res.headers.get('location')); // => 'https://api-sandbox.dwolla.com/customers/62c3aa1b-3a1b-46d0-ae90-17304d60c3d5'

Create a Business Verified Customer

Request Parameters - Create a business verified Customer and controller

Events

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

  1. customer_created
  2. customer_verified

What parties are identity verified by Dwolla?

Business TypeBusiness EntityControllerAccount Admin
CorporationIdentity verifiedIdentity verifiedNot identity verified
PartnershipIdentity verifiedIdentity verifiedNot identity verified
LLCIdentity verifiedIdentity verifiedNot identity verified

For all other businessType‘s other than soleProprietorship, your Customer will need to provide more information for verification. In order to create a business verified Customer with a controller, Dwolla requires information on an account admin, the business, and the controller. Your business verified Customer account admin will act as the agent signing up on behalf of the business. When going through the Customer creation flow, your business verified Customer account admin will only need information on one controller to successfully complete the signup flow.

ParameterRequiredTypeDescription
firstNameyesstringThe legal first name of the Account Admin or individual signing up the business verified Customer.
lastNameyesstringThe legal last name of the Account Admin or individual signing up the business verified Customer.
emailyesstringEmail address of the Account Admin creating and managing the Customer account.
ipAddressnostringipAddress of registering user is recommended.
typeyesstringValue of: business
address1yesstringStreet number, street name of business’ physical address.
address2nostringApartment, floor, suite, bldg. # of business’ physical address
cityyesstringCity of business’ physical address.
stateyesstringTwo-letter US state or territory abbreviation code of business’ physical address. For two-letter abbreviation reference, check out the US Postal Service guide.
postalCodeyesstringBusiness’ US five-digit ZIP or ZIP + 4 code.
businessNameyesstringRegistered business name.
doingBusinessAsnostringPreferred business name – also known as fictitious name, or assumed name.
businessTypeyesstringBusiness structure. Possible values are corporation, llc, partnership.
businessClassificationyesstringThe industry classification Id that corresponds to Customer’s business. Reference our Dev Docs to learn how to generate this Id.
einyesstringEmployer Identification Number. Note: If the businessType is soleProprietorship, then ein and controller can be omitted from the request.
websitenostringBusiness’ website
phonenostringBusiness’s 10 digit phone number. No hyphens or other separators, e.g. 3334447777.
controllerconditionalobjectA controller JSON object. Controllers are not required if businessType is soleProprietorship

Controller JSON object

ParameterRequiredTypeDescription
firstNameyesstringThe legal first name of the controller.
lastNameyesstringThe legal last name of the controller.
titleyesstringJob title of the Customer’s Controller. e.g. Chief Financial Officer
dateOfBirthyesstringThe date of birth of the controller. Formatted in YYYY-MM-DD format. Must be 18 years or older.
ssnconditionalstringLast four-digits of Controller’s social security number. Required for Controllers who reside in the United States.
addressyesobjectA controller address JSON object. Full address of the controller’s physical address. See below
passportconditionalobjectAn optional controller’s passport JSON object. Required for non-US individuals. Includes passport identification number and country. See below

Controller address JSON object

ParameterRequiredTypeDescription
address1yesstringStreet number, street name of Controller’s physical address.
address2nostringApartment, floor, suite, bldg. # of Controller’s physical address.
address3nostringThird line of the street address of the Controller’s physical address.
cityyesstringCity of Controller’s physical address.
stateProvinceRegionyesstringTwo-letter US state or territory abbreviation code of controller’s physical address. For two-letter abbreviation reference, check out the US Postal Service guide.
postalCodenostringController’s’ US five-digit ZIP or ZIP + 4 code.
countryyesstringCountry of controller’s physical address. Two digit ISO code, e.g. US.

Controller passport JSON object

ParameterRequiredTypeDescription
numberconditionalstringRequired for a non-U.S. person who has no Social Security number.
countryconditionalstringCountry of issued passport. Two digit ISO code, e.g. US.

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 a HTTP 201/Created with the URL of the new Customer resource contained in the Location header.

Business with Controller - 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 0Sn0W6kzNic+oWhDbQcVSKLRUpGjIdl/YyrHqrDDoRnQwE7Q

{
    "firstName": "Account",
    "lastName": "Admin",
    "email": "accountAdmin@email.com",
    "ipAddress": "143.156.7.8",
    "type": "business",
    "address1": "99-99 33rd St",
    "city": "Some City",
    "state": "NY",
    "postalCode": "11101",
    "controller": {
        "firstName": "John",
        "lastName": "Controller",
        "title": "CEO",
        "ssn": "6789",
        "dateOfBirth": "1980-01-31",
        "address": {
            "address1": "1749 18th st",
            "address2": "apt 12",
            "city": "Des Moines",
            "stateProvinceRegion": "IA",
            "postalCode": "50266",
            "country": "US"
        }
    },
    "businessClassification": "9ed3f670-7d6f-11e3-b1ce-5404a6144203",
    "businessType": "llc",
    "businessName":"Jane Corp",
    "ein":"00-0000000"
}

HTTP/1.1 201 Created
Location: https://api-sandbox.dwolla.com/customers/62c3aa1b-3a1b-46d0-ae90-17304d60c3d5
<?php
$customersApi = new DwollaSwagger\CustomersApi($apiClient);
$new_customer = $customersApi->create([
  'firstName' => 'Account',
  'lastName' => 'Admin',
  'email' => 'accountAdmin@email.com',
  'type' => 'business',
  'address1' => '99-99 33rd St',
  'city' => 'Some City',
  'state' => 'NY',
  'postalCode' => '11101',
  'controller' =>
  [
      'firstName' => 'John',
      'lastName'=> 'Controller',
      'title' => 'CEO',
      'dateOfBirth' => '1990-01-31',
      'ssn' => '1234',
      'address' =>
      [
          'address1' => '18749 18th st',
          'address2' => 'apt 12',
          'city' => 'Des Moines',
          'stateProvinceRegion' => 'IA',
          'postalCode' => '50265',
          'country' => 'US'
      ],
  ],
  'phone' => '5554321234',
  'businessClassification' => '9ed3f670-7d6f-11e3-b1ce-5404a6144203',
  'businessType' => 'llc',
  'businessName' => 'Jane Corp',
  'ein' => '00-0000000']);

?>
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby (Recommended)
request_body = {
  :firstName => 'Account',
  :lastName => 'Admin',
  :email => 'accountAdmin@email.com',
  :type => 'business',
  :address1 => '99-99 33rd St',
  :city => 'Some City',
  :state => 'NY',
  :postalCode => '11101',
  :controller => {
      :firstName => 'John',
      :lastName => 'Controller',
      :title => 'CEO',
      :dateOfBirth => '1980-01-31',
      :ssn => '1234',
      :address => {
        :address1 => '1749 18th st',
        :address2 => 'apt 12',
        :city => 'Des Moines',
        :stateProvinceRegion => 'IA',
        :postalCode => '50266',
        :country => 'US',
      }
  },
  :businessClassification => '9ed38155-7d6f-11e3-83c3-5404a6144203',
  :businessType => 'llc',
  :businessName => 'Jane Corp',
  :ein => '12-3456789'
}

customer = app_token.post "customers", request_body
customer.response_headers[:location] # => "https://api-sandbox.dwolla.com/customers/62c3aa1b-3a1b-46d0-ae90-17304d60c3d5"
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python (Recommended)
request_body = {
  'firstName': 'Account',
  'lastName': 'Admin',
  'email': 'accountAdmin@email.com',
  'type': 'business',
  'address1': '99-99 33rd St',
  'city': 'Some City',
  'state': 'NY',
  'postalCode': '11101',
  'controller': {
      'firstName': 'John',
      'lastName': 'Controller',
      'title': 'CEO',
      'dateOfBirth': '1980-01-31',
      'ssn': '1234',
      'address': {
        'address1': '1749 18th st',
        'address2': 'apt12',
        'city': 'Des Moines',
        'stateProvinceRegion': 'IA',
        'postalCode': '50266',
        'country': 'US'
      }
  },
  'businessClassification': '9ed38155-7d6f-11e3-83c3-5404a6144203',
  'businessType': 'llc',
  'businessName': 'Jane Corp',
  'ein': '12-3456789'
}
customer = app_token.post('customers', request_body)
customer.headers['location'] # => 'https://api-sandbox.dwolla.com/customers/62c3aa1b-3a1b-46d0-ae90-17304d60c3d5'
var requestBody = {
  firstName: 'Account',
  lastName: 'Admin',
  email: 'accountAdmin@email.com',
  type: 'business',
  address1: '99-99 33rd St',
  city: 'Some City',
  state: 'NY',
  postalCode: '11101',
  controller: {
      firstName: 'John',
      lastName: 'Controller',
      title: 'CEO',
      dateOfBirth: '1980-01-31',
      ssn: '1234',
      address: {
        address1: '1749 18th st',
        address2: 'apt 12',
        city: 'Des Moines',
        stateProvinceRegion: 'IA',
        postalCode: '50266',
        country: 'US',
      }
  },
  businessClassification: '9ed38155-7d6f-11e3-83c3-5404a6144203',
  businessType: 'llc',
  businessName: 'Jane Corp',
  ein: '12-3456789'
};
appToken
  .post('customers', requestBody)
  .then(res => res.headers.get('location')); // => 'https://api-sandbox.dwolla.com/customers/62c3aa1b-3a1b-46d0-ae90-17304d60c3d5'

Check the status of the business Customer

You have created a business verified Customer; however, the successful creation of a business verified Customer doesn’t necessarily mean the Customer account is verified. Businesses may need to provide additional information to help verify their identity. It is important to check the status of the business Customer to determine if additional documentation is needed.

Request and response

GET https://api-sandbox.dwolla.com/customers/62c3aa1b-3a1b-46d0-ae90-17304d60c3d5
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY

...

{
    "_links": {
        "verify-beneficial-owners": {
            "href": "https://api-sandbox.dwolla.com/customers/d56c07fa-3832-427d-bb88-a9eb2d375c14/beneficial-owners",
            "type": "application/vnd.dwolla.v1.hal+json",
            "resource-type": "beneficial-owner"
        },
        "beneficial-owners": {
            "href": "https://api-sandbox.dwolla.com/customers/d56c07fa-3832-427d-bb88-a9eb2d375c14/beneficial-owners",
            "type": "application/vnd.dwolla.v1.hal+json",
            "resource-type": "beneficial-owner"
        },
        "deactivate": {
            "href": "https://api-sandbox.dwolla.com/customers/d56c07fa-3832-427d-bb88-a9eb2d375c14",
            "type": "application/vnd.dwolla.v1.hal+json",
            "resource-type": "customer"
        },
        "self": {
            "href": "https://api-sandbox.dwolla.com/customers/d56c07fa-3832-427d-bb88-a9eb2d375c14",
            "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/d56c07fa-3832-427d-bb88-a9eb2d375c14",
            "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/d56c07fa-3832-427d-bb88-a9eb2d375c14",
            "type": "application/vnd.dwolla.v1.hal+json",
            "resource-type": "customer"
        },
        "certify-beneficial-ownership": {
            "href": "https://api-sandbox.dwolla.com/customers/d56c07fa-3832-427d-bb88-a9eb2d375c14/beneficial-ownership",
            "type": "application/vnd.dwolla.v1.hal+json",
            "resource-type": "beneficial-ownership"
        },
        "funding-sources": {
            "href": "https://api-sandbox.dwolla.com/customers/d56c07fa-3832-427d-bb88-a9eb2d375c14/funding-sources",
            "type": "application/vnd.dwolla.v1.hal+json",
            "resource-type": "funding-source"
        },
        "transfers": {
            "href": "https://api-sandbox.dwolla.com/customers/d56c07fa-3832-427d-bb88-a9eb2d375c14/transfers",
            "type": "application/vnd.dwolla.v1.hal+json",
            "resource-type": "transfer"
        }
    },
    "id": "d56c07fa-3832-427d-bb88-a9eb2d375c14",
    "firstName": "Account",
    "lastName": "Admin",
    "email": "accountAdmin@email.com",
    "type": "business",
    "status": "verified",
    "created": "2018-04-26T19:11:41.290Z",
    "address1": "99-99 33rd St",
    "city": "Some City",
    "state": "NY",
    "postalCode": "11101",
    "businessName": "Jane Corp",
    "controller": {
        "firstName": "John",
        "lastName": "Controller",
        "title": "CEO",
        "address": {
            "address1": "1749 18th st",
            "address2": "apt 12",
            "city": "Des Moines",
            "stateProvinceRegion": "IA",
            "country": "US",
            "postalCode": "50266"
        }
    },
    "businessType": "llc",
    "businessClassification": "9ed3f670-7d6f-11e3-b1ce-5404a6144203"
}
<?php
$customerUrl = 'https://api-sandbox.dwolla.com/customers/62c3aa1b-3a1b-46d0-ae90-17304d60c3d5';

$customersApi = new DwollaSwagger\CustomersApi($apiClient);

$customer = $customersApi->getCustomer($customerUrl);
$customer->status; # => "verified"
?>
# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby (Recommended)
customer_url = 'https://api-sandbox.dwolla.com/customers/62c3aa1b-3a1b-46d0-ae90-17304d60c3d5'

customer = app_token.get customer_url
customer.status # => "verified"
# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python (Recommended)
customer_url = 'https://api-sandbox.dwolla.com/customers/62c3aa1b-3a1b-46d0-ae90-17304d60c3d5'

customer = app_token.get(customer_url)
customer.body['status']
var customerUrl = 'https://api-sandbox.dwolla.com/customers/62c3aa1b-3a1b-46d0-ae90-17304d60c3d5';

appToken
  .get(customerUrl)
  .then(res => res.body.status); // => 'verified'

You will want to ensure that both your Controller and your Business have been verified, as the Customer will be unable to send or receive funds until then. If the Customer is in retry or document, head to our next article to learn how to handle these statuses.


Next steps


Status
Production: Operational

Financial institutions play an important role in the Dwolla network.

Dwolla, Inc. is an agent of Veridian Credit Union and all funds associated with your account in our network are held in one or more pooled accounts at Veridian Credit Union. These funds may not be eligible for share insurance by the National Credit Union Share Insurance Fund. Dwolla, Inc. is the operator of a software platform that communicates user instructions for funds transfers to Veridian Credit Union.