Mass Payments - Pay 5,000 People in Five Simple Steps

Pay 5,000 People in Five Simple Steps

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 - Request 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"
    }
}

Step 2 - Let the Mass Payment Job to Complete

Once the Mass Payment job has been kicked off, Dwolla will parse through all the individual items you specified and determine if the item is valid. If it is determined that the item is valid, Dwolla will add it to the batch and kick off transfers for each one.

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
}

Step 4 - Determine Failed Item Reasons and Reinitiate Payment

Ensuring the right payments made it to the correct end user’s bank account is just as important as kicking off the payment itself. There may be cases where some individual items will not be kicked off.

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

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

2 Likes