Client Integration Guide

–By continuing to read, you agree to the confidentiality terms of our agreement.–

 

 

Table of Contents

1. Creating Customers
   1. End User Onboarding
      • Collection of End User Information
      • Recommendation and Example for Collecting
      • Certified Ownership
      • Incorporating the Dwolla TOS and Privacy Policy
      • Required Client TOS Disclosures
        
        
2. Customer Verification States
   1. Required Verification States
      • Retry
      • Document
      • Suspend
      • Deactivating an End User
   2. Beneficial Ownership Guidelines
      
      
3. Funding Sources - Adding/Verifying/Removing
   1. On-demand Transfer Authorization - if applicable
   2. Recurring Payments Transfer Authorization
   3. Adding a Funding Source
   4. Verifying a Funding Source
      • Micro-deposit Funding Source Verification
   5. Removing a Funding Source
4. Transfers: Payment Requirements
   1. Disclosure of Fees
   2. Presentation of Transfer
   3. Displaying the Funding Source
   4. Payment Transfer Workflow
   5. Funds Flow - if applicable
      • Allowing an End User to Hold a Balance
      • Allowing an End User to Transfer Funds Between their Linked Bank Accounts
   6. Negative Balance Notification
5. Real-Time Payments (RTP)
   1. Idempotency
   2. Displaying The Balance
   3. Obtaining Authorization
   4. Recurring Payments Transfer Authorization for RTP–if applicable
6. Managing Customers
   1. Closing End User Accounts
7. Support
   1. End User Assistance
   2. Dispute Resolution
8. Information Security
   1. Authentication
   2. Encryption
   3. Vulnerability Management
   4. Application Security
   5. Infosec Checklist
9. Risks & Returns
10. Operational Notifications
11. Walkthrough and Sign-Off
    1. Legal/Compliance Review
    2. Production Account Review

Terminology

• Application: Your website and/or mobile application.
• PP: Privacy Policy, your policy with regard to how you will collect, use and share an End User’s personal data.
• TOS: Terms of Service, the terms under which an End User accesses and uses your Application.
• Dwolla PP: Dwolla’s Privacy Policy, our policy which describes how we collect, use and share a Customer’s data.
• Dwolla TOS: Dwolla’s Terms of Service, the terms under which a Customer can create and use a Dwolla account.
• End User: An individual residing in the United States or a business organized and located in the United States that uses the payment services offered by the Client through the Application. Dwolla categorizes End Users in three groups, each defined below: “Verified Customers”, “Unverified Customers” or “Receive Only Users”.
• Funding Source: A Client’s or End User’s financial institution account that may be used to fund or receive payment transfers. The funding source must be a bank or credit union account at a state or federally-chartered institution–referred to as a bank account– within the United States. In certain cases, a funding source could also refer to a balance within the Dwolla Platform held by a Client.
• Receive Only User: An End User who may only receive payments and does not create a Dwolla account.
• Unverified Customer: An End User who is eligible to send and/or receive payments using the Dwolla Platform services and must create a Dwolla account.
• Verified Customer: An End User who is eligible to send and/or receive payments and hold a balance using the Dwolla Platform services and must create a Dwolla account.

 

1. Creating Customers

1a. End User Onboarding

Collection of End User Information

Depending on the End User account type you are approved for (e.g. Verified Customer Record, Unverified Customer Record), you will need to collect various pieces of information to pass to Dwolla. You can read more about the data requirements in our developer documents here. For a faster build and less development work, check out our low-code solutions.

In addition, due to the customer due diligence rule requirements under the Bank Secrecy Act, when End Users open business Verified Customer Record (“VCR”) accounts and are corporate entities, you will need to collect controller and beneficial owner information of that End User, which will be passed to Dwolla.

A controller is a natural person who holds significant responsibilities to control, manage or direct a company or other corporate entity (e.g. CEO, CFO, General Partner, President, etc). A company may have more than one controller, but only one controller’s information must be collected.

A beneficial owner is a natural person who—directly or indirectly—owns 25 percent or more of a company. If there are no natural persons who own 25 percent or more of a company, then no information needs to be collected. A beneficial owner cannot be another company (or other corporate entity), nor a nominee owner.

You will also need to collect a certification from the person creating the business VCR account in order to verify that the information is accurate.

Recommendation and Example for Collecting Certification of Ownership

One way to collect the certification is to have the person check a box to indicate that s/he certifies the information provided is, to the best of his or her knowledge, complete and correct. If this information is being collected at a different stage than the acceptance of the Dwolla TOS and Privacy Policy, this check box will also need to be followed by clicking a button to submit that acceptance in order to capture express consent.

We have included an example of a form with recommended language, as well as the data required to be collected for the beneficial owner(s), controller and certification, in the appendix of the integration guide. Ultimately, your application will need to be able to accept this information for up to four beneficial owners in addition to one controller.

Learn more about the customer due diligence rule in this FAQ, including exceptions to the customer due diligence rule, and understand what these changes mean for Dwolla Clients and the business VCR accounts created within the API. To help avoid any disruption to your business, Dwolla has prepared developer documentation for review and updated our sandbox to allow Clients to test these requirements.

Incorporating the Dwolla TOS and Dwolla PP

Prior to passing data to Dwolla to create a Customer (End User), you must obtain your End User's (a) acceptance of your Client TOS and Privacy Policy, and (b) acceptance of the Dwolla TOS and Privacy Policy.

There are two options for presenting the Dwolla TOS and Privacy Policy within your application flow. Regardless of the method you choose, you are responsible for capturing your End User’s expressed consent to the Dwolla TOS and Privacy Policy and providing an opportunity for them to review these prior to acceptance (e.g. provide a link to each document). The preferred method for capturing express consent is to have your user check a box to indicate that they accept the terms (and Client TOS, if applicable), then click a button to submit their acceptance.

Example Below:

Note: You must ensure that your application complies with federal electronic signatures law and that each acceptance of the Dwolla terms by an End User is recorded in a manner that can be audited.

Option 1: Capture acceptance of Dwolla terms and Client TOS in separate flows

You may already have a flow established for signing up new End Users to your application. If a process already exists or if you would like to keep your terms acceptance flow independent from the acceptance of the terms, you may create a separate flow that is only used to capture acceptance of Dwolla’s terms.

Note: End Users must have already accepted your Client TOS in order to accept the Dwolla TOS.

Option 2: Capture acceptance of Dwolla TOS and Client TOS in a combined flow

Required Client TOS Disclosures & Considerations

As set out in your Dwolla Client agreement, you must include certain information in your Client TOS that explains the End User’s relationship with Dwolla. You may use the following sample language, or substantially similar language, to satisfy that requirement:

1. If a Client will have both VCR/CR and RO End Users, the TOS must demonstrate the correct use of appropriate Dwolla language as applied to each type of End User–excerpts must include hyperlinks to both the Terms of Service and Privacy Policy.
   1. Verified Customer Record/Customer Record Language
      In order to use the payment functionality of [Client’s/our] application, you must open a "Dwolla Platform" account provided by Dwolla, Inc. and you must accept the Dwolla Terms of Service and Privacy Policy. Any funds held in or transferred through the Dwolla Account are held or transferred by Dwolla’s financial institution partners as described in the Dwolla Terms of Service. You authorize [Client/us] to collect and share with Dwolla your personal information including full name, [date of birth, social security number, physical address,] email address and financial information, and you are responsible for the accuracy and completeness of that data. You understand that you will access and manage your Dwolla account through [Client’s/our] application, and Dwolla account notifications will be sent by [Client/us], not Dwolla. [Client/We] will provide customer support for your Dwolla account activity, and can be reached at [website], [email] and/or [phone number].
   2. Receive Only Language
      "You expressly authorize [Client’s] service provider, Dwolla, Inc. to originate credit transfers to your financial institution account. You authorize [Client/us] to collect and share with Dwolla your personal information including full name, email address and financial information, and you are responsible for the accuracy and completeness of that data. Dwolla’s Privacy Policy is available here.
      • Clarifying point: ROs should not accept Dwolla’s Terms of Service and Privacy Policy due to the fact they are not setting up a Dwolla account.
2. Client Name Must Match the Contracted Entity
   Ensure the company listed in the TOS is the same as the identified Client in the contract.
3. Facilitation Fee Disclosure
   Due to the Reg E requirement, if a facilitation fee is being taken from transactions the Client will need to disclose:
   • Where and how the End User is informed of the fee.
   • When End Users are notified of fees–this should happen prior to a fee actually being charged.
4. Age Restriction (18, 13, none)
   All Customers that are created must be at least 18 years old in order to create a Dwolla account. If there is no age restriction for the application or the restriction is less than 18, you will need to have certain controls in place to ensure you are complying with the contracted terms. We may request that you provide us additional information or a demonstration of such controls. Receive Only End Users must be at least 13+ years old in order to create an account.
   • If there is no age restriction for the application, you will need to have certain controls in place to ensure you do not provide Dwolla any information relating to a child under the age of 13.
5. Accountability
   The Client should make sure that there is contact information in the Client’s TOS for any questions or concerns, in addition to having that information in another place for End Users to find on a website.
6. Agreeing to TOS/PP
   There must be a 2-step authorization process for accepting the Terms of Service and Privacy Policy. The end-user must select a box stating that they agree to both parties TOS/PP as well as select a button that says, “Agree and Continue”.
   • By checking this box you agree to our Terms of Service [include hyperlink] and Privacy Policy [include hyperlink], as well as our partner Dwolla’s Terms of Service and Privacy Policy.

 

2. Customer Verification States

2a. Required Verification States

It is required that the following verification states are built out on your platform. You will be notified of these events via webhooks. The information collected needs to be passed through the API to Dwolla.

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.

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

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.

Suspend

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.

Deactivating an End User

Under the customers tab search for your End User Once the End User is selected, hit the ellipsis button then hit “deactivate customer”. A separate window will appear asking you to confirm your decision. Select that checkbox and hit “deactivate”.

2b. Beneficial Ownership Guidelines

To help the government fight financial crime, Federal regulation requires our financial institution partners to obtain, verify and record information about the beneficial owners of legal entity customers. 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 (e.g. the beneficial owners) helps law enforcement investigate and prosecute these crimes.

This is a requirement ONLY if you are creating Business verified Customers. Business verified Customers will need an Account Admin to sign up the company during the onboarding process. This Account Admin is not identity verified, unless that Account Admin also identifies as a controller. To verify a business customer, the business needs to provide sufficient information about at least one controller and up to four beneficial owners to permit Dwolla to verify each individual’s identity. Collection of this information is required by U.S. regulations prior to allowing a business customer to transact using Dwolla’s software. A “controller” is an individual who holds significant responsibilities to control, manage, or direct the company (i.e. CEO, CFO, General Partner, President, etc). A company may have more than one controller, but only one controller’s information must be collected. A “beneficial owner” is any natural person who, directly or indirectly, owns 25% or more of the equity interests of the company.

What information do I have to provide?

To ensure alignment with the beneficial ownership guidelines, you are required to collect the name, address, date of birth and Social Security number (or passport number in the case of foreign persons) for the following individuals (e.g. the beneficial owners):

1. Each individual, if any, who owns, directly or indirectly, 25 percent or more of the equity interests of the legal entity customer (e.g. each natural person that owns 25 percent or more of the shares of a corporation); and
2. An individual with significant responsibility for managing the legal entity customer (e.g. a CEO, CFO, COO, Managing Member, General Partner, President, Vice President or Treasurer).

Dwolla may also ask to see a copy of a driver’s license or other identifying document for each beneficial owner listed.

Beneficial Owners

The following information must be collected for each individual, if any, who, directly or indirectly, through any contract, arrangement, understanding, relationship or otherwise, owns 25 percent or more of the equity interests of the legal entity listed above. If no individual meets this definition, please check “Beneficial Owner Not Applicable” below and skip this section.

[Beneficial Owner Not Applicable]

• Beneficial Owner 1 Information
  • First Name
  • Last Name
  • Date of Birth
  • SSN or Passport ID #
  • Identification Type
  • Identification Country of Issuance
  • Address 1
  • Address 2
  • Address 3
  • City
  • State/Province/Municipality
  • Country
  • Post Code

For a non-U.S. person without a SSN/TIN, a passport number and country of issuance will be requested.

Controller

The following information should be collected for one individual with significant responsibility for managing the legal entity listed above, such as:

• An executive officer or senior manager (e.g. Chief Executive Officer, Chief Financial Officer, Chief Operating Officer, Managing Member, General Partner, President, Vice President, Treasurer); or
• Any other individual who regularly performs similar functions.
  • First Name
  • Last Name
  • Title
  • Date of Birth
  • SSN or Passport ID #
  • Identification Type
  • Identification Country of Issuance
  • Address 1
  • Address 2
  • Address 3
  • City
  • State/Province/Municipality
  • Country
  • Post Code

For a non-U.S. person without a SSN/TIN, a passport number and country of issuance will be requested.

Certified/Agreed To By:

Person opening the account:

• First Name
• Last Name
• Title Name
  I,____ (name of the natural person opening an account), hereby certify, to the best of my knowledge, that the information provided above is complete and correct.
  Signature/Date

 

3. Adding/Verifying/Removing Funding Sources

3a. On-demand Transfer Authorization - if applicable

If your application allows payers to authorize transfers for variable amounts from their bank account using bank transfers at a later point in time for products or services, on-demand transfer authorization is required from your End User. It’s an additional step, but you must obtain a quick authorization from the End User, prior to them adding a funding source.

You must use the following language to satisfy the authorization requirement (text is provided from on-demand-authorization API endpoint):

• Paragraph text:
  "I agree that future payments to [Client Name] will be processed by the Dwolla payment system from the selected account above. In order to cancel this authorization, I will change my payment settings within my [End User Name] account."
• Button text:
  “Agree and continue”

Clarifying point: if you are using Dwolla.js this language will already be included and will not require you to add any further language.

On-demand transfer authorization is submitted via the API to Dwolla along with the details of the End User’s bank account when adding a funding source. If on-demand transfer authorization is provided on a funding source, you must use the following content when notifying the End User in the required funding source added email:

• Email text:
  “You've agreed that future payments to [Client Name] will be processed by the Dwolla payment system using bank account [bank name/ID], and if you want to cancel this, do [X].”

 

Removal of On-demand Transfer Authorization

If your End User contacts you to request removal of on-demand authorization, then you must comply by removing the bank account attached to the End User. Removal of your End User’s bank account will revoke the on-demand authorization set on the End User’s funding source.

3b. Recurring Payment Transfer Authorization - if applicable

Recurring payments are automatic payments that a user authorizes to be made on a regular billing cycle. Generally, the billing cycle is on a set day of every month. For authorization of a recurring payment transfer to be effective, the amount must be consistent and the schedule for payments must be regular intervals (i.e., your platform charges a $4 fee per month for subscription access). The user must clearly acknowledge and authorize the amount and the schedule. You must clearly explain to your End User how to cancel this authorization and you must honor timely requests to cancel such payments.

Additionally, you must send an email to your End User once recurring payments have been set up, as Dwolla cannot provide this notice through Operational Notifications. You will also need to notify the End User in advance of each payment unless they waive such right in accordance with regulations.

• Example Email text:
  “You have set up $XX.XX payments to be made each [payment schedule] to [Client Name] which will be processed by the Dwolla payment system using bank account [bank name/ID], beginning on MM/DD/YYYY. If you want to cancel this, [do X].”

Please note that if you are collecting authorizations in advance for ACH debits of varying amounts, on-demand language is required. If you are using real time payments please see section 5d.

Removal of Recurring Transfer Authorization

If your End User contacts you to request removal of recurring authorization, then you must comply by removing the bank account attached to the End User. Removal of your End User’s bank account, as outlined in section 3e, will revoke the recurring transfer authorization set on the End User’s funding source.

3c. Adding a Funding Source

A bank account can be linked to an End User to act as a funding source. When adding a funding source to an End User, you will send a request to Dwolla providing their bank account details (account number, routing number and name of funding source).

Important: You must utilize the funding source “name” parameter to clearly identify the bank account that is being added. The funding source “name” will be used to identify and display the End User’s funding source within your application’s user interface and in email notifications. Because this is sensitive information, you must encrypt the data while transmitting it as set out in the information security section (Section 8b) on encryption requirements. Upon successful creation of the funding source, you must respond accordingly by immediately sending out an email to the End User notifying them that their bank account has been added.

3d. Verifying a Funding Source

By default, when a funding source is added through collection of the bank account details it will be marked as “unverified” and is only eligible to receive funds.

In order for an End User to send funds from a linked bank account, the ownership of the bank account must first be verified in a commercially reasonable manner. You can leverage Dwolla’s micro-deposit or instant account verification (IAV) bank verification methods or use your own method of bank verification. If you utilize your own method of bank verification, it must be reviewed by Dwolla prior to going live in production. If a funding source is later marked as verified, you are required to send an email notification to the customer.

Micro-deposit Funding Source Verification

If your application leverages Dwolla’s micro-deposit method of bank verification then you are required to notify the End User through each step of the micro-deposit verification process (initiated and completed or failed) by sending email notifications. Please note that micro-deposits cannot be sent via RTP.

3e. Removing a Funding Source

Within your application, you should give your customer (End User) the ability to remove a linked bank account or debit card. Any references to a given bank account must clearly identify that bank account using the funding source “name” parameter, which represents the name your End User specified when they added their bank account. If a bank account has been removed, you must not process or attempt to process any transactions on that bank account. Upon successful removal of the funding source, you are required to send an email notification to the customer (End User. If the removed funding source contains an on-demand authorization, you are required to inform your customer (End User) of this removal in the required funding source removed email notification.

 

4. Transfers: Payment Requirements

4a. Disclosure of Fees

If your application charges any fees, the fees must be clearly conveyed and communicated to the customer (End User) prior to payment being made. You are responsible for disclosing any fee payment terms to the customer (End User) and obtaining their express consent to charge them a fee.

4b. Presentation of Transfer

Transfers must be clearly displayed in a manner that indicates the terms of the payment. If your application allows End Users to buy goods or services from you or other End Users, your application must clearly identify and disclose the following at the point of payment (this list is not intended to be exhaustive):

• The payment recipient
• The goods or services being purchased
• The purchase price (and quantity, if applicable)
• The payment schedule, if applicable

This information must be shown to the customer (End User) so that they can review it, prior to authorizing the transfer.

4c. Displaying the Funding Source

Your application must identify the funding source[s] that will be used for a given transfer [source and/or destination account, as appropriate], prior to collecting the End User’s authorization for the transfer. A customer (End User) must always have adequate notice of which funding source their funds will be transferred to or from before the transfer occurs, as appropriate [See examples below]. Identification of funding sources within your application and content included in required email notifications depend on your transfer workflow[s]. A few examples are provided below for reference.

Transfer workflow examples:

1. Between an End User’s Bank Accounts (e.g.“You are transferring $xx.xx from “Superhero Savings Bank - checking” to “Superhero Savings Bank - savings”)
2. End User A (sender) Bank Account to End User B (recipient) Bank Account - The source and destination funding sources in a transfer between the two parties will be displayed differently for End User A in comparison to End User B. End User B (recipient) must indicate which bank account they wish to receive funds into before a transfer is initiated (e.g. For End User A (sender), “You are sending $xx.xx from “Superhero Savings Bank - checking” to End User B). For End User B (recipient), “You are receiving $xx.xx into bank “Superhero Savings Bank - checking” from End User A).
3. Client Account to an End User’s Bank Account or Debit Card (e.g. “You are receiving $xx.xx into bank “Superhero Savings Bank - checking”)

 

4d. Payment Transfer Workflow

Bank transfers will follow a lifecycle with different transfer states. You are required to notify your customers (End Users) through each step of the transfer. Contact your Integration Manager if you have any questions on email distribution for any of the transfer events outlined below.

A normal bank transfer workflow includes the following statuses:

• A transfer is initiated and starts off as “pending.” A transfer is pending when the money has yet to leave the funding source or it is enroute to its destination. Upon successful creation of the transfer, you are required to send an email notification to the customer (End User) [or customers (End Users), if applicable]. An email must be sent immediately after receiving the webhook containing the customer_transfer_created event.
• Once the bank transfer has cleared successfully, it will be marked as “processed.” A processed transfer represents money that has reached its destination—either the End User’s balance or their linked bank account. Balance funds are now available for the recipient to use. For funds sent to a bank account, the bank may take additional time to make the funds available to the recipient.
  Note: “processed” is not necessarily a final state as a “processed” transfer may subsequently “fail”, as set out below. Upon receiving the webhook containing the customer_transfer_completed event, you must notify the customer (End User) [or customers (End Users), if applicable] immediately that that transfer was successfully completed. If there is more than one customer involved in the transfer request then two webhooks will be sent by Dwolla and you will need to send two email notifications (one to each customer involved).

Besides the bank transfer statuses of “pending” and “processed” there are two other transfer statuses which can occur: “cancelled” and “failed”.

• If a transfer status changes from “pending” to “cancelled” this means that the transfer was cancelled. A transfer can be cancelled by the Customer or Customer’s users as outlined in Dwolla’s developer documentation. Upon successful cancellation of the transfer, you are required to immediately send an email notification to the customer (End User) [or customers (End Users), if applicable].
  Note: If there is more than one customer (End User) involved in the transfer request, then two webhooks will be sent by Dwolla, and you will need to send two email notifications (one to each End User involved).
• If a transfer failed to clear successfully (usually, as a result of an ACH reject) the transfer’s status will be “failed”. Transfers can fail for a number of reasons (e.g. insufficient funds, invalid account number, no account/unable to locate account, etc).
  Note: In rare cases, a “processed” transfer may later on be returned as “failed”. Upon receiving a webhook containing the transfer_failed event, you are required to immediately send an email notification to the customer (End User) [or customers (End Users), if applicable].

 

4e. Funds Flow - if applicable

Allowing an End User to Hold a Balance

If your application is creating End Users who are set up as Verified Customer Records (Personal or Business), then you are required to allow that End User (VCR) to hold funds in their balance funding source. Verified Customer Records (Personal or Business VCRs) is the only customer type that is able to hold a balance. Unverified Customers or Receive Only users cannot utilize the balance. We have a prebuilt solution for displaying the balance available here.

You must provide an easily accessible and accurate summary of the End User’s balance transfer history that includes:

• Amount of each transfer;
• Date each transfer was credited or debited to the End User;
• Type of each transfer;
• Name of each party to or from whom funds were transferred;
• Fee(s) charged for each transfer, if any;
• Activity for specific calendar months and show the beginning and ending balance for that month;
• Current balance*; and
• Activity within the most recent 2 years.

*Note:

• All Dwolla Clients are responsible for ensuring at least a zero balance for all VCR End User record accounts.
• All Dwolla Clients are required to display a VCR’s balance within the UI.
  
  

Allowing an End User to Transfer Funds Between their Linked Bank Accounts

If your application will allow an End User to transfer funds between their own linked bank accounts, the End User’s funds will need to pass through the Dwolla system on their way from the sending bank account to the receiving bank account. If the funds are unable to settle to the receiving bank account (e.g. the bank rejects the transaction), you will receive a webhook notification from Dwolla informing you that the transfer has failed. You must respond accordingly by immediately sending out an email to the End User notifying them that their transfer failed to process successfully.

If funds are unable to settle to the receiving bank account, you must immediately return the funds to the sending bank account (e.g. initiate a transfer from the End User’s balance funding source to the originating source bank account). We recommend that you inform the End User that the funds are being returned to their originating source bank account in the email notification that you send.

Note: When a customer (VCR End User) record(s) balance falls negative because of a return, the Client is responsible for ensuring the account is brought to at least a zero balance. An email is sent to the main email address on the Dwolla account including the details about the failed transaction and the corresponding customer name. There is also a webhook event that you can subscribe to, which is listed in the developer documentation.

Allowing an End User to Hold a Balance

If your application will allow an End User to transfer funds to another End User, then one of the End Users (if not both) must be a Verified Customer Record (VCR) and able to hold funds in their balance funding source. This is a Dwolla system requirement (and the requirements in the section “Allowing a Customer to Hold a Balance” above will apply for the End User(s) that can hold a balance).

For a transfer sent from End User X to End User Y, the funds will pass through the Dwolla system on their way from End User X’s balance funding source or linked bank account to End User Y’s balance funding source or linked bank account. If the funds are unable to settle to End User Y (e.g. End User Y’s bank rejects the transaction), you will receive a webhook notification from Dwolla informing you that the transfer has failed. You must respond accordingly by immediately sending out an email to the customer (End User) notifying them that their transfer failed to process successfully.

If that occurs, you must immediately return the funds to the End User X account from which the funds were originally sent (e.g. initiate a transfer from the sending customer’s (End User’s) balance funding source to the originating source bank account).

4f. Negative Balance Notification

All ACH transfers are subject to return codes. Refer to this article to understand the ACH Returns Process. When a return code is received in, that will cause a transfer failure. A negative balance occurs when funds are withdrawn out of the Dwolla Network before a return code is received from the financial institution of the sending party. When Dwolla receives the return code, at this point the transaction cannot be reversed and funds cannot be pulled out of the receiver’s bank account. Therefore, the funds are pulled out of the end user’s balance, causing the funding source to go negative and putting the Client’s application at a loss. The handling of negative balances is a fully automated process to align with all relevant rules and regulations.

Clients are responsible for maintaining at least a zero Dwolla balance for customer (VCR End User) records within your application.

If an VCR End User balance has gone negative, Dwolla Clients are responsible for making the Dwolla account whole. Dwolla will notify Clients of the negative balance via email and request they bring the account to a zero balance. If no action is taken, Dwolla will debit the Client’s billing source within 5 business days.

There is also a webhook event that you can subscribe to, which is listed in the developer documentation.

 

5. Real-Time Payments (RTP)

The RTP® Network is a newer payments network developed and launched by The Clearing House (TCH). RTP provides the ability to send faster payments to End Users, but it works differently than other payment systems you might be more familiar with, such as credit or debit cards and the ACH Network.

Note: Only financial institutions that have agreed with TCH to participate in the RTP® Network are eligible to send or receive RTP transactions. Many of the major financial institutions in the U.S. are participants. Only U.S. depository financial institutions are eligible to participate.

The RTP® Network operates as a push system, meaning all RTP transfers are credit sends.. This payment type can be utilized in both send and facilitate funds flows.

Note: All RTP transactions are irrevocable and cannot be canceled.

5a. Idempotency

RTP transfers are irrevocable once sent. Dwolla strongly recommends that you implement idempotency into your platform. Dwolla supports passing in an Idempotency-Key header with a unique key as the value to prevent an operation from being performed more than once . Multiple POSTs with the same idempotency key and request body won’t result in multiple resources being created. It is recommended to use a random value for the idempotency key, like a UUID (Idempotency-Key: d2adcbab-4e4e-430b-9181-ac9346be723a). For more information, please reference our developer documentation.

For example, if a request to initiate a transfer fails due to a network connection issue, you can reattempt the request with the same idempotency key to guarantee that only a single transfer is created. Without idempotency, there is a higher risk a business could accidentally send an RTP transfer twice because they are not sure it went through. If that were to occur, no one at Dwolla or our financial institution partners would have the ability to cancel the payment and we cannot guarantee you or your End Users can recover funds sent in error. Idempotency help will protect multiple transactions being initiated by accident.

5b. The Balance

In order to send funds via RTP, you must have funds loaded into your Dwolla Balance in the Dwolla Network. The Dwolla Balance is a Funding Source that can be utilized like a “wallet” for holding a stored value of USD funds.

When creating a transfer to add funds into a Dwolla Balance, you will have to make sure to use the Balance funding-source ID in the destination URL. You will only be able to send funds via RTP from your Dwolla Balance. It is important to make sure you have all the funds you want to send available in your balance.

Displaying the Balance

If you plan to let your End Users send RTP transfers, you must ensure they are properly created as Business Verified Customer Records(bVCR). Your End Users will only be permitted to send funds they are holding in their balance funding source. As a result, it will be even more important to have a way to display the End Users’ balance in your application. We have a prebuilt solution for displaying the balance available here.

If you are going to build this feature yourself, you must provide an easily accessible and accurate summary of the End User’s current balance and a comprehensive transfer history that includes:

• Amount of each transfer;
• Date each transfer was credited or debited to the End User;
• Type of each transfer; i.e. ACH or RTP
• Name of each party to or from whom funds were transferred;
• Fee(s) charged for each transfer, if any;
• Activity for specific calendar months and show the beginning and ending balance for that month;
• Current balance*; and
• Activity within the most recent 2 years.

*Note:

• All Dwolla Clients are responsible for ensuring at least a zero balance for all VCR accounts.
• All Dwolla Clients are required to display a VCR’s balance within the User Interface

 

5c. Obtaining Authorization

If your application allows payors to make RTP transfers, we require you obtain consent from your End User prior to sending the transaction. You must have the Business Verified Customer Record (bVCR) select RTP as their payment mechanism, especially if you are offering both RTP and ACH. Please note that funds will be transferred instantly and that the sending of these funds is irrevocable and cannot be canceled.

5d. Recurring Payment Transfer Authorization for RTP - if applicable

Section 3b describes the generally applicable rules for authorization of a recurring payment transfer, and all these rules apply to a similar authorization using RTP. If your application permits multiple payment methods, you must specifically collect authorization to initiate recurring payments via RTP, in accordance with Section 5c above.

6. Managing Customers

 

6a. Closing End User Accounts

You must immediately notify Dwolla at support@dwolla.com if your contractual relationship with any of your End Users is terminated. If an End User holds a balance at termination, the funds must be handled or disbursed in compliance with your Client Terms of Service, prior to termination.

7. Support

7a. End User Assistance

You will be responsible for supporting your End Users and their payment needs. It is recommended that you implement a Help or FAQ section within your application and/or on your website that aids in answering questions related to the payment process (and other aspects of using your application). In addition, your customer support policy and contact information must be easily accessible within your application and/or on your website.

If your End User requests Dwolla’s customer support contact information, you must provide the following: support@dwolla.com and 1-888-289-8744.

7b. Dispute Resolution

You are responsible for resolving your End User’s disputes that relate to your application, including any disputes solely related to your services that your users may communicate to Dwolla. (Dwolla will inform you of any such communication). Dwolla has no obligation to provide dispute resolution support to your End Users, but may choose to assist an End User that contacts us. You agree to provide Dwolla with any requested information regarding the status and/or resolution of a specific dispute pertaining to your services.

8. Information Security

The Dwolla Platform uses strong security to protect End User data and, as a Client, you also have security responsibilities when integrating the platform into your application.

8a. Authentication

• Actions that result in the movement of money in or out of the Dwolla network (including microdeposits), or that allow access to sensitive information such as social security numbers or bank account numbers, are required to use strong authentication. Strong authentication means multi-factor authentication in addition to a password with strength equivalent to eight characters including a letter, number and symbol.
  Note: email or SMS-based “magic links” (i.e., links that allow login without actually authenticating) are not acceptable under this standard.
• If multi-factor authentication is not used, a password with strength equivalent to twelve characters including a letter, number and symbol is required. Primary and secondary authenticators must never be sent via the same medium.
• It is permissible to utilize third-party authentication from the following list of identity providers (others will require review by Dwolla or evidence that the client has performed equivalent diligence): Google, Apple, Okta, LastPass Identity, Azure Active Directory, Facebook, Twitter, or an on-premise Active Directory. In these cases, as these sites do not conform with the password requirements above and might not enforce MFA, you must require a second factor (such as an emailed confirmation code) on new devices before the user is able to access sensitive information or initiate the movement of money in or out of the Dwolla network (including microdeposits).
• It is permissible to only require a password on initial login, and allow subsequent logins with an easier authenticator. This requires that you utilize the device's secure enclave (e.g., TouchID, Titan M, Secure Element (SE), TrustZone) to store the password, require a 6-digit PIN or biometric (i.e., fingerprint, facial recognition) to decrypt the password, and still use the password (not the secondary authenticator) for authentication from the mobile device to the backend system.
• Passwords must be stored using a strong password hash algorithm (including a salt value). Suitable algorithms and parameters include:
  
  

  	Minimum	Suggested
  bcrypt	Work factor 11	Work factor 14
  pbkdf2	100,000 rounds	1,000,000 rounds
  scrypt	N: 2^15, R: 8, P: 2	N: 2^18, R: 8, P: 2
  argon2id	T:4, M: 2^17, P: 8	T:16, M: 2^19, P: 8

 

• Password reset actions require a notification to the End User (email or other out-of-band medium)
• Password guessing (brute forcing) attempts must be controlled
  • Lockout after 10 incorrect attempts or less, automatic unlock after expiration period exceeding 30 minutes.
• Security-relevant events, including authentication and authorization, should be captured (success, failure) including pertinent information such as: the action taken, target object or user, IP address, date/time (synchronized to a reliable source) and user identifier.
• Email addresses must require validation prior to End Users interacting with payment-related services.
  
  

8b. Encryption

• Data in-transit:
  • TLS v1.2 is required. TLS 1.1, 1.0 and all versions of SSL must be disabled.
  • HTTP Strict Transport Security (HSTS) and Content Security Policy (CSP) settings are recommended.
• Data at-rest: Standards-based symmetric key cryptography is required for all sensitive data (e.g. customer personally identifiable information, bank account numbers, Know Your Customer information, etc).
  • AES128/256 using CBC, CTR or GCM modes. GCM is preferred.
  • Key management techniques must include controlled and protected access with rotation capability.
    
    

8c. Vulnerability Management

• Clients are expected to securely maintain systems and software. Public or End User facing systems (attack surface) hosted by the Client are to be managed, such that identified vulnerabilities are remediated in a timely fashion (no more than 30 days from discovery for high vulnerabilities based on CVSS rating).
• Clients are required to provide a security contact to Dwolla to ensure proper communication is possible during a security event.
  • Clients must promptly report information security breaches to Dwolla, Inc.
• Clients are expected to respond to customer or internet-based vulnerability submissions, via a responsible disclosure process.
  
  
  

8d. Application Security

• Clients are expected to protect their solution from internet-based attacks using industry-standard techniques including, but not limited to:
  • Reduced attack surface (network firewall and/or reverse proxy) to limit exposed ports/protocols to only what is needed to run the solution.
  • Protection from common vulnerabilities.
    • The OWASP Top 10 project is a good starting point (currently includes: Cross Site Request Forgery (CSRF), Cross Site Scripting (XSS), Insecure Direct Object Reference (IDOR), etc).
    • Application security scanning by a third party is recommended.
  • Solutions must degrade gracefully to protect sensitive information about the system (e.g., stack traces or exceptions exposing internal elements of a Client’s solution should be suppressed and not returned to users).
  • Border protection, such as CloudFlare or AWS CloudFront, is recommended to adapt to and defend against advanced Internet threats such as application-layer and DDoS attacks.
    
    

8e. Infosec Checklist

Dwolla encourages all Clients to use leading practices and capacities related to Information Security (InfoSec) threats. Each Client is required to complete an InfoSec questionnaire during the application submission process. The questionnaire must be approved by Dwolla’s review team prior to going live with the platform.

9. Risk and Returns

Dwolla does not offer fraud protection or fraud monitoring. You are responsible for reviewing transactions, returns and suspicious activity and providing a contact to Dwolla who works closely with monitoring users and transaction activity and can quickly react should there be any suspicious usage. We request you notify Dwolla at support@dwolla.com if there are successful/known fraudulent user transactions. You will be expected to respond to any inquiries from the Dwolla Risk & Compliance team about specific users.

10. Operational Notifications

Email notifications for activity on the platform are a requirement to conduct your business. By default, Dwolla sends emails to your End Users on your behalf. These emails would include your logo, website, support email, reply-to email address etc. so they would look like they were coming directly from you. To set up or edit your email settings within the Dwolla Dashboard, click on your name in the right corner, select Basic Info and scroll down to Email Settings.

These email notifications are sent to your End Users when they complete the activities focused on the following key functions in your application (powered by the Dwolla Platform) or via the Dwolla Dashboard:

• Customer creation
• Bank account management and validation
• Money added to a balance
• Money withdrawn from a balance
• Money sent to another user (or your company)
• Money received from another user (or your company)
• Customer verification and suspension

A full list of all events is listed here. Please review to ensure you know when your customers will receive notifications. In addition to the email notifications listed in that link, your business will have additional communications to be sent to your End Users and there may be other Dwolla-required emails as well. Please contact your Integration Manager with questions about your specific integration and recommended (or required) emails.

If you do not want to utilize Dwolla’s Operational Notifications and instead send out your own, please contact your Integration Manager for more information. You will be required to fill out the email templates within the application portal and will require additional Legal review which may extend your application review period.

11. Walkthrough and Sign-Off

Prior to going live for your End Users, a Dwolla representative will conduct a thorough review of your application. The goal of this final walkthrough is to confirm that contractual and integration requirements have been met. Approval is granted in Dwolla’s sole discretion and is based on the requirements set out in this document and all related API documentation.

11a. Legal/Compliance Review

During the review process, Dwolla representative(s) will simulate the End User experience and review the transfer workflow in the Client’s staging environment. The following items will be reviewed on the Client’s website and, if applicable, mobile application:

• Presentation of the Client TOS and Privacy Policy and the Dwolla TOS and Privacy Policy
• End User experience of onboarding and transfer flow, including notification emails (If different types of End Users, multiple scenarios will be tested)**
  • **Please refer to Demo Checklist provided by the Integration Manager
• Application’s functionality is inline with the business model and use cases originally communicated to Dwolla
  
  

11b. Production Account Review

Once your application has successfully completed the review process, Dwolla’s Integration Manager will transition you to production by conducting a final review of your production Dwolla account. The Client, owner of the application, must have a verified, full Dwolla Platform account.

• The account must be a Business, Government or Non-Profit account
• The account must not be in any restricted or suspended state
• The account must have a verified bank account attached
  
  

– Confidential –