Cancelling Mass Payments

How are mass payments cancelled? The docs indicate a deferred mass payment can be cancelled by updating the status of the mass payment - Is there a “mass cancel” for processing mass payments or do you have to cancel all of the items individually? Is updating the items individually sufficient to cancel the mass payment or is there more to it? I couldn’t find anything in the docs besides cancelling a deferred mass payment.

Hi @jmtichell – on a high level once a masspayment is created in the Dwolla API, a job gets created in the queue which is picked up by a service that creates individual items off of the masspayment. The job starts running almost immediately, depending on the queue and the numbers of items in a masspayment. Essentially, there isn’t a way to cancel a masspayment as a whole once it get’s created, unless it’s created as a deferred masspayment like you mentioned.

As another alternative to cancelling individual transfers created from the masspayment, you could also listen to the webhook that gets sent for the creation of the debit portion of the masspayment and cancel it, which subsequently cancels the individual credit portions of the transfers. This discuss post by our team member is also a good read on masspayments in Dwolla - Mass Payments - Pay 5,000 People in Five Simple Steps

Hope that helps! Please let me know if you have any questions!

Thank you for sharing this. Just to confirm - the metadata/correlationID attribute this relies on is usable under the PAYG tier as well?

You’re welcome! Yes – this is supported under PAYG! :slight_smile:

Could you go into a little more detail on this? I’m not sure what you mean - is there somewhere in the docs that describe how to do this?

Sure, i can try to clarify further. Since masspays aren’t designed to be cancelled, this is more of a workaround which isn’t documented.

Essentially, when a masspayment is created and processed, there is a single debit transfer created for the total masspayment amount from the source bank. When this debit transfer is created, you’ll receive a webhook indicating the event customer_bank_transfer_created with the source Customer’s link in the payload. If you were to cancel this transfer, then the individual transfers outgoing to the multiple receivers would subsequently fail, or cancel.

Thank you @shreya. The one piece I"m still trying to work out is sending Operational Notifications after cancelling a Mass Payment - the only webhooks sent are each individual transfer cancelling, which would result in multiple emails being sent to the client if I fire off an email for each webhook - and none of which would be for the amount that the client would recognize (since the payment was broken down into transfers of a maximum of $5,000 each).

I’m going through the same mental gymnastics trying to figure out when transfers are successful as well. Do you have any suggestions on how to approach this?

You bet! :slight_smile:

As for sending a notification to your users, you can utilize the same customer_bank_transfer_created webhook sent for the debit portion of the masspayment which has the link to the source Customer to notify the Sender. This webhook contains the link to the single debit transfer for the total amount. As for notifying the receivers, they will all be individual transfers for which you’ll get individual webhooks.

As for following webhooks and the status of the transfer to figure out when a transfer finishes processing successfully, I’d recommend checking out this Gist - https://gist.github.com/spencerhunter/2ab064e8e76a049eb22e17ed8e92f350
It also ACH returns, late ACH returns, and the webhooks that are sent to notify about each, as well as the automatic actions Dwolla takes upon receiving these late returns.

Let me know if you come across any questions!

I circled back to this implementation now that I’m readying for production, and was wondering if some behavior in production would be different than the sandbox - particularly for getting the transfer urls from a masspayment. When I create the masspayment, will the transfer urls actually be available almost immediately or will this fail when I swap to production? I thought about using webhooks, but I don’t seem to be receiving a customer_transfer_created event when the mass payment is initiated (which I used to - is there an issue w/ webhooks currently)?

    transfer = app_token.post('mass-payments', request_body)
    transfer_url = transfer.headers['location']
    transfer = app_token.get(transfer_url)
    
    # Get the mass payment items, iterate through them to update the database with transfer urls
    items_url = transfer.body['_links']['items']['href']
    items = app_token.get(items_url)

    # Will this information in particular be available?
    for item in items.body['_embedded']['items']:
        mp_item = MassPayment_Transfer.objects.get(pk=item['metadata']['itemID'])
        transfer_item = app_token.get(item['_links']['self']['href'])
        mp_item.dwolla_transfer_url = transfer_item.body['_links']['cancel']['href']
        mp_item.save()

Also - do you have any idea why one of these transfers would fail to cancel and respond with this:

I submitted these 5 cancellation requests

https://api-sandbox.dwolla.com/transfers/4fbabd7f-ef2f-eb11-8129-d2ba35ae0f85
https://api-sandbox.dwolla.com/transfers/50babd7f-ef2f-eb11-8129-d2ba35ae0f85
https://api-sandbox.dwolla.com/transfers/51babd7f-ef2f-eb11-8129-d2ba35ae0f85
https://api-sandbox.dwolla.com/transfers/52babd7f-ef2f-eb11-8129-d2ba35ae0f85
https://api-sandbox.dwolla.com/transfers/53babd7f-ef2f-eb11-8129-d2ba35ae0f85

and this one failed:
https://api-sandbox.dwolla.com/transfers/51babd7f-ef2f-eb11-8129-d2ba35ae0f85

I submitted the request like below and the error I received follows. These items were in an array, and #1, 2,4, and 5 succeeded but I received this odd response for #3

request_body = {
            'status': 'cancelled'
        }
for item in transfer_to_cancel:
    item_transfer = app_token.post(item.transfer_url, request_body)

dwollav2.error.ValidationError: {"code":"ValidationError","message":"Validation error(s) present. See embedded errors list for more details.","_embedded":{"errors":[{"code":"NotAllowed","message":"Status not allowed.","path":"/status","_links":{}}]}}

I tried again through Postman - and was not able to cancel this particular transfer that way either, with the same error (the transfer is currently ‘pending’).