Imagine your business pays contractors on a weekly basis. Currently the process for paying out your end users involves writing checks for each of them. Not only is this a time-consuming method of paying people out, but your contractors will also be responsible for depositing these funds into their bank. It’s inefficient, expensive (each check costs a business about $7 in time and material) and inconvenient.

Enter: Dwolla

With Mass Payments in the Dwolla API, you can automate payouts by going electronic and send funds to 5,000 different bank accounts with one API call, while incurring just one ACH debit.

Our white-label solution allows you to build out the method of payouts to fit your business’ needs.

Whether you choose to construct a CSV uploader or create your own front end components that allow for greater collaboration with your team, Mass Payments with Dwolla is flexible enough to support your needs.

Let’s walk through a scenario where your business needs to pay two different end users using Dwolla’s Mass Payment functionality.

Step 1 – Initiate the Mass Payment Job

Initiating a Mass Payment job involves specifying the bank accounts that will be sending or receiving the funds.

With this example, we will specify the funds will be sent to two different bank accounts.

Optional parameters that you can add include metadata, correlation ID and ACH details. These optional parameters make it easy to track the individual transfer items within the API after the initial job is completed.

Create a MassPayment – Parameters

Parameter Required? Description
Source Yes The funding source where funds are being debited from–specify a bank or balance funding source.
Destination Yes The funding source where funds are being credited to–specify a bank or balance funding source.
correlationId No Searchable in the API, correlationId allows traceability between two systems.
Specify an ID and use that ID from the point of origin on, instead of waiting for a response from Dwolla to then obtain an ID.
metadata No Add insight to your transfers by adding metadata.
Up to ten key-value pairs are allowed.
achDetails No Utilize the achDetails to assign and expose an addenda record to your Customers.

 

```
POST api-sandbox.dwolla.com/mass-payments
Content-Type: application/json
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer 4VCTm1Hm1XLHh9RCnKBjG3qUTaiP2Mkfifl9UvVnXeG6LYFB66
Idempotency-Key: 0a90909e-682b-405d-9369-69f7242b7ed7

{
    "_links": {
        "source": {
            "href": "https://api-sandbox.dwolla.com/funding-sources/3152c22b-3d72-442d-a83b-e575df3a043e"
        }
    },
    "items": [
      {
        "_links": {
            "destination": {
                "href": "https://api-sandbox.dwolla.com/funding-sources/8f85e2fe-7126-4505-bbe2-5c89bc409842"
            }
        },
        "amount": {
            "currency": "USD",
            "value": "101.01"
        },
        "metadata": {
            "itemId": "item1"
        }
      },
      {
        "_links": {
            "destination": {
                "href": "https://api-sandbox.dwolla.com/funding-sources/dd22c4e6-cb00-4b72-92d1-2cd06c6f6032"
            }
        },
        "amount": {
            "currency": "USD",
            "value": "202.02"
        },
        "metadata": {
            "itemId": "item2"
        }
      }
    ],
    "metadata": {
        "jobId": "Job1"
    }
}
```

 

Every item takes about a half-second to complete validation and be added to the batch. Knowing this, a Mass Payment job with 5,000 items will take around 45 minutes for full completion. Rather than waiting in the dark, Dwolla will inform you when the job is completed by sending a masspayment_completed webhook. This webhook will act as a notification that the Mass Payment is completed and you can move onto the next step. This also indicates that the transfer is created and that you should expect a single debit coming out of the bank associated with this Mass Payment job.

Step 3 – Check for Failed Individual Items

After being informed that the Mass Payment job has been completed, you will want to check for any failures for the individual items.

As detailed in the previous step, Dwolla will run validation checks on each individual item to ensure they are valid to receive funds. Item failures can occur on a number of instances. Dwolla will return a list of all the items created and failed. It is recommended to check for failed items, as these are not batched up in the job and transfers are unable to be created.

```
{
    "_links": {
        "self": {
            "href": "https://api-sandbox.dwolla.com/mass-payments/19244ef5-14ea-443e-83b9-aa8c01581b7d/items",
            "type": "application/vnd.dwolla.v1.hal+json",
            "resource-type": "mass-payment-item"
        },
        "first": {
            "href": "https://api-sandbox.dwolla.com/mass-payments/19244ef5-14ea-443e-83b9-aa8c01581b7d/items?&limit=25&offset=0",
            "type": "application/vnd.dwolla.v1.hal+json",
            "resource-type": "mass-payment-item"
        },
        "last": {
            "href": "https://api-sandbox.dwolla.com/mass-payments/19244ef5-14ea-443e-83b9-aa8c01581b7d/items?&limit=25&offset=0",
            "type": "application/vnd.dwolla.v1.hal+json",
            "resource-type": "mass-payment-item"
        }
    },
    "_embedded": {
        "items": [
            {
                "_links": {
                    "self": {
                        "href": "https://api-sandbox.dwolla.com/mass-payment-items/9710fbf1-ef5a-4d0e-b856-609407c82acb",
                        "type": "application/vnd.dwolla.v1.hal+json",
                        "resource-type": "mass-payment-item"
                    },
                    "mass-payment": {
                        "href": "https://api-sandbox.dwolla.com/mass-payments/19244ef5-14ea-443e-83b9-aa8c01581b7d",
                        "type": "application/vnd.dwolla.v1.hal+json",
                        "resource-type": "mass-payment"
                    },
                    "destination": {
                        "href": "https://api-sandbox.dwolla.com/customers/f6b35905-2885-43af-b3bc-5d66e5fc79d3",
                        "type": "application/vnd.dwolla.v1.hal+json",
                        "resource-type": "customer"
                    },
                    "transfer": {
                        "href": "https://api-sandbox.dwolla.com/transfers/c5bb6fa9-0ba8-e911-811a-9de799d3b148",
                        "type": "application/vnd.dwolla.v1.hal+json",
                        "resource-type": "transfer"
                    }
                },
                "id": "9710fbf1-ef5a-4d0e-b856-609407c82acb",
                "status": "success",
                "amount": {
                    "value": "101.01",
                    "currency": "USD"
                },
                "metadata": {
                    "itemId": "item1"
                }
            },
            {
                "_links": {
                    "self": {
                        "href": "https://api-sandbox.dwolla.com/mass-payment-items/498cd308-989d-4b0d-89fe-1e55bb93dd96",
                        "type": "application/vnd.dwolla.v1.hal+json",
                        "resource-type": "mass-payment-item"
                    },
                    "mass-payment": {
                        "href": "https://api-sandbox.dwolla.com/mass-payments/19244ef5-14ea-443e-83b9-aa8c01581b7d",
                        "type": "application/vnd.dwolla.v1.hal+json",
                        "resource-type": "mass-payment"
                    },
                    "destination": {
                        "href": "https://api-sandbox.dwolla.com/customers/dd0671cc-7622-40fe-87cf-cc9b212cc6c4",
                        "type": "application/vnd.dwolla.v1.hal+json",
                        "resource-type": "customer"
                    }
                },
                "_embedded": {
                    "errors": [
                        {
                            "code": "Restricted",
                            "message": "Receiver restricted.",
                            "path": "/items/destination/href",
                            "_links": {}
                        }
                    ]
                },
                "id": "498cd308-989d-4b0d-89fe-1e55bb93dd96",
                "status": "failed",
                "amount": {
                    "value": "202.02",
                    "currency": "USD"
                },
                "metadata": {
                    "itemId": "item2"
                }
            }
        ]
    },
    "total": 2
}
```

 

Looking at our example from the previous step, we can see that one of the Customers is restricted from receiving funds. If we investigate this specific Customer further, we could see that this Customer is in a deactivated status within Dwolla. You will want to create a procedure to reactivate Customers in order to get them into a good status.

ErrorCodes and Descriptions

ErrorCode Description How to Solution
insufficientFunds Mass Payments can be initiated from a bank or Dwolla Balance. A job initiated from a balance will not be created if there are insufficient funds to cover the Mass Payment job. Ensure your balance funding source has enough funds. You can load a Dwolla balance at any time.
invalid – receiver not found The destination was not a valid funding source. Review the fundingSourceId you specified in the API request and ensure it’s correct.
invalid – receiver cannot be the owner of the funding source The destination of the transfer cannot be the same as the source. Senders of a MassPayment job cannot receive funds to their own bank. Remove this fundingSourceId from the API request.
restricted The destination customer is either deactivated or suspended and is not eligible to receive funds. Customers in a restricted status must either be reactivated or unsuspended.

Once you have determined the error reason and solved the issue blocking them from initiating a transfer, you can create a new Mass Payment with these newly valid end users.

Step 5 – Track and Reconcile Individual Mass Payment Items

Ensuring that the right payments made it to the correct end user’s bank account is just as important as kicking off the payment itself. For this reason, Dwolla allows you to check each individual payment item by checking each individual transfer by its unique transferId.

Methods to track payment statuses

API – Developers can check the status of a transfer at any time via the API. Statuses include pending, processed or failed.

Webhooks – When an event occurs within the Dwolla API, a webhook will be sent to your webhook subscription to notify you of events. Rather than checking to see the status of a payment, Dwolla webhooks can tell you the status of a transfer immediately after it changes. This means that you get real-time insight into when a transfer clears to an end user’s bank account.

Methods to reconcile transfers

traceId –  A unique string value that identifies a transaction from the source funding source to the destination funding source. This value is often used to determine where a transaction’s funds lie at a certain time.

Check out our blog about traceId to learn more on how you can track where funds are at a given financial institution.

individualAchId – An identifier for that ACH entry. A unique string value matching the value on the bank line related to the transfer. Appears when the debit entry clears out of the bank.

Mass Payments Summary

Mass Payments can be a valuable tool in automating payouts to your end users. In five easy steps, you can not only send out thousands of payments, but you can easily build out the procedures to ensure that the individual items that fail to be created are flagged for review and further action.

As your business grows, ensuring that your own procedures are scalable is key to success. Paying out your own clients shouldn’t be a chore. Mass Payments with Dwolla can help.

Want to get started building your solution? Dive into our sandbox environment and test our ACH payouts API.

Stay Updated with Dwolla