This project is now obsolete. Please use the offical Dwolla C# Client here: https://github.com/Dwolla/dwolla-v2-csharp
A .NET implementation for the Dwolla Checkout (off-site gateway) API.
- .NET 4.0
via Nuget Dwolla.Checkout
Install-Package Dwolla.Checkout
- Download the source code.
- Run
build.bat.
Upon successful build, the results will be in the \__package directory.
Dwolla allows two methods to initiate payment from a customer (off-site, without using OAuth).
- Initiate Payments by HTML Form Post.
- Initiate Payments by Server-to-Server Communication.
Implementers usually choose a single method to initiate payments depending on your development scenario.
Both methods provide an option to configure a Callback URL. The Callback URL is a location on your server where Dwolla will post a JSON object that describes the success or failure of a payment after the user has completed the checkout process.
When using the HTML Form method, use the DwollaSignatureUtil.GenerateSignature() to generate a signature for the form submission. Dwolla uses the form's signature value to verify the authenticity of the form submission.
<form accept-charset="UTF-8" action="https://www.dwolla.com/payment/pay" method="post">
<input id="key" name="key" type="hidden" value="myAppKey" />
<input id="signature" name="signature" type="hidden"
value="<%= DwollaSignatureUtil.GenerateSignature("appKey", "appSecret",
orderId:"188375",
DateTime.UtcNow); %>" />
<input id="callback" name="callback" type="hidden"
value="http://www.example.com/callback" />
<input id="redirect" name="redirect" type="hidden"
value="http://www.example.com/redirect" />
<input id="test" name="test" type="hidden" value="true" />
<input id="name" name="name" type="hidden" value="Purchase" />
<input id="description" name="description" type="hidden" value="Description" />
<input id="destinationid" name="destinationid" type="hidden" value="812-111-1111" />
<input id="amount" name="amount" type="hidden" value="1.00" />
<input id="shipping" name="shipping" type="hidden" value="0.00" />
<input id="tax" name="tax" type="hidden" value="0.00" />
<input id="orderid" name="orderid" type="hidden" value="188375" />
<input id="timestamp" name="timestamp" type="hidden" value="1323302400" />
<button type="submit">Submit Order</button>
</form>The general process of communicating with Dwolla in a Server-to-Server Checkout process involves:
- Creating a
DwollaCheckoutRequest. - Sending the
DwollaCheckoutRequestto Dwolla. - Parse the
DwollaCheckoutResponseand deal with any errors. - Use the
DwollaCheckoutResponseto generate a Redirect URL for the customer's browser to complete the checkout process.
var api = new DwollaServerCheckoutApi( appKey:"...", appSecret: "..." );
//Create a checkout request
var checkoutRequest = new DwollaCheckoutRequest
{
OrderId = "MyOrderTest",
Callback = new Uri("http://www.example.com/order-callback")
PurchaseOrder = new DwollaPurchaseOrder
{
DestinationId = "812-111-1111",
OrderItems = {
new DwollaOrderItem( name: "Candy Bar", price: 25.00m, quantity: 1 )
{
Description = "Expensive Candy Bar",
}
},
},
};
//Send the request to Dwolla.
var checkoutResponse = api.SendCheckoutRequest( checkoutRequest );
if( checkoutResponse.Result == DwollaCheckoutResponseResult.Failure )
{
//Handle Error
}
else if( checkoutResponse.Result == DwollaCheckoutResponseResult.Success)
{
var redirectUrl = checkoutResponse.GetRedirectUrl();
//Send HTTP Redirect to browser so the
//customer can finish the checkout process
}Regardless of the method chosen to initiate payments, if a Callback URL was specified in the request, Dwolla will "post back" a JSON object to the Callback URL after the user has completed the checkout. This callback usually happens asynchronously after the user's browser is redirected. It is good practice to verify the authenticity of the callback to ensure the callback hasn't been spoofed.
var jsonCallback =
@"
{
'Amount': 3.25,
'OrderId': 'A1B2C3',
'TestMode': true,
'TransactionId': 1,
'CheckoutId': 'C3D4DC4F-5074-44CA-8639-B679D0A70803',
'Status': 'Completed',
'Signature': '7f42ba58ff0d20486fdc2634745e8e7c92cb6321'
}";
//Parse the JSON into an object
var receivedCallback = JsonConvert.DeserializeObject<DwollaCallback>( jsonCallback );
var api = new DwollaServerCheckoutApi( appKey: "...", appSecret: "..." );
//Verify the DwollaCallback.Singature
//to ensure this is a valid HTTP POST from Dwolla.
if( api.VerifyAuthenticity(receivedCallback) )
{
//Update the payment status in your database.
if( receivedCallback.Status == DwollaStatus.Completed )
{
//Payment was successful.
}
else if( receivedCallback.Status == DwollaStatus.Failed)
{
//Payment was not successful.
}
}
else
{
//Log -- Possible URL tampering or trying to spoof their payment.
}Optionally, you can also handle the user's browser redirect from Dwolla too. Handling the URL parameters from the user's browser on an MVC controller is show below:
var api = new DwollaServerCheckoutApi( appKey: "...", appSecret: "..." );
public ActionResult Handle_Dwolla_BrowserRedirect(DwollaRedirect redirect)
{
if( api.VerifyAuthenticity( redirect ) )
{
if( redirect.Status == DwollaStatus.Completed )
{
//The User completed the transaction.
}
else
{
//The transaction failed.
}
}
return new HttpStatusCodeResult( HttpStatusCode.BadRequest );
}Created by Brian Chavez.
Note: This application/third-party library is not directly supported by Dwolla Corp. Dwolla Corp. makes no claims about this application/third-party library. This application/third-party library is not endorsed or certified by Dwolla Corp.