[2.5][nikandrovalex][1][gibbsfromncis] UX Add support for recurring payments

[svk31]

From @svk31 on December 29, 2015 7:10

Copied from original issue: cryptonomex/graphene-ui#639

[svk31]

Most likely even the 160120 milestone is too soon for this, it will require some digging to find out how stuff works and what's actually possible.

[svk31]

From @noisy on February 2, 2016 0:50

This feature will be very good for new businesses. :+1:

[svk31]

Copy paste of xeroc's explanation of how this works on the blockchain level:

1) you setup a withdraw permission:

get_prototype_operation withdraw_permission_create_operation
[
  25,{
    "fee": {
      "amount": 0,
      "asset_id": "1.3.0"
    },
    "withdraw_from_account": "1.2.0",
    "authorized_account": "1.2.0",
    "withdrawal_limit": {
      "amount": 0,
      "asset_id": "1.3.0"
    },
    "withdrawal_period_sec": 0,
    "periods_until_expiration": 0,
    "period_start_time": "1970-01-01T00:00:00"
  }
]

All you need to define is

• The account from which to withdraw
• The account that is allowed to withdraw
• The asset and amount limit that is allowed to withdraw
• And the period in which the limit is reset (e.g. 1k$ monthly.)
• as well as the start time

2) The other party can withdraw funds from your account with the withdraw operation:

get_prototype_operation withdraw_permission_claim_operation
[
  27,{
    "fee": {
      "amount": 0,
      "asset_id": "1.3.0"
    },
    "withdraw_permission": "1.12.0",
    "withdraw_from_account": "1.2.0",
    "withdraw_to_account": "1.2.0",
    "amount_to_withdraw": {
      "amount": 0,
      "asset_id": "1.3.0"
    }
  }
]

You need

• The actually object id of that withdrawal permission
• the account to withdraw from (imho redundant)
• the account to withdraw to
• and the amount

The biggest problem here is that the withdraw permissions are not "searchable" and I don't think they are in the results of get_full_account yet. @abit: maybe you can help add them there.

Once you have a withdraw permission object id (and the matching account), you can create a withdrawal transaction!

[abitmore]

Might had been closed accidentally. Reopened.

[wmbutler]

Thanks!

[wmbutler]

@ahdigital Need your UX skills for this. It's in the March Sprint so you can delay it until then.

[abitmore]

@wmbutler just FYI I'm not sure if the required API will be ready in March.

[wmbutler]

Thanks. I'll be adding a bunch more Milestones and will push this appropriately.

[ahdigital]

@wmbutler Add me under the UX tag and I will work on a proposal.

[wmbutler]

It's yours.

[ahdigital]

I started working out the scope for this issue, and I read this:

The other party can withdraw funds from your account with the withdraw operation

And looking at the API documentation for the class it's definition is:

Withdrawal permissions define withdrawal periods, which is a span of time during which the authorized account may make a withdrawal. Any number of withdrawals may be made so long as the total amount withdrawn per period does not exceed the limit for any given period.

I think the issue title 'recurring payments' will be a poor UX choice because it suggests payments can be scheduled and automatically sent and I don't think this will be possible. Can someone confirm?

If it's not possible it raises these questions:

1. What can we rename this issue/new functionality?
   • What about 'Grant Funds'?
2. What happens if the other party doesn't withdraw the maximum available funds within the period set? Do they roll over?
3. Are the total funds defined for the period locked/allocated to ensure they'll be available for the other party to withdraw?
4. Will we be able to notify or remind the other party that they have funds available for withdrawal?

[wmbutler]

@ahdigital I think @ryanRfox and his team could be helpful in this conversation. Moving to May per @abitmore

[abitmore]

1. What can we rename this issue/new functionality?
   • What about 'Grant Funds'?
2. What happens if the other party doesn't withdraw the maximum available funds within the period set? Do they roll over?

Good question. The answer is no, the remaining funds won't be withdraw-able in next period.

3. Are the total funds defined for the period locked/allocated to ensure they'll be available for the other party to withdraw?

No.

4. Will we be able to notify or remind the other party that they have funds available for withdrawal?

Should be possible.

[wmbutler]

Assuming this would be set up like a common billpay flow:

• [ ] Set authorized recipient (account with authority to request funds)
• [ ] Set authorized amount
• [ ] Set frequency: Monthly (default), Weekly, Yearly, Daily, manual date picker to manually set windows.

Monthly window would be 2018-01-01 - 2018-02-28 etc...

• [ ] Display a listing of all authorized bill pays
• [ ] filter at header
• [ ] Ability to multi-select and cancel bill pays
• [ ] Ability to view past history (per payee) to be able to verify activity
• [ ] csv export

[abitmore]

• Set frequency: Monthly (default), Weekly, Yearly, Daily, manual date picker to manually set windows.

The back end is based on seconds. So, daily and weekly is OK, but monthly and yearly is a bit tricky. E.G. need to set 365.25*86400 seconds aka 365.25 days for a year, and 365.25*86400/12 seconds aka 30.4375 days for a month, that means a user may probably find herself be charged twice in a month and etc.

[wmbutler]

Monthly will be by far the most heavily used range. Seems that the backend should be based on date ranges. Is this negotiable with the core team? This feature will need to be perfect in order for widespread adoption to occur.

@ryanRfox

[abitmore]

Currently the chain doesn't handle dates, it's perhaps possible to do so, but I think it's a bit too complicated. Actually, if you're concerned about dates, you'll also be concerned about time zones, Daylight Saving Time and etc.

[wmbutler]

@abitmore Dates make the business world go around. We would store dates in UTC of course. This is not a new problem. I just want to underscore the importance of this feature in the business world. If we do this perfectly, it will get used. If we don't it won't and monthly bills are the most common.

[abitmore]

If it really makes sense, get someone write a BSIP first.

[wmbutler]

@ryanRfox going to leave this to your team. Pushing to mid May.

[sschiessl-bcp]

Set frequency: Monthly (default), Weekly, Yearly, Daily, manual date picker to manually set windows.

I don't think that this should keep UI implementation for this feature to happen. I'd be happy to look into it again if wanted?

[wmbutler]

Feel free, but without a window for backend changes, I don't see the point in expending a lot of effort here.

[sschiessl-bcp]

Just FYI, I plan to pick this up beginning/middle of august

[oxarbitrage]

this is the correct pull that was merged, this are the api calls available: https://github.com/bitshares/bitshares-core/pull/676

[oxarbitrage]

there are 2 things needed in the core to make the feature more complete, not any of the 2 are needed to develop UI interface but i think it will help the whole:

• be able to do the process from client/seller with dedicated cli wallet calls.
• have test cases with different scenarios.

maybe open an issue in the core for this ...

[TheTaconator]

@svk31 @wmbutler: I drafted suggestions in a document that describes two user experiences, and supporting GUI for them in case they might be helpful

[gibbsfromncis]

@wmbutler @startailcoon If I understand correct recurring payments already support on blockchain level and we can start to work on UI implementation. Right?

If so, lets do it :)

[sschiessl-bcp]

I'm pretty much just waiting to get a go for #1860, which creates a place for this to go.

Maybe @nikandrovalex can already start with a mockup for this one?

[gibbsfromncis]

@sschiessl-bcp I suppose we should provide more details or any requirements list for @nikandrovalex because he is not familiar enough with Bitshares. If you ready to do it it would be cool

[wmbutler]

I saw saw @TheTaconator writeup for recurring payments and it's very detailed. I think we need to be careful about terminology and approach this carefully to avoid confusion. There are two ways that traditional contracts work.

• Payer initiated. I, as the payer, can commit to pay an amount every month. Since I hold the keys, this simply happens every month. We need a few things for UX here.

  • [ ] Optional picker on the Send modal for setting date and time recurrence.
  • [ ] A dashboard to show all of the scheduled transactions

• Payee initiated

  • [ ] Optional picker in the Propose modal for setting date and time recurrence
  • [ ] A dashboard to show all of the scheduled transactions

If it's payer initiated, it would require no manual approvals. If it's payee initiated, I'd expect a proposal would appear each period that would require confirmation. Curious to hear your thoughts.

[TheTaconator]

@wmbutler suspect that recurring confirmation by giver is the less common use case. Suspect that the most common use case is a (1) recipient requests/prepares a recurring payment once, (2) giver approves once, and (3) recipient performs recurring withdrawals until either the contract expires or the user cancels the contract.

If a recurring confirmation by the giver is desired then some possibilities exist: (A) recipient periodically prepares for approval by giver a "regular" proposed transaction; (B) recipient periodically prepares for approval by giver a single cycle "recurring payment"; (B) recipient periodically prepares a special case "recurring payment" that does require monthly re-confirmations by giver.

Option A exists in Core and in Reference Wallet Option B exists in Core Option C would likely require a new operation in Core

[TheTaconator]

Regarding terminology: recurring withdrawals can be used to pay for goods or services but also for non-payments such as remittances

[sschiessl-bcp]

I saw saw @TheTaconator writeup for recurring payments and it's very detailed

I think you saw the new BSIP, which is not done or voted in yet. Your description targets how the automated payment should take place. This is not in the scope of this issue, every repeated withdrawal/payment must be manually triggered. User can possibly be remindend to do so in the UI.

The goal is to create a panel that allows the user to create the withdrawal permission (withdraw_permission_create_operation), and to allow the recipient to claim from such a permission (withdraw_permission_claim_operation). It makes sense to put that in its own panel and not include it in the send modal.

1. proper design within send is too complicated
2. user also wants to see which other accounts gave him withdrawal permission, how much still claimable etc., which does not fit into send
3. it is its own use-case and should leveraged as such, thus the idea with the showcases #1860

[TheTaconator]

@sschiessl-bcp @wmbutler just to clarify one point with the existing recurring feature and manual triggers: recurring withdrawals must be "manually" triggered only by recipient after the contract is initiated

[wmbutler]

Terminology check. We should probably stop using the word withdraw since it typically implies funds leaving the BTS ecosystems via a gateway. Can we use terms send and receive instead?

I've been thinking of billpay operations that I use all the time and as I put more thought into it, I see that I am implicitly trusting the recipient with this contract. The recipient or vendor is saying they will pull either a fixed or variable amount from my account each month. Utilities are typically variable whereas other services are fixed values and a fixed period.

So, let's say I sign up for a service that costs $10 per month. Once I sign up, I have payment options. fiat/paypal/bitUSD. I choose bitUSD and am presented with a recurring monthly contract generated by the vendor of $10 on the 5th of each month. I accept the contract, BEET (scatter) pops up and asks me to sign. Now, I should be able to go to my wallet and see this commitment.

This gets more difficult if the value is arbitrary. In this case, does the BSIP handle a way to set a max value so guardrails can be placed on the potential damage? For instance, if my utility bill generally ~80 per month, do we have a mechanism to set an upper range of 120/month? It's fine if not, but this will limit us to recurring transactions where the value is fixed until this feature is added.

[abitmore]

For instance, if my utility bill generally ~80 per month, do we have a mechanism to set an upper range of 120/month? It's fine if not, but this will limit us to recurring transactions where the value is fixed until this feature is added.

If you assume the upper bound is 120, you just need to setup the "monthly pulling limit" to 120, then your service provider will be able to pull any amount equal to or lower than 120 per month from your account.

[sschiessl-bcp]

This issue is to implement the existing feature, not what the new BSIP (not yet completed, and not voted in) might provide. At the end it will be the same core feature, plus a monthly option and automatic execution. That should be easily implementable in whatever UI we come up with.

Your intended use is possible @wmbutler , with the restriction that you would have to set up the permission for your electricity company with a max. amount per time interval, and then the electricity company would have claim in every interval manually.

From the intended usage we could call it "direct debit authorization", or "direct debit mandate".

[TheTaconator]

@wmbutler The act of "send", as opposed to the enduring authorization, might be awkward because the recipient performs the action.

Suggestion by @sschiessl-bcp of "debit" is reasonable for the act if "withdraw" term is deprecated

Maybe the enduring authorization can be called "recurring send" or "recurring debit"

[sschiessl-bcp]

@nikandrovalex Do you have an idea on the timeframe for this issue?

Happy to discuss details on necessary functionality, please ping me.

This is just for reference https://github.com/bitshares/bitshares-core/blob/3ea52879d634f0bd5bca80e6059b9308ba3270ff/libraries/chain/include/graphene/chain/protocol/withdraw_permission.hpp#L49

[Agorise]

We will be implementing this into both of our mobile wallets. If you guys could send us screenshots or camera snaps from drawing-mockups here would be great. A feature like this will definitely need to be grandma-friendly.

Also @TheTaconator regarding "recurring send" or "recurring debit", that could be "send" from the user/employer that sets it up, and the ui displays the term "debit" to the person/employee at the receiving end (like the mobile wallet user) i'd think.

(like an employer that sends out some of their company token to all subscribed employees every month. some employers may send some or all of an employees wages as company tokens, and each employee may receive a differing amount of the company token that month, based on their wages for that month)

[wmbutler]

The goal is to create a panel that allows the user to create the withdrawal permission (withdraw_permission_create_operation), and to allow the recipient to claim from such a permission (withdraw_permission_claim_operation). It makes sense to put that in its own panel and not include it in the send modal.

@sschiessl-bcp from the standpoint of a withdrawal permission, I feel strongly that this belongs on the send modal. The design pattern is very much like that of a recurring calendar invite.

We do need a withdrawal permissions screen to allow the user to view and edit those set from the send modal.

[sschiessl-bcp]

I suppose it would be possible to be included there.

For the additional screen, you also need the option to actually claim it. From a user perspective you have four parts:

1. setup permission for someone else
2. view permission that I have given or received
3. edit permission
4. claim from a permission

Which of those would you see within Send modal? I assume 1. and 4.

[sschiessl-bcp]

@nikandrovalex

First step I suggest to do UX for setup/update permission. Required inputs to setup/update permission:

• authorized account
• withdrawal limit per period (this is a maximum, actual claim can be less, only one claim per period allowed!)
• withdrawal period (in seconds)
• number of periods
• start of first period

Bill suggests to include it into the send modal. When setting up or editing a permission, the memo is not applicable. I suggest to replace that area with a permission detail selector component. On the right area of "Quantity" we could display "Recurring debit" to toggle the creation of withdrawal permissions.

The component should allow the user to specify a start date and the period length, which is set in seconds in the backend. Possible options for the user could be:

• hourly, reset on :00/:20/etc.
• daily, reset on 8:00/10:00/etc.
• weekly, reset on Monday|Tuesday|etc. (default to 12:00 UTC on that day)
• bi-weekly, reset on Monday|Tuesday|etc. (default to 12:00 UTC on that day) After specifying the start date and period length, I imagine that the user may either want to:
• specify how many periods should be possible (expiration is then calculated)
• specify when the permission should expire (number of periods is then calculated)

[nikandrovalex]

Hi @sschiessl-bcp Please check, I correctly understood the task?

[gibbsfromncis]

@startailcoon added 1h for a call to sync with Alex

[gibbsfromncis]

@nikandrovalex you have missed Asset selection (bitUSD, OPEN.BTC etc.) on withdrawal limit input.

[nikandrovalex]

@gibbsfromncis pls check

[abitmore]

The "monthly" option is tricky because the back end calculates periods in seconds only. Please either add a description about how the UI will implement it, or don't have that option.

[abitmore]

By the way, better have a "authorized from" label/box (perhaps read only) in the model.

[gibbsfromncis]

@abitmore what about the case if I want to create withdrawal permission for you and give a permission for myself to withdraw money from your account? Should we add "authorized from" input with ability to change it. And if currentAccount !== authorizedFrom (gibbs-from-ncis !== abit) we make a proposed transaction for you to give me a permission?