Docs
Get API Keys

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 #

ParameterRequiredTypeDescription
_linksyesobjectA _links JSON object describing the desired source of a mass payment. Reference the Source and Destination object to learn more about possible values for source and destination.
itemsyesarrayan array of item JSON objects that contain unique payments. See below
metadatanoobjectA metadata JSON object with a maximum of 10 key-value pairs (each key and value must be less than 255 characters).
statusnostringAcceptable value is: deferred.
clearingnoobjectA clearing JSON object describing the desired 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.
achDetailsnoobjectAn ACH details JSON object which represents additional information sent along with a transfer created from a mass payment item to an originating or receiving financial institution. Details within this object can be used to reference a transaction that has settled with a financial institution. See below
correlationIdnostringA string value attached to a mass payment resource which can be used for traceability between Dwolla and your application. Note: A correlationId is not a replacement for an idempotency key.
Must be less than or equal to 255 characters and contain no spaces.
Acceptable characters are: a-Z, 0-9, -, ., and _.
Note: Sensitive Personal Identifying Information (PII) should not be used in this field and it is recommended to use a random value for correlationId, like a UUID.

Source and destination values #

Source types
Source TypeURIDescription
Funding sourcehttps://api.dwolla.com/funding-sources/{id}A bank or balance funding source of an Account or verified Customer.
Destination types
Destination TypeURIDescription
Funding sourcehttps://api.dwolla.com/funding-sources/{id}Destination of a Verified Customer's own bank or balance funding source, an Unverified Customer's bank funding source, or a Receive-only User's bank funding source.

Mass payment item #

ParameterRequiredTypeDescription
_linksyesobjectA _links JSON object describing the desired destination of a mass payment. See above for possible values for destination.
amountyesobjectAn amount JSON object containing currency and value keys.
metadatanoobjectA metadata JSON object with a maximum of 10 key-value pairs (each key and value must be less than 255 characters).
clearingnoobjectA clearing JSON object that contains destination key to expedite a transfer. Reference the clearing JSON object to learn more.
correlationIdnostringA string value attached to a mass payment item which can be used for traceability between Dwolla and your application. The correlationId will be passed along to a transfer that is created from an item and can be searched on. Must be less than or equal to 255 characters and contain no spaces. Acceptable characters are: a-Z, 0-9, -, ., and _.
achDetailsnoobjectAn ACH details JSON object which represents additional information sent along with a transfer created from a mass payment item to an originating or receiving financial institution. Details within this object can be used to reference a transaction that has settled with a financial institution.
processingChannelnoobjectA processingChannel JSON object that contains a key-value pair with a string key and string value of destination and real-time-payments.

amount JSON object #

ParameterRequiredTypeDescription
valueyesstringAmount of money
currencyyesstringPossible values: USD

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.

ParameterRequiredTypeDescription
sourcenostringRepresents a clearing object for debits into the Dwolla network.
Possible values: 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.
Note: Cannot be used on individual mass payment items as items represent a destination for the funds transfer. See example masspayment request.
destinationnostringRepresents a clearing object for credits out of the Dwolla network to a bank funding source.
Possible values: next-available
next-available - Used to upgrade the clearing time of credits to Same-day ACH.
Note: Can only be used on individual mass payment items. See [example masspayment request](https://developers.dwolla.com/api-reference/mass-payments/initiate#request-and-response-mass-payment-from-account-to-customers

Clearing example:

Same-day debit
bash
"clearing": {
  "source": "next-available"
}
Standard debit (if Next-day is enabled)
bash
"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
ParameterRequiredTypeDescription
sourcenoobjectRepresents information that is sent to a source/originating bank account along with a transfer. Include information within this JSON object for customizing details on ACH debit transfers. Can include an addenda JSON object.
destinationnoobjectRepresents information that is sent to a destination/receiving bank account along with a transfer from a mass payment item. Include information within this JSON object for customizing details on ACH credit transfers. Can include an addenda JSON object.
addenda object
ParameterRequiredTypeDescription
addendanoobjectAn addenda object contains a 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 - _ . ~! * ' ( ) ; : @ & = + $ , / ? % # [ ].
Source mass payment achDetails with addenda example:
bash
"achDetails": {
  "source": {
    "addenda": {
      "values": ["ABC123_AddendaValue"]
    }
  }
},
Destination mass payment item with achDetails and addenda example
bash
"achDetails": {
  "destination": {
    "addenda": {
      "values": ["ZYX987_AddendaValue"]
    }
  }
}

HTTP status and error codes #

HTTP StatusCodeDescription
201CreatedA mass payment resource was created
400ValidationErrorCan be: Items exceeded maximum count of 5000, Invalid amount, Invalid metadata, Invalid job item correlation ID, or Invalid funding source.
401NotAuthorizedOAuth token does not have Send scope.

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

Raw
POST https://api-sandbox.dwolla.com/mass-payments
Accept: application/vnd.dwolla.v1.hal+json
Content-Type: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY
Idempotency-Key: 19051a62-3403-11e6-ac61-9e71128cae77

{
    "_links": {
        "source": {
            "href": "https://api-sandbox.dwolla.com/funding-sources/707177c3-bf15-4e7e-b37c-55c3898d9bf4"
        }
    },
    "achDetails": {
      "source": {
        "addenda": {
          "values": ["ABC123_AddendaValue"]
        }
      }
    },
    "clearing": {
      "source": "next-available"
    },
    "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"
        },
        "achDetails": {
          "destination": {
            "addenda": {
              "values": ["ZYX987_AddendaValue"]
            }
          }
        },
        "correlationId": "ad6ca82d-59f7-45f0-a8d2-94c2cd4e8841",
        "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": ["ZYX987_AddendaValue"]
              }
            }
        }
      }
    ],
    "metadata": {
        "batch1": "batch1"
    },
    "correlationId": "6d127333-69e9-4c2b-8cae-df850228e130"
}

...

HTTP/1.1 201 Created
Location: https://api-sandbox.dwolla.com/mass-payments/d093bcd1-d0c1-41c2-bcb5-a5cc011be0b7
Test in the Sandbox for free today.
Use sandbox environment to test API requests.
Get API Keys
2024 All Rights Reserved
Financial institutions play an important role in our network.

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.