Initial implementation

[pierre]

This payment plugin will integrate Dwolla with Kill Bill.

Here is the official Java client. The implementation will be very similar to the Adyen plugin (check the work-for-release-0.17.x branch - we won't adapt this plugin to work with Kill Bill 0.16.x).

Implementation details for the PaymentPluginApi:

• Customers will map to Kill Bill accounts
• Payment Methods in Kill Bill will map to funding sources
• getPaymentMethods can use the Fetch funding sources API
• purchasePayment can use the Create a transfer API
• getPaymentInfo can use the Check transfer status API
• Webhooks will be integrated with the processNotification API (see our doc)

To verify the integration, it would be nice to create a small demo, similar to the Stripe one for example.

[matias-aguero-hs]

@pierre I started working on this integration. First of all I'm reading Dwolla docs and following your instructions.

• Customers will map to Kill Bill accounts
• Payment Methods in Kill Bill will map to funding sources

I assume that the customer already created the Dwolla account and FundingSource before add it as a KillBill payment method, and KillBill expects the funding source id as a parameter when the payment method is created. Is that correct?

[pierre]

I assume that the customer already created the Dwolla account and FundingSource before add it as a KillBill payment method, and KillBill expects the funding source id as a parameter when the payment method is created. Is that correct?

It actually depends on the integration method, see https://developers.dwolla.com/guides/receive-money/.

In the white label solution, the dwolla.js flow is very similar to a credit-card tokenization flow (like Stripe: the callback with the funding source id is passed in the create payment method call).

In the Dwolla Direct solution, the flow is similar to an HPP flow (the initial url should be generated using the buildFormDescriptor API). The refresh payment methods plugin API can then implement Step C. (i.e. creating payment methods according to the list of funding sources).

Does that make sense?

[matias-aguero-hs]

Thanks.

In the white label solution, the dwolla.js flow is very similar to a credit-card tokenization flow (like Stripe: the callback with the funding source id is passed in the create payment method call).

I prefer this option, it makes more sense to me.

Another point is about the dwolla plugin dao. In my opinion it shouldn't extend from PluginPaymentDao, because it has several db columns that Dwolla will not use.

[pierre]

I prefer this option, it makes more sense to me.

Actually, merchants will decide how they will want to implement their integration. 😸

This is similar to credit-card payment plugins: some merchants use JavaScript to tokenize the card in the gateway, some (which are PCI certified) simply pass the PAN to the gateway and don't use the tokenization feature.

Eventually, we would want to implement both flows. But it's fine to focus on one for now.

Another point is about the dwolla plugin dao. In my opinion it shouldn't extend from PluginPaymentDao, because it has several db columns that Dwolla will not use.

Up to you. PluginPaymentDao gives you a lot for free though (e.g. how responses are traditionally stored).

[matias-aguero-hs]

@pierre I developed a small demo app (similar to stripe one). Can you please create a repo? So I can commit the code. I'm also going to commit a first wolla-plugin version this week.

[pierre]

Awesome!

Here you are: https://github.com/killbill/killbill-dwolla-demo

[matias-aguero-hs]

@pierre I'm having some trouble with Dwolla recurring payments. It seems recurring payments are not yet supported for V2.

The main issue is that a transfer action requires an user access token (it's expires after 60 minutes), and the only way get it without user interaction is to call refresh token api, but it also change and we should store the last valid code in the database.

NOTE: The refresh_token you receive will change every time you exchange either 
an authorization_code or refresh_token for a new token pair.

I'm a bit confused and worried about how to implement it.

[pierre]

I'm having some trouble with Dwolla recurring payments. It seems recurring payments are not yet supported for V2.

I don't have full context but it seems that this is about having Dwolla trigger recurring payments (similar to, say, Stripe subscriptions)?

We don't really care about that feature since payments should be driven by Kill Bill (Kill Bill implements the recurring portion). 😏

We do need a way to trigger subsequent payments though (more below).

The main issue is that a transfer action requires an user access token (it's expires after 60 minutes), and the only way get it without user interaction is to call refresh token api, but it also change and we should store the last valid code in the database.

Can't you call this API before initiating the payment (in the createPurchase call, or equivalent)? If you need to always keep the latest "refreshed" token, you can simply swap the value in the payment methods token column, during each payment.

Does that make sense? Or am I missing something?

[matias-aguero-hs]

We don't really care about that feature since payments should be driven by Kill Bill (Kill Bill implements the recurring portion). 😏

You are right. This is solved by KillBill, but I think we'll have problems with tokens. (see bellow)

Can't you call this API before initiating the payment (in the createPurchase call, or equivalent)? If you need to always keep the latest "refreshed" token, you can simply swap the value in the payment methods token column, during each payment.

Yes, we can. But we have some scenarios that may not work. Please check Token lifetimes.

1. I'm not sure if the 60 days are from user authorisation (can be used up to 2 invoices/months) or it is reseted every time token pair is refreshed.
2. Annual subscriptions will fail when our plugin try to refresh token (both will be expired).
3. Suppose we save the refresh token in paymentMethod.token column, what happen if it fails for any reason and we keep an invalid token?

I'm asking me if this gateway is prepared to accept transactions during a long period of time without an user re-auth.

[pierre]

Yes, we can. But we have some scenarios that may not work.

Could you reach out to our contact(s) at Dwolla regarding question 1? They should be able to answer it.

1. Annual subscriptions will fail when our plugin try to refresh token (both will be expired).
2. Suppose we save the refresh token in paymentMethod.token column, what happen if it fails for any reason and we keep an invalid token?

Any payment plugin should be prepared to handle these failure scenarios (these are very common in practice). It's very similar to, say, a credit card that has expired one year later. As long as the plugin returns a PAYMENT_FAILURE to Kill Bill, the system will be able to take care of it (notify the user, update the invoice/account balance, trigger overdue, etc.).

I'm asking me if this gateway is prepared to accept transactions during a long period of time without an user re-auth.

Let's see what Dwolla says about 1. If indeed after 2 months we always need to get some input from the user, I don't think it's difficult to handle:

• The payment will fail (PAYMENT_FAILURE)
• The user will be notified (e.g. via email) and prompted to go through the oauth flow again
• The plugin should be able to update the payment method (depending on the API used, this can be through the refresh mechanism for instance)

For annual subscriptions, if we know it's never going to work, associated accounts should probably be tagged with MANUAL_PAY (this is similar to a user sending a check: a user interaction is always required).

In a nutshell, all payment providers and payment methods behave a little bit differently. Kill Bill should have enough hooks to support these various flows though.

[matias-aguero-hs]

Could you reach out to our contact(s) at Dwolla regarding question 1? They should be able to answer it.

• question: Is this period reseted every time the token pair is refreshed? (we can call your api monthly and keep the latest valid token)
• answer: Correct. Every time you refresh authorization on an account token you'll receive a new access token and refresh token pair. The access token will have a ttl of 1 hour and the refresh token 60 days.

In addition, they included: On-demand transfers: From the example provided in your email, it appears that you are wanting to send variable amounts for variable dates in the future. With ACH, a specific authorization is required in order to allow this functionality. The user must agree to an on-demand bank transfer authorization when they are adding their funding source(Bank Account) within Dwolla. If using IAV, it's as simple as us flipping a flag on the Partner Dwolla Account which allows the authorization text to display.

[pierre]

From the example provided in your email, it appears that you are wanting to send variable amounts for variable dates in the future. With ACH, a specific authorization is required in order to allow this functionality. The user must agree to an on-demand bank transfer authorization when they are adding their funding source(Bank Account) within Dwolla. If using IAV, it's as simple as us flipping a flag on the Partner Dwolla Account which allows the authorization text to display.

FYI, such display requirements are similar to the ones for SEPA mandates.

[matias-aguero-hs]

@pierre I created two PRs to show you the progress of the plugin and demo page.

• Demo: https://github.com/killbill/killbill-dwolla-demo/pull/1
• Plugin: https://github.com/killbill/killbill-dwolla-plugin/pull/2

The plugin creates transfers for White Label solution. Pending work is:

• Handling errors and exceptions
• Webhooks

[matias-aguero-hs]

@pierre I finishing processNotification implementation (White label). How do you test it in a local environment? Do you have a way to make 'http://127.0.0.1:8080/1.0/kb/paymentGateways/notification/killbill-dwolla' public for Dwolla API?

[pierre]

I finishing processNotification implementation (White label). How do you test it in a local environment? Do you have a way to make 'http://127.0.0.1:8080/1.0/kb/paymentGateways/notification/killbill-dwolla' public for Dwolla API?

127.0.0.1 being a local address, Dwolla won't be able to access it.

You have two options:

• Setup the server on a public IP (e.g. temporary EC2 zone) and configure the Dwolla sandbox to point to that address.
• Mock the payload in a unit test. That's what we do for Adyen for example: we hardcode the raw XML that Adyen would send, and use it as an input to the processNotification method (this is what would happen inside Kill Bill too, as both KNP and Kill Bill will simply pass through the raw data to the plugin, without modification).

[matias-aguero-hs]

Thank you. We'll try to do both.

[matias-aguero-hs]

@pierre Dwolla White Label solution is almost done for these actions:

• Add payment method
• Create transfers (pay invoice)
• Process payment notifications (transfer results)

Regarding payment methods, I implemented IAV (Instant Account Verification), but there is another option called Micro-deposit verification. Do you also want to support this way? (the plugin need to create two micro deposits, and the funding-source cannot be use for transactions until the plugin receives a notification of customer approval)

[pierre]

Do you also want to support this way?

Yup, I think it would be useful to support it too, especially for non-white label implementations.

[matias-aguero-hs]

Yup, I think it would be useful to support it too, especially for non-white label implementations.

Ok, I'll include it.

FYI, I just pushed some changes to implement refund feature.

[pierre]

@matias-aguero-hs I've reviewed the refund feature. 👍 (just a couple of minor comments)

Let me know when you are in a good spot so I can merge this and we can do smaller PRs moving forward (it's getting tricky to review with all these changes).

[matias-aguero-hs]

@pierre I think you can merge this branch now, and I can open individual branches for pending tasks. As I remember, the pending tasks are Dwolla Direct Solution and Micro Deposits.

[pierre]

@matias-aguero-hs I've reviewed the refund feature. 👍 (just a couple of minor comments)

...that I forgot to submit! Sorry! 😸

Just merged both PRs.

[matias-aguero-hs]

Guys, these are the PRs for Dwolla Direct solution.

• Demo: https://github.com/killbill/killbill-dwolla-demo/pull/2
• Plugin: https://github.com/killbill/killbill-dwolla-plugin/pull/3