Labels - Breathing Life into Ledgers

(Cory Anderson) #1

Labels - Breathing Life into Ledgers

Ledgers. Fun, right?
No? Well, we can change that. First, let’s set up the scenario.

Let’s say you’re creating the next game-changing savings application where new college students can save for various goals over their college career by sending funds from their bank accounts to their Dwolla Balance.

Cory the College Kid - Savings Goals

  • Goal1 - Books for Next Semester ($250)
  • Goal2 - New TV for the Apartment ($290)
  • Goal3 - A new bike for campus ($350)

Label Creation

Previously with the Dwolla API, in order to keep track of these different goals within the Dwolla Balance, your application would need to create its own “sub-balance” functionality.

With the new Dwolla Labels functionality, your application can assign values from an existing Verified Customers’ Dwolla Balance to different Labels.

Think of Labels as assigning different “buckets” where you can allocate a portion of a Dwolla balance.

Let’s go back to our savings app and assume Cory, our end-user, has a Dwolla balance of $100. Cory has decided to assign $15.00 to go towards his “Books” goal. In order to do this, we will create a Label to designate the amount to be labeled for this goal.

Create a Label

All that is required to initially create a label is a positive amount which tells Dwolla to allocate a portion of Cory’s balance to his books goal.

POST https://api-sandbox.dwolla.com/customers/{{verifiedCustomerId}}/labels
Accept: application/vnd.dwolla.v1.hal+json
Content-Type: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqO
Idempotency-Key: 19051a62-3403-11e6-ac61-9e71128cae77

{
	"amount": {
		"currency": "USD",
		"value": "15.00"
	}
}

...

HTTP/1.1 201 Created
Location: https://api-sandbox.dwolla.com/labels/9e4dc8cc-4e09-4832-9e46-1ed5f15a98ab

When the Label is created, you will receive a 201 HTTP response with an empty response body. You can refer to the Location header to retrieve a link to the created Label. We recommend storing the full URL for future use as it will be referenced when making updates to the Label Ledger.

Label Value Reallocation

Now consider a situation where our student already has enough funds to cover books for the upcoming academic semester and wants to reassign some of his books savings towards his bike goal.

Creating and managing a ledger that updates these “sub-balances” would bring more complexity to your application and more development time that could otherwise be used to work on other revenue-generating features.

With the new Dwolla Labels functionality, your application can take advantage of a real-time ledger within a Verified Customer’s Dwolla Balance to track changes to the label amounts.

Now, let’s examine the scenario where our college student would like to move $25 out of his ‘Books goal’ and reassign it to his bike savings.

Reallocate a Label’s Value

We can create a label reallocation by specifying the amount as well as the from and to Label parameter for the reassignment of $25.

POST https://api-sandbox.dwolla.com/label-reallocations
Accept: application/vnd.dwolla.v1.hal+json
Content-Type: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqO
Idempotency-Key: 51a62-3403-11e6-ac61-9e71128cae77190

{
  "_links":{
    "from": {
      "href": "https://api-sandbox.dwolla.com/labels/cca6a6b3-da04-4fa2-a11a-5f65b2e33f8d"
    },
    "to": {
      "href": "https://api-sandbox.dwolla.com/labels/9e4dc8cc-4e09-4832-9e46-1ed5f15a98ab"
    }
  },
  "amount": {
    "value": "25.00",
    "currency": "USD"
  }
}
...

HTTP/1.1 201 Created
Location: https://api-sandbox.dwolla.com/label-reallocations/57dea5af-bd11-4522-8dba-9bc9d4c436c0

When the Label reallocation request succeeds, you will receive a 201 HTTP response with an empty response body. You can refer to the Location header to retrieve a link to the created label reallocation resource. A label reallocation will create label ledger entries on both of our Labels representing our books and bike savings goals.

Wrapping it Up

With Dwolla’s new Labels functionality, you now have a seamless way to assign values to various parts of a verified Customer’s balance funding source. Want to learn more? Check out our updated API Reference Docs to get all the details on implementing this exciting new feature.

Tell us in the thread below, what do you plan on using Labels for?

3 Likes