Other notable changes
Webhooks - v1 vs. the Dwolla v2 API
- Webhook payload differences - One of the biggest differences in webhooks sent in v1 vs. the Dwolla v2 API is the type of data included in the webhook payload.
- In v1, the JSON payload includes detailed information on the resource that caused the webhook to be sent. For example, a TransactionStatus webhook would include the entire Transaction Resource with information such as Transaction Id, SourceName, DestinationName, Type, Fees, etc.
- In the Dwolla v2 API, each webhook sent by Dwolla contains an Event object with an event topic (e.g. transfer_created) and _links to: the associated resource, account associated with the event, and the customer associated with the event (if applicable). Your application will then follow a link to the resource contained in the event to lookup additional information.
- Subscribing a webhook URL
- Failed webhook attempts and retries
- In v1, webhook notifications were only sent once—regardless of whether or not your server responded to the request from Dwolla.
- In the Dwolla v2 API, if your server doesn’t acknowledge the webhook request from Dwolla with a 2xx level status code, then the request will be retried on an exponential backoff schedule. Reference the API docs for more information on acknowledgement and retries.
- Authenticating webhooks - To ensure that the requests are coming from a valid source, Dwolla signs webhook requests so that you can verify that any requests you receive are generated by Dwolla and not someone pretending to be Dwolla.
- Webhook requests in v1 included a X-Dwolla-Signature header, which is an SHA-1 HMAC hash of the request body salted using the consumer application secret.
- In the Dwolla v2 API, a X-Request-Signature-Sha-256 header is included which is a SHA256 HMAC hash of the request body with the key being your webhook secret. Reference our webhooks guide for more information on validating webhook requests.
Transactions - How transactions work
- Transaction Ids
- In v1, when a payment is sent, two or more transactions are created. At least one is created to credit the recipient’s account, and another one to debit the sender’s account. As a simple example, let’s say Bob sends $5 to Alice from his account balance. From this action, two Transactions are created: Transaction 512010: credits Alice’s account with $5. Transaction 512011: deducts $5 from Bob’s account. It’s important to keep in mind that when Bob looks at this payment, he will see the credit transaction’s ID: 512010. This is called the Sender’s Transaction ID. Similarly, when Alice looks up this payment, she will see a different transaction of ID 512011, which we call the Recipient’s Transaction ID.
- In the Dwolla v2 API, we’ve reduced the number of unique Ids returned on a payment from two transaction Ids to a single transfer Id.
- How transactions are displayed in dwolla.com and emails - Since unique transaction Ids are different in the Dwolla v2 API they will not match Ids that are displayed in the legacy dashboard at https://www.dwolla.com or within Dwolla emails. A new dashboard will be released which displays Dwolla v2 API Ids that can be used to reconcile against transfers created in the API.
- Fees must be specified via the API on a per request basis
- By default, fees are sent to the account of the application owner
- Only flat fees can be specified, not a percentage on the amount of the transfer
Financial institutions play an important role in the Dwolla network.
Dwolla, Inc. is an agent of Veridian Credit Union and Compass Bank and all funds associated with your account in the Dwolla network are held in pooled accounts at Veridian Credit Union and Compass Bank. These funds are not eligible for individual insurance, including FDIC insurance and may not be eligible for share insurance by the National Credit Union Share Insurance Fund. Dwolla, Inc. is the operator of a software platform that communicates user instructions for funds transfers to Veridian Credit Union and Compass Bank.