Check it out! - New Events


(Cory Anderson) #1

Check it out! Two new events

We added two new events! The customer_bank_transfer_creation_failed and customer_balance_inquiry_completed events assist our Partners in managing the Access API. Check out a quick overview and how to fire them below:

Event Description
customer_bank_transfer_creation_failed An attempt to initiate a transfer to a verified Customer’s bank failed due to a negative balance. Transfers initiated to a verified Customer’s bank must pass through the verified Customer’s balance before being sent to a receiving bank. Dwolla will fail to create a transaction intended for a verified Customer’s bank if the funds available in the balance are less than the transfer amount. In order fund a negative balance, Dwolla will fail to create a transaction to go to a receiving bank account.
customer_balance_inquiry_completed Upon checking a Customer’s bank balance, Dwolla will immediately return an HTTP 202 with response body that includes a status of processing. This event will be triggered when the bank balance check has completed processing.

customer_bank_transfer_creation_failed

An attempt to initiate a transfer to a verified Customer’s bank failed due to the Destination of the transfer holding a negative balance. In order fund a negative balance, Dwolla will fail to create a transaction to go to a receiving bank account.

Who could this effect?

A common scenario is when a Verified Customer (VCR) holding a balance sends money to a Receive Only Customer (RO). If there are insufficient funds in the VCR when the transfer is completed, the remaining funds are pulled from the balance funding source, which may cause the balance to go negative. In a subsequent bank transfer, the VCR will be unable to receive these funds to their bank, instead, settling in the balance.

Let’s test it out!

There are a couple prerequisites to fulfill in order to successfully trigger this event.

Customer Funding Sources
Sam
Verified personal Customer
Balance funding source has $150
Verified Bank funding source named “R01-late”
Learn more about insufficient funds
Darren
Recieve-only Customer
Verified bank funding source
Thomas
Verified personal Customer
Verified Bank funding source

Initiate a transfer to create a negative balance

Your R01-late bank funding source will create and fire off a transfer to the Receive Only Customer. The R01-late naming will tell fail the bank transfer via insufficient funds in the post-settlement. Due to the nature of Receive-Only Customers, once the funds have transferred, there is no way to refund or return these funds.
Let’s initiate a transfer from Sam to Darren

Source: Sam // R01-late bank funding source

Destination: Darren // Bank funding source

Amount: $200

What happened?

A transfer was initiated for $200. Once you press the “Process Bank Transfers” button twice in the Dashboard, this will cause the funds to fail from the source bank account post-settlement. Due to the nature of Receive-Only customers, a transfer that clears is unable to be returned, inevitably pulling money from the balance.
In this case, Sam’s bank had insufficient funds and the only way we could pull money from him was from the $150 from his balance. Unfortunately, this will also put his balance negative by $50.

Create another transfer

You can now initiate a transfer from Thomas to Sam.

Source: Darren // bank funding source

Destination: Sam // R01-late bank funding source

Amount: $5

What happened?

You will notice the new webhook get fired called customer_bank_transfer_creation_failed

Instead of sending the $5 to Sam’s bank funding source, the funds will fail to move through the balance. As a result, the funds settled to the negative balance in an attempt to make it whole. To double check Now you can check the balance of Sam’s balance funding source. You will find the updated balance of -$45. As a result, the customer_bank_transfer_creation_failed event was fired.

customer_balance_inquiry_completed

Recently, we observed balance check response times exceeding upwards of 5 minutes, and as a result, deployed changes to the API behavior to better accommodate high response times. Previously, when you did a GET to https://api.dwolla.com/funding-sources/{id}/balance the connection would stay open until we received the current available balance and then eventually returned an HTTP 200 or timeout.

Changing the balance check to be asynchronous changes the behavior, meaning this event will be fired after a balance check completes processing. This can be used as an alternative to repeatedly polling the API to check if processing has completed. Dwolla will immediately return an HTTP 202 with response body that includes a status of processing. Subsequent requests to this endpoint will return a 202 up until processing completes and then either return an HTTP 200 with the current balance or an HTTP 400 if there was an error (i.e. UnsupportedBank).

Who could this effect?

If you are an Access API Partner that is using a balance check, you will want to take this new behavior into consideration.

Test it out!

Due to the limitations of the Sandbox environment and the use of fake data, it is not possible to fully simulate this event and receive an HTTP 202. In the Sandbox, Dwolla will always return a 200 with an available balance.

To learn how this event will be fired in the Production environment, read on!

Production behavior

When you call a balance check, we will immediately return an HTTP 202 with a response body that includes a status of processing.

{
  "status": "processing"
}

Requests after the initial 202 will return either:

  1. a 202 if the request is still processing
  2. a 200 with a response body containing the amount in the balance
  3. a 400 if there’s an error in checking the balance for that particular bank(i.e. UnsupportedBank)
  4. a 503 if there’s an error with talking to our upstream provider.

A webhook with event topic of customer_balance_inquiry_completed which will point to the funding source that the balance check completed for.

Example payload:

{
  "id": "84f296e9-08a6-46b2-bb23-bd25552492f5",
  "resourceId": "00e17e13-8ebb-4160-96e7-c632170ef9f9",
  "topic": "customer_balance_inquiry_completed",
  "timestamp": "2017-01-20T22:15:48.265Z",
  "_links": {
    "self": {
      "href": "https://api-sandbox.dwolla.com/events/84f296e9-08a6-46b2-bb23-bd25552492f5"
    },
    "account": {
      "href": "https://api-sandbox.dwolla.com/accounts/ad5f2162-404a-4c4c-994e-6ab6c3a13254"
    },
    "resource": {
      "href": "https://api-sandbox.dwolla.com/funding-sources/00e17e13-8ebb-4160-96e7-c632170ef9f9"
    },
    "customer": {
      "href": "https://api-sandbox.dwolla.com/customers/e358a488-6699-4d79-bbfb-c5bf58100ea4"
    }
  },
  "created": "2017-01-20T22:15:48.265Z"
}

2017 - The Highlights