> ## Documentation Index > Fetch the complete documentation index at: https://developers.dwolla.com/llms.txt > Use this file to discover all available pages before exploring further. # 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. ## OpenAPI ````yaml post /mass-payments openapi: 3.1.0 info: title: Dwolla API description: Dwolla API Documentation contact: name: Dwolla Developer Relations Team url: https://developers.dwolla.com email: api@dwolla.com version: '2.0' termsOfService: https://www.dwolla.com/legal/tos/ license: name: MIT url: https://github.com/Dwolla/dwolla-openapi/blob/master/LICENSE servers: - url: https://api.dwolla.com description: Production server - url: https://api-sandbox.dwolla.com description: Sandbox server security: - clientCredentials: [] tags: - name: tokens description: Operations related to Application Access Tokens - name: root description: Root API operations - name: accounts description: Operations related to Accounts - name: customers description: Operations related to Customers - name: kba description: Operations related to Knowledge-Based Authentication - name: beneficial owners description: Operations related to Beneficial Owners - name: documents description: Operations related to Documents - name: exchanges description: Operations related to Exchanges - name: exchange sessions description: Operations related to Exchange Sessions - name: funding sources description: Operations related to Funding Sources - name: transfers description: Operations related to Transfers - name: labels description: Operations related to Labels - name: mass payments description: Operations related to Mass Payments - name: events description: Operations related to Events - name: webhook subscriptions description: Operations related to Webhook Subscriptions - name: webhooks description: Operations related to Webhooks - name: client tokens description: Operations related to Client Tokens - name: sandbox simulations description: Sandbox-only operations for simulating processing of bank transfers paths: /mass-payments: post: tags: - mass payments summary: Initiate a mass payment description: >- 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. operationId: initiateMassPayment parameters: - $ref: '#/components/parameters/Accept' - name: Idempotency-Key schema: type: string in: header example: 19051a62-3403-11e6-ac61-9e71128cae77 requestBody: required: true description: Parameters for initiating a mass payment content: application/json: schema: required: - _links - items type: object properties: _links: type: object properties: source: type: object properties: href: type: string example: >- https://api.dwolla.com/funding-sources/707177c3-bf15-4e7e-b37c-55c3898d9bf4 items: type: array items: type: object properties: _links: type: object properties: destination: type: object properties: href: type: string example: >- https://api.dwolla.com/funding-sources/9c7f8d57-cd45-4e7a-bf7a-914dbd6131db amount: $ref: '#/components/schemas/TransferAmount' processingChannel: type: object properties: destination: type: string example: real-time-payments metadata: type: object clearing: type: object properties: destination: type: string example: next-available achDetails: type: object properties: destination: type: object properties: addenda: type: object properties: values: type: array items: type: string example: XYZ987_AddendaValue correlationId: type: string example: ad6ca82d-59f7-45f0-a8d2-94c2cd4e8841 status: type: string example: deferred achDetails: type: object properties: source: type: object properties: addenda: type: object properties: values: type: array items: type: string example: ZYX987_AddendaValue clearing: type: object properties: source: type: string example: next-available metadata: type: object correlationId: type: string example: ad6ca82d-59f7-45f0-a8d2-94c2cd4e8841 responses: '201': description: created headers: Location: $ref: '#/components/headers/Location' '400': description: Bad Request headers: {} content: application/vnd.dwolla.v1.hal+json: schema: $ref: '#/components/schemas/BadRequestError' '403': description: Forbidden headers: {} content: application/vnd.dwolla.v1.hal+json: schema: type: object properties: code: type: string example: Forbidden message: type: string example: Not authorized to create mass payment x-codeSamples: - lang: bash source: > 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" } - lang: javascript source: | // 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' - lang: python source: > # 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' - lang: php source: > 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" ?> - lang: ruby source: > # 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" components: parameters: Accept: name: Accept in: header required: true description: >- The media type of the response. Must be application/vnd.dwolla.v1.hal+json schema: type: string enum: - application/vnd.dwolla.v1.hal+json default: application/vnd.dwolla.v1.hal+json schemas: TransferAmount: title: TransferAmount type: object required: - value - currency properties: value: type: string example: '5.00' currency: type: string example: USD BadRequestError: title: BadRequestError description: Error response schema for 400 Bad Request type: object required: - code - message properties: code: type: string example: BadRequest message: type: string example: The request body contains bad syntax or is incomplete. headers: Location: description: The location of the created resource schema: type: string securitySchemes: clientCredentials: type: oauth2 flows: clientCredentials: tokenUrl: /token x-speakeasy-token-endpoint-authentication: client_secret_basic scopes: {} ````