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.
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.
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
.
POST https://api.dwolla.com/mass-payments
source
of a mass payment. Reference the Source and Destination object to learn more about possible values for source
and destination
.deferred
.source
processing time. Utilize this parameter for bank sourced mass payments that you wish to configure the proccessing time for the ACH debit to Same-day ACH, or from Next-day ACH to standard ACH . Reference the clearing JSON object to learn more.a-Z
, 0-9
, -
, .
, and _
. https://api.dwolla.com/funding-sources/{id}
https://api.dwolla.com/funding-sources/{id}
bank
or balance
funding source, an Unverified Customer's bank
funding source, or a Receive-only User's bank
funding source.destination
of a mass payment. See above for possible values for destination
.currency
and value
keys.destination
key to expedite a transfer. Reference the clearing JSON object to learn more.a-Z
, 0-9
, -
, .
, and _
.destination
and real-time-payments
.USD
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.
standard
, next-available
standard
- Used to downgrade the clearing time of debits from the default of Next-day ACH (if enabled) to Standard ACH. next-available
- Used to upgrade the clearing time of debits to Same-day ACH. next-available
next-available
- Used to upgrade the clearing time of credits to Same-day ACH. "clearing": {
"source": "next-available"
}
"clearing": {
"source": "standard"
}
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.
values
key which is an array of comma separated string addenda values. Addenda record information is used for the purpose of transmitting transfer-related information. Values must be less than or equal to 80 characters and can include spaces. Acceptable characters are: a-Z, 0-9, and special characters - _ . ~! * ' ( ) ; : @ & = + $ , / ? % # [ ]
. Will not show up on bank statements from balance-sourced transfers."achDetails": {
"source": {
"addenda": {
"values": ["ABC123_AddendaValue"]
}
}
},
"achDetails": {
"destination": {
"addenda": {
"values": ["ZYX987_AddendaValue"]
}
}
}
// 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'
Use sandbox environment to test API requests.
All funds transfers made using the Dwolla Platform are performed by a financial institution partner, and any funds held in a Dwolla Balance are held by a financial institution partner. Learn more about our financial institution partners.