Dwolla Developers Logo
Back
API Reference
  • SDK Support
    Drop-in Components
    Authorization
    Root
    Accounts
    Customers
    Knowledge-based Authentication (KBA)
    Beneficial Owners
    Documents
    Funding Sources
    Transfers
    Mass payments
    OverviewInitiate a mass paymentRetrieve a mass paymentUpdate a mass paymentList items for a mass paymentRetrieve a mass payment itemList mass payments for a customer
    Labels
    Events
    Webhook subscriptions
    Webhooks
CommunityOpen in new tabChangelog
Get API Keys
CommunityOpen in new tabChangelog
JavaScript
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 belowmetadatanoobjectA 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 belowcorrelationIdnostringA string value attached to a customer 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 TypeURIDescriptionFunding sourcehttps://api.dwolla.com/funding-sources/{id}A bank or balance funding source of an Account or verified Customer.
Destination types
Destination TypeURIDescriptionFunding 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 #

ParameterRequiredTypeDescriptionvalueyesstringAmount of moneycurrencyyesstringPossible 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.

Info
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.
ParameterRequiredTypeDescriptionsourcenostringRepresents 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
ParameterRequiredTypeDescriptionsourcenoobjectRepresents 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
ParameterRequiredTypeDescriptionaddendanoobjectAn 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 - _ . ~! * ' ( ) ; : @ & = + $ , / ? % # [ ]. Will not show up on bank statements from balance-sourced transfers.
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 StatusCodeDescription201CreatedA mass payment resource was created400ValidationErrorCan 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) #

JavaScript
// 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'

Test in the Sandbox for free today.

Use sandbox environment to test API requests.

Get API Keys
2022 All Rights Reserved

Dwolla

  • About
  • Blog
  • Pricing
  • Contact Sales
  • Terms of Service
  • Privacy Policy
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.