Initiate a mass payment

Create a mass payment containing up to 5,000 individual payment items from a Dwolla Main Account or Verified Customer funding source. Supports optional metadata, correlation IDs for traceability, deferred processing, and expedited transfer options including same-day ACH clearing. Returns the location of the created mass payment resource with a unique identifier for tracking and management.

POST /mass-payments

cURL

cURL

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": "instant"
        }
      },
      {
        "_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"
}

// 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: "instant",
      },
    },
    {
      _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'

# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
request_body = {
  '_links': {
    'source': {
      'href': 'https://api-sandbox.dwolla.com/funding-sources/707177c3-bf15-4e7e-b37c-55c3898d9bf4'
    }
  },
  'achDetails': {
    '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': {
        'addenda': {
          'values': ['ABC123_AddendaValue']
        }
      },
      'processingChannel': {
        'destination': 'instant'
      }
    },
    {
      '_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': {
        'addenda': {
          'values': ['ABC123_AddendaValue']
        }
      }
    }
  ],
  'metadata': {
    'batch1': 'batch1'
  },
  'correlationId': '6d127333-69e9-4c2b-8cae-df850228e130'
}

mass_payment = app_token.post('mass-payments', request_body)
mass_payment.headers['location'] # => 'https://api-sandbox.dwolla.com/mass-payments/cf1e9e00-09cf-43da-b8b5-a43b3f6192d4'

<?php
// Using dwollaswagger - https://github.com/Dwolla/dwolla-swagger-php
$massPaymentsApi = new DwollaSwagger\MasspaymentsApi($apiClient);

$massPayment = $massPaymentsApi->create([
  '_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' =>
      [
        'source' => [
          'addenda' => [
            'values' => ['ABC123_AddendaValue']
          ]
        ]
      ],
      'processingChannel' => [
        'destination' => 'instant'
      ]
    ],
    [
      '_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' =>
      [
        'source' => [
          'addenda' => [
            'values' => ['ABC123_AddendaValue']
          ]
        ]
      ]
    ],
  ],
  'metadata' =>
  [
    'batch1' => 'batch1',
  ],
  'correlationId' => '6d127333-69e9-4c2b-8cae-df850228e130',
]);
$massPayment; # => "https://api-sandbox.dwolla.com/mass-payments/cf1e9e00-09cf-43da-b8b5-a43b3f6192d4"
?>

# Using dwolla_v2 - https://github.com/Dwolla/dwolla-v2-ruby
request_body = {
  :_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 => "instant"
      }
    },
    {
      :_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"
}

mass_payment = app_token.post "mass-payments", request_body
mass_payment.response_headers[:location] # => "https://api-sandbox.dwolla.com/mass-payments/cf1e9e00-09cf-43da-b8b5-a43b3f6192d4"

400

{
  "code": "BadRequest",
  "message": "The request body contains bad syntax or is incomplete."
}

{
  "code": "Forbidden",
  "message": "Not authorized to create mass payment"
}

Authorizations

Authorization · string · header · required

The access token received from the authorization server in the OAuth 2.0 flow.

Headers

Accept · enum<string> · default: application/vnd.dwolla.v1.hal+json · required

The media type of the response. Must be application/vnd.dwolla.v1.hal+json

Available options: application/vnd.dwolla.v1.hal+json

Idempotency-Key · string

Body

application/json

Parameters for initiating a mass payment

_links · object · required

Show child attributes

items · object[] · required

Show child attributes

status · string

Example:

"deferred"

achDetails · object

Show child attributes

clearing · object

Show child attributes

metadata · object

correlationId · string

Example:

"ad6ca82d-59f7-45f0-a8d2-94c2cd4e8841"

Response

201

created