Initiate a mass payment #

This section covers how to initiate a mass payment from your Dwolla Master Account or Verified Customer resource. A mass payment contains a list of items representing individual payments. Optionally, mass payments can contain metadata and a correlationId on the mass payment itself as well as items contained in the mass payment, which can be used to pass along additional information with the mass payment and item respectively. If a correlationId is included on a mass payment item it will be passed along to the transfer created from the item and can be searched on.

Prevent duplicate mass payment with idempotency key #

To prevent an operation from being performed more than once, Dwolla supports passing in an Idempotency-Key header with a unique key as the value. Multiple POSTs with the same idempotency key won't result in multiple resources being created.

For example, if a request to initiate a mass payment fails due to a network connection issue, you can reattempt the request with the same idempotency key to ensure that only a single mass payment is created.

Refer to our idempotency key section to learn more.

Deferred mass payment #

A mass payment can be created with a status of deferred, which allows you to create the mass payment and defer processing to a later time. To trigger processing on a deferred mass payment, you'll update the mass payment with a status of pending. A deferred mass payment can be cancelled by updating the mass payment with a status of cancelled.

HTTP request #

POST https://api.dwolla.com/mass-payments

Request parameters #

Source and destination values #

Source types

Destination types

Mass payment item #

amount JSON object #

clearing JSON object (mass payment) #

The clearing object is used in tandem with our expedited transfers feature. This object does not need to be included if not using expedited transfers. Source specifies the processing time for the source bank funding source involved in the transfer, and can be used to downgrade the processing time from the default of Next-day ACH or to upgrade it to Same-day ACH on the debit portion of the mass payment into the Dwolla Network. Destination specifies the processing time for the destination funding source involved in the transfer, and can be used to upgrade the processing time from the default of Standard ACH to Same-day ACH on each mass payment item.

The clearing request parameter is a premium feature available for Dwolla customers in the Scale pricing tier. Enabling Next-day ACH and Same-day ACH requires additional Dwolla approvals before getting started. Please contact sales or your account manager for more information on enabling this feature.

Clearing example:

Same-day debit

"clearing": {
  "source": "next-available"
}

Standard debit (if Next-day is enabled)

"clearing": {
  "source": "standard"
}

achDetails and addenda object #

The addendum record is used to provide additional information to the payment recipient about the payment. This value will be passed in on a transfer request and can be exposed on a customer’s bank statement. Addenda records provide a unique opportunity to supply your customers with more information about their transactions. Allowing businesses to include additional details about the transaction—such as invoice numbers—provides their end users with more information about the transaction in the comfort of their own banking application.

achDetails object

addenda object

Source mass payment achDetails with addenda example:

"achDetails": {
  "source": {
    "addenda": {
      "values": ["ABC123_AddendaValue"]
    }
  }
},

Destination mass payment item with achDetails and addenda example

"achDetails": {
  "destination": {
    "addenda": {
      "values": ["ZYX987_AddendaValue"]
    }
  }
}

HTTP status and error codes #

Request and response (mass payment from Account to Customers) #

// Using dwolla-v2 - https://github.com/Dwolla/dwolla-v2-node
var requestBody = {
  _links: {
    source: {
      href: "https://api-sandbox.dwolla.com/funding-sources/707177c3-bf15-4e7e-b37c-55c3898d9bf4",
    },
  },
  achDetails: {
    source: {
      addenda: {
        values: ["ABC123_AddendaValue"],
      },
    },
  },
  clearing: {
    source: "standard",
  },
  items: [
    {
      _links: {
        destination: {
          href: "https://api-sandbox.dwolla.com/funding-sources/9c7f8d57-cd45-4e7a-bf7a-914dbd6131db",
        },
      },
      amount: {
        currency: "USD",
        value: "1.00",
      },
      clearing: {
        destination: "next-available",
      },
      metadata: {
        payment1: "payment1",
      },
      correlationId: "ad6ca82d-59f7-45f0-a8d2-94c2cd4e8841",
      achDetails: {
        destination: {
          addenda: {
            values: ["ABC123_AddendaValue"],
          },
        },
      },
      processingChannel: {
        destination: "real-time-payments",
      },
    },
    {
      _links: {
        destination: {
          href: "https://api-sandbox.dwolla.com/funding-sources/b442c936-1f87-465d-a4e2-a982164b26bd",
        },
      },
      amount: {
        currency: "USD",
        value: "5.00",
      },
      clearing: {
        destination: "next-available",
      },
      metadata: {
        payment2: "payment2",
      },
      achDetails: {
        destination: {
          addenda: {
            values: ["ABC123_AddendaValue"],
          },
        },
      },
    },
  ],
  metadata: {
    batch1: "batch1",
  },
  correlationId: "6d127333-69e9-4c2b-8cae-df850228e130",
};

dwolla
  .post("mass-payments", requestBody)
  .then((res) => res.headers.get("location")); // => 'https://api-sandbox.dwolla.com/mass-payments/cf1e9e00-09cf-43da-b8b5-a43b3f6192d4'