Dwolla.Client 7.0.0-alpha

This is a prerelease version of Dwolla.Client.
dotnet add package Dwolla.Client --version 7.0.0-alpha                
NuGet\Install-Package Dwolla.Client -Version 7.0.0-alpha                
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Dwolla.Client" Version="7.0.0-alpha" />                
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add Dwolla.Client --version 7.0.0-alpha                
#r "nuget: Dwolla.Client, 7.0.0-alpha"                
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install Dwolla.Client as a Cake Addin
#addin nuget:?package=Dwolla.Client&version=7.0.0-alpha&prerelease

// Install Dwolla.Client as a Cake Tool
#tool nuget:?package=Dwolla.Client&version=7.0.0-alpha&prerelease                

Dwolla SDK for C#

This repository contains the source code for Dwolla's C#-based SDK, which allows developers to interact with Dwolla's server-side API via a C# API. Any action that can be performed via an HTTP request can be made using this SDK when executed within a server-side environment.

Table of Contents

Getting Started

Installation

To begin using this SDK, you will first need to download it to your machine. We use NuGet to distribute this package. Check out the Microsoft documentation for more information on how to install and manage packages from Nuget using Visual Studio.

Here's an example using the Package Manager Console

$ Install-Package Dwolla.Client -Version 5.2.2

Initialization

Before any API requests can be made, you must first determine which environment you will be using, as well as fetch the application key and secret. To fetch your application key and secret, please visit one of the following links:

Finally, you can create an instance of DwollaClient by specifying which environment you will be using—Production or Sandbox—via the isSandbox boolean flag.

var client = DwollaClient.Create(isSandbox: true);
Tokens

Application access tokens are used to authenticate against the API on behalf of an application. Application tokens can be used to access resources in the API that either belong to the application itself (webhooks, events, webhook-subscriptions) or the Dwolla Account that owns the application (accounts, customers, funding-sources, etc.). Application tokens are obtained by using the client_credentials OAuth grant type:

var tokenRes = await client.PostAuthAsync<AppTokenRequest, TokenResponse>(
    new Uri($"{client.AuthBaseAddress}/token"),
    new AppTokenRequest {Key = "...", Secret = "..."});

Application access tokens are short-lived: 1 hour. They do not include a refresh_token. When it expires, generate a new one using AppTokenRequest.

Making Requests

You can make either low-level or high-level HTTP requests.

High-Level Requests

To make high-level HTTP requests you can use the HttpServices. The HttpServices allow you to make resource level requests with ease. You can either use the DwollaHttpService which will encapsulate all other resource HttpServices. Otherwise, you can simply use a single resource HttpService(e.g., CustomerHttpService).

Setting Access Token

The DwollaHttpService will use the AuthorizationHttpService in GetAccessTokenAsync() to retrieve and then cache the access token. If you use a single resource HttpService you will need to pass in a method to retrieve the access token.

Low-Level Requests

To make low-level HTTP requests, you can use the DwollaClient GetAsync(), PostAsync(), UploadAsync() and DeleteAsync() methods with the available request models. These methods will return responses that can be mapped to one of the available response models.

Setting Headers

To specify headers for a request (e.g., Authorization), you can pass a Headers object as the last argument.

var headers = new Headers {{"Authorization", $"Bearer {tokenRes.Content.Token}"}};
client.GetAsync<GetCustomersResponse>(url, headers);
GET
// GET api.dwolla.com/customers
var url = new Uri("https://api.dwolla.com/customers");
client.GetAsync<GetCustomersResponse>(url);
POST
// POST api.dwolla.com/customers
var url = new Uri("https://api.dwolla.com/customers/");
var request = new CreateCustomerRequest
{
  FirstName = "Jane",
  LastName = "Doe",
  Email = "jane.doe@email.com"
};
var res = await PostAsync<CreateCustomerRequest, EmptyResponse>(url, request, headers);
//res.Response.Headers.Location => "https://api-sandbox.dwolla.com/customers/fc451a7a-ae30-4404-aB95-e3553fcd733f

// POST api.dwolla.com/customers/{id}/documents multipart/form-data foo=...
var url = new Uri("https://api-sandbox.dwolla.com/customers/{id}/documents");
var request = new UploadDocumentRequest
{
    DocumentType = "idCard",
    Document = new File
    {
        ContentType = "image/png",
        Filename = "filename.jpg",
        Stream = fileStream
    }
};
client.UploadAsync<UploadDocumentRequest, EmptyResponse>(url, request, headers);
DELETE
// DELETE api.dwolla.com/resource
var url = "https://api.dwolla.com/labels/{id}"
client.DeleteAsync<object>(url, null);

Example App

Take a look at the Example Application for examples on how to use the available C# models to call the Dwolla API. Before you can begin using the app, however, you will need to specify a DWOLLA_APP_KEY and DWOLLA_APP_SECRET environment variable.

Docker

If you prefer to use Docker to run ExampleApp locally, a Dockerfile file is included in the root directory. You can either build the Docker image with your API key and secret (by passing the values via CLI), or you can specify the values for the app_key and app_secret build arguments in Dockerfile. Finally, you will need to build and run the Docker image. More information on this topic can be found on Docker's website, or you can find some example commands below.

Building Docker Container
# Building container by specifying build arguments.
# In this configuration, you will not need to modify Dockerfile. All of the
# necessary arguments are passed via Docker's `--build-arg` option.
$ docker build \
    --build-arg app_key=YOUR_API_KEY \
    --build-arg app_secret=YOUR_APP_SECRET \
    -t dwolla/csharp-example-app:latest .

# Building container without specifying build arguments.
# In this configuration, you will need to specify your account API key and
# secret (retrieved from Dwolla) in the Dockerfile file.
$ docker build -t dwolla/csharp-example-app:latest .
Running Container Instance
# Running Docker container in interactive shell
$ docker run --init -it dwolla/csharp-example-app:latest

Changelog

  • 7.0.0-alpha
    • Alpha pre-release introducing high-level HTTP requests with HttpServices, encapsulating resource-level requests.
    • Special thanks to @isaiah-eventlink and @miccav-eventlink for their contributions in adding HTTP services for high-level methods! 🎉
  • 6.0.0
    • Fix issue #41 reported by, @waynebrantley
      • Upgrade the target framework to netstandard2.0 in line with Microsoft's recommendation to avoid targeting netstandard1.x. Users of the SDK will need to update their applications to target netstandard2.0 or a later version to use the updated SDK.
      • Replace Newtonsoft.Json with System.Text.Json to remove external dependencies.
    • Configure static HttpClient in DwollaClient to adhere to Microsoft's HttpClient guidelines for .NET.
    • Special thanks to @natehitz and @IsaiahDahlberg for their contributions to this release! 🙌
  • 5.4.0
    • Fix issue with deserialization of 200 Ok response with an _embedded error on GET customer. Issue #47. (Thanks, @dahlbyk!)
    • Add missing fields to Customer response schema - Embedded, CorrelationID, BusinessType, BusinessClassification.
  • 5.3.0
    • Add API models and examples for Exchanges
    • Add Trace ID under AchDetails object
  • 5.2.2 Update Newtonsoft.Json to version 13.0.1
  • 5.2.1 Add Masspayment models and examples, support RTP transfers
  • 5.2.0 Change Token URLs and Add Labels models and examples
  • 5.1.1 Update Content-Type and Accept headers for Token URLs
  • 5.1.0 Change Token URLs
  • 5.0.16 Add missing using to ExampleApp
  • 5.0.15 Upgrade dependencies and Dwolla.Client.Tests and ExampleApp to netcoreapp2.0. Breaking changes:
    • DwollaClient no longer throws on API errors, they should be properly deserialized into RestResponse.Error instead
    • DwollaException, RestException, and RestResponse.Exception are removed
    • Use EmptyResponse instead of object in DwollaClient inteface
  • 4.0.14 Ignore null values in JSON POST requests
  • 4.0.13 Add Beneficial Owner models and examples
  • 4.0.12 Add Controller models
  • 4.0.11 Add document failure reason
  • 4.0.10 Add Micro Deposit models
  • 4.0.9 Add Document models, support transfer fees
  • 4.0.8 Add Transfer models, expose raw response on RestResponse
  • 4.0.7 Add Micro Deposit and Balance models
  • 4.0.6 Breaking change: Remove CreateCustomerRequest.Status. Add UpdateCustomerRequest
  • 3.0.5 Breaking change: CreateCustomerRequest.DateOfBirth stringDateTime?. Create base responses, refactor ExampleApp to tasks, add Funding Source models
  • 2.0.4 Add Webhook Subscription models
  • 2.0.3 Breaking change: CustomerEmbed → CustomersEmbed. Thanks to @ithielnor for adding Business Classification models and a CLI
  • 1.0.2 Lower VisualStudioVersion, add more properties to Customer
  • 1.0.1 Include deserialized error in DwollaException
  • 1.0.0 Initial release

Community

Additional Resources

To learn more about Dwolla and how to integrate our product with your application, please consider visiting the following resources and becoming a member of our community!

Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 is compatible.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
.NET Core netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.0 is compatible.  netstandard2.1 was computed. 
.NET Framework net461 was computed.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 was computed.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen40 was computed.  tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
7.0.0-alpha 106 8/15/2024
6.0.0 11,868 3/22/2023
5.4.0 5,011 1/31/2023
5.2.2 16,869 7/13/2022
5.2.1 19,326 5/4/2022
5.1.1 62,385 12/27/2018
5.0.16 2,331 5/30/2018
5.0.15 1,574 5/30/2018
4.0.14 1,583 5/30/2018
4.0.13 1,593 5/9/2018
4.0.12 1,545 5/8/2018
4.0.11 1,692 1/19/2018
4.0.10 1,642 1/4/2018
4.0.9 1,589 12/13/2017
4.0.8 1,493 11/30/2017
4.0.7 1,437 11/10/2017
4.0.6 1,482 11/9/2017
3.0.5 1,482 11/6/2017
2.0.4 1,443 11/2/2017
2.0.3 1,462 10/23/2017
1.0.2 1,479 10/20/2017
1.0.1 2,052 7/3/2017
1.0.0 1,602 7/1/2017