Plugin to use Dwolla as a gateway
Java
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
.idea
src
.gitignore
.travis.yml
LICENSE
NEWS
README.md
pom.xml

README.md

killbill-dwolla-plugin

Plugin to use Dwolla as a gateway. It supports both Dwolla Direct (co-branded product, easier to setup), as well as Dwolla White Label (for deeper integrations). Funding sources can be verified through both IAV (Instant Account Verification) and Micro-deposit verifications. You can even configure it to listen to webhooks, to get real-time notifications of the deposits status.

Release builds are available on Maven Central with coordinates org.kill-bill.billing.plugin.java:dwolla-plugin.

Kill Bill compatibility

Plugin version Kill Bill version
0.1.y 0.18.z

Requirements

The plugin needs a database. The latest version of the schema can be found here.

Merchants need to create a Dwolla application. The first time a token pair needs to be created from Dwolla Application page, and save into plugin database. The plugin offers two endpoints to creante and update this token pair.

// TO CREATE A NEW TOKEN PAIR
curl -v \
     -X POST \
     -u admin:password \
     -H 'X-Killbill-ApiKey: bob' \
     -H 'X-Killbill-ApiSecret: lazar' \
     -H 'X-Killbill-CreatedBy: admin' \
     -H 'Content-Type: text/plain' \
     -d '{
           "accessToken": "<ACCESS-TOKEN>",
           "refreshToken": "<REFRESH-TOKEN>"
         }' \
     http://127.0.0.1:8080/plugins/killbill-dwolla

// TO UPDATE AN EXISTING TOKEN PAIR
curl -v \
     -X PUT \
     -u admin:password \
     -H 'X-Killbill-ApiKey: bob' \
     -H 'X-Killbill-ApiSecret: lazar' \
     -H 'X-Killbill-CreatedBy: admin' \
     -H 'Content-Type: text/plain' \
     -d '{
           "accessToken": "<ACCESS-TOKEN>",
           "refreshToken": "<REFRESH-TOKEN>"
         }' \
     http://127.0.0.1:8080/plugins/killbill-dwolla
    

A Webhook Subscription is needed to receive Dwolla notifications.

Build

To build the plugin locally, see https://github.com/Dwolla/dwolla-swagger-java/blob/master/README.md.

Configuration

The following properties are required:

  • org.killbill.billing.plugin.dwolla.baseUrl : REST Payment service url (i.e. https://api-uat.dwolla.com/ or https://api.dwolla.com/)
  • org.killbill.billing.plugin.dwolla.baseOAuthUrl : REST Auth service url (i.e. https://uat.dwolla.com/oauth/v2 or https://dwolla.com/oauth/v2)
  • org.killbill.billing.plugin.dwolla.scopes : The application scopes (i.e. Send|AccountInfoFull|Funding)
  • org.killbill.billing.plugin.dwolla.clientId : Your merchant application key.
  • org.killbill.billing.plugin.dwolla.clientSecret : Your merchant application secret.
  • org.killbill.billing.plugin.dwolla.accountId : Your merchant account id.

These properties can be specified globally via System Properties or on a per tenant basis:

curl -v \
     -X POST \
     -u admin:password \
     -H 'X-Killbill-ApiKey: bob' \
     -H 'X-Killbill-ApiSecret: lazar' \
     -H 'X-Killbill-CreatedBy: admin' \
     -H 'Content-Type: text/plain' \
     -d 'org.killbill.billing.plugin.dwolla.baseUrl=UUU
     org.killbill.billing.plugin.dwolla.baseOAuthUrl=VVV
     org.killbill.billing.plugin.dwolla.scopes=WWW
     org.killbill.billing.plugin.dwolla.clientId=XXX'
     org.killbill.billing.plugin.dwolla.clientSecret=YYY'
     org.killbill.billing.plugin.dwolla.accountId=ZZZ' \
     http://127.0.0.1:8080/1.0/kb/tenants/uploadPluginConfig/killbill-dwolla

Kill Bill

Usage

A full end-to-end integration demo is also available here.

Bank account

Add a payment method:

curl -v \
     -u admin:password \
     -H "X-Killbill-ApiKey: bob" \
     -H "X-Killbill-ApiSecret: lazar" \
     -H "Content-Type: application/json" \
     -H "X-Killbill-CreatedBy: demo" \
     -X POST \
     --data-binary '{
       "pluginName": "killbill-dwolla",
       "pluginInfo": {
         "properties": [
           {
             "key": "fundingSource",
             "value": "9ece9660-aa34-41eb-80d7-0125d53b45e8"
           },
           {
             "key": "customerId",
             "value": "ca32853c-48fa-40be-ae75-77b37504581b"
           }
         ]
       }
     }' \
     "http://127.0.0.1:8080/1.0/kb/accounts/<ACCOUNT_ID>/paymentMethods?isDefault=true"

Notes:

To trigger a payment:

curl -v \
     -u admin:password \
     -H "X-Killbill-ApiKey: bob" \
     -H "X-Killbill-ApiSecret: lazar" \
     -H "Content-Type: application/json" \
     -H "X-Killbill-CreatedBy: demo" \
     -X POST \
     --data-binary '{"transactionType":"PURCHASE","amount":"5","currency":"EUR","transactionExternalKey":"INV-'$(uuidgen)'-PURCHASE"}' \
    "http://127.0.0.1:8080/1.0/kb/accounts/<ACCOUNT_ID>/payments"

Notes:

  • Make sure to replace ACCOUNT_ID with the id of the Kill Bill account

At this point, the payment will be in PENDING state, until we receive a notification from Dwolla. You can verify the state of the transaction by listing the payments:

curl -v \
     -u admin:password \
     -H "X-Killbill-ApiKey: bob" \
     -H "X-Killbill-ApiSecret: lazar" \
     -H "Content-Type: application/json" \
     -H "X-Killbill-CreatedBy: demo" \
    "http://127.0.0.1:8080/1.0/kb/accounts/<ACCOUNT_ID>/payments?withPluginInfo=true"

You can simulate a notification from Dwolla as follows:

curl -v \
     -u admin:password \
     -H "X-Killbill-ApiKey: bob" \
     -H "X-Killbill-ApiSecret: lazar" \
     -H "Content-Type: application/json" \
     -H "X-Killbill-CreatedBy: demo" \
     -X POST \
     --data-binary '
     {
      "id": "80d8ff7d-7e5a-4975-ade8-9e97306d6c16",
      "topic": "customer_transfer_completed",
      "_links": {
        "self": {
          "href": "https://api-uat.dwolla.com/events/80d8ff7d-7e5a-4975-ade8-9e97306d6c16"
        },
        "account": {
          "href": "https://api-uat.dwolla.com/accounts/b3153e29-b25a-4ccd-9c1a-5b05b606e50c"
        },
        "resource": {
          "href": "https://api-uat.dwolla.com/transfers/7c8e7484-2184-e611-80e8-0aa34a9b2388"
        },
        "customer": {
          "href": "https://api-uat.dwolla.com/customers/b3153e29-b25a-4ccd-9c1a-5b05b606e50c"
        }
      }
    }' \
    "http://127.0.0.1:8080/1.0/kb/paymentGateways/notification/killbill-dwolla"

Notes:

  • Make sure to replace resource.href with the Dwolla transfer id reference of your payment (see the dwolla_responses table)
  • If topic is customer_transfer_completed, the payment transaction state will be SUCCESS and the payment state PROCESSED
  • If topic is customer_transfer_failed or customer_transfer_canceled, the payment transaction state will be PAYMENT_FAILURE and the payment state ERROR