[API v2] Idempotency-Key - Safely initiate duplicate requests

(Spencer Hunter) #1

After receiving feedback from various API consumers on what to do in the event of a network connection issue when calling the Dwolla API to create a resource, we have come up with a solution that involves passing a unique idempotency key on requests.

As of Friday June 17, 2016, we released support for an optional Idempotency-Key header on requests to the API.

As mentioned in the developer documentation if, for example, a request to initiate a transfer fails due to a request timing out calling the Dwolla API. In this instance the request may have succeeded on Dwolla’s end, but your application just simply didn’t get a “success” response back from the Dwolla server. By passing in an idempotency key you can safely re-attempt the request with the same idempotency key to guarantee that only a single transfer is created. If you re-attempt a POST request with the same value for the idempotency key, you will receive the original response. The idempotency key will expire after 24 hours.


POST https://api-uat.dwolla.com/transfers
Content-Type: application/vnd.dwolla.v1.hal+json
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY
Idempotency-Key: d2adcbab-4e4e-430b-9181-ac9346be723a

    "_links": {
        "source": {
            "href": "http://api-uat.dwolla.com/funding-sources/707177c3-bf15-4e7e-b37c-55c3898d9bf4"
        "destination": {
            "href": "https://api-uat.dwolla.com/customers/d795f696-2cac-4662-8f16-95f1db9bddd8"
    "amount": {
        "currency": "USD",
        "value": "22.00"

We highly recommend using the Idempotency-Key header on endpoints that involve movement of money to prevent accidental duplicate payments from being submitted.

We have added support to our Node.js, Python, and Ruby SDKs and are working on adding support for swagger generated SDKs like PHP. Please don’t hesitate to reach out if you have any questions on leveraging this functionality within your application!