Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Improve withdrawal flow on wallets that enable cross-border payments #404

Merged
merged 7 commits into from
Sep 17, 2019
Merged

Improve withdrawal flow on wallets that enable cross-border payments #404

Changes from 5 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
52d4d4e
Update anchor recommendations to accommodate CBP use cases
accordeiro Sep 16, 2019
19a2e95
Add exchange rate fluctuation edge case docs
accordeiro Sep 16, 2019
69484b4
Add SEP6 anchor guidance for accepting all payment ops
accordeiro Sep 16, 2019
4b89669
Add minor textual improvements to SEP6
accordeiro Sep 16, 2019
ac07caa
Address #404 feedback
accordeiro Sep 17, 2019
266b264
Address #404 review
accordeiro Sep 17, 2019
b132fbf
Final #404 tweak
accordeiro Sep 17, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 8 additions & 3 deletions ecosystem/sep-0006.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,8 +6,8 @@ Title: Anchor/Client interoperability
Author: SDF
Status: Active
Created: 2017-10-30
Updated: 2019-07-08
Version 3.0.0
Updated: 2019-09-16
Version 3.1.0
```

## Simple Summary
Expand Down Expand Up @@ -102,6 +102,7 @@ SEP-6 lays out many options for how deposit and withdrawal can work. These are r
* Provide an interface to the user that allows them to view the withdrawal details including the computed fee. The user can confirm and then the wallet will initiate the withdrawal by sending the Stellar payment to the address provided by the issuer.
* If the anchor responds with an interactive flow, handle it as [described in detail](#3-customer-information-needed-interactive).
* For now, do not handle the non-interactive or status responses to the `/withdraw` request.
* For wallets that enable cross-border payments: exchange rate fluctuations might require withdrawal values to slightly vary from the originally provided `amount`. Anchors are instructed to accept a variation of ±10% between the informed `amount` and the actual value sent to the anchor's Stellar account. The withdrawn amount will be adjusted accordingly.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

make the same type of "Some wallets" change here too and we should be good to go

* **Transaction history**
* It provides a better experience for users to show deposits or withdrawals they've completed in the past via the `/transactions` endpoint, but it's not strictly necessary.

Expand All @@ -115,12 +116,16 @@ SEP-6 lays out many options for how deposit and withdrawal can work. These are r
* To start an interactive flow, provide the [Customer info needed response](#3-customer-information-needed-interactive).
* Include the `id` field in your response so the wallet can check up on the status of the transaction if it wants.
* Also include the `id` field in the popup URL you provide to the wallet. This allows you to keep track of the transaction when the user visits the URL.
* Make sure to pass along the `amount` to the popup URL, especially on the `/withdraw` flow.
* We recommend you use [SEP-10 authentication](#authentication) in the interactive flow and do not separately prompt for password to achieve a good user experience (although asking for MFA when confirming a transaction or requiring email confirmation is reasonable). Be sure to accept the [`jwt` parameter](#adding-parameters-to-the-url) so the user does not have to re-login. Support the `callback` parameter as well.
* Test your interactive flows on mobile. They should be easy to use on all devices: make them responsive, handle auto-fill well, and do smart keyboard management on mobile devices.
* **Interactive deposit**
* Your interactive deposit popup will do everything needed to initiate the deposit without the user needing to interact with the wallet further. It should either directly initiate the deposit, or handle displaying information (such as reference number or bank account number) that the user will need to complete their deposit.
* **Interactive withdrawal**
* Your withdrawal flow will have to pass control back to the user's wallet, so it can initiate the withdrawal with a Stellar payment to your withdrawal address. You'll need to communicate the withdrawal address, amount and status to the wallet using the [`callback` parameter](#adding-parameters-to-the-url), and also by making it available on your `/transaction` endpoint. See [details](#guidance-for-wallets-completing-an-interactive-withdrawal).
* If an `amount` parameter is provided to the interactive URL, make sure to use that value to pre-populate the amount on the interactive form. This greatly improves the user experience, especially in wallets that enable cross-border payments.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Remove the reference to cross-border payments here

* In order to fulfill a withdrawal, a wallet must make a payment to the Stellar address that the anchor provides. It is the anchor's job to watch for Stellar payments to the given address and make the external transaction as soon as they're detected. It is recommended for anchors to listen to at least `payment` and `path_payment` [operations](https://www.stellar.org/developers/horizon/reference/endpoints/payments-all.html), although supporting the remaining ones is important for covering all use cases.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It is recommended for anchors to listen to at least payment and path_payment

Should we mention our SDKs do this for our /payment streaming endpoints already?

* When the wallet is exchanging relatively unstable currencies, there might be slight fluctuations on value between the informed withdrawal `amount` and the actual transferred amount. It is recommended for anchors to accept an amount fluctuation of up to ±10%, and adjust the amount to be transferred (and fees) to reflect the actual value received.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd like to make this section a little clearer that the unstable currencies isn't something the anchor needs to worry about, but they should expect that the amount requested to withdraw might not be the exact amount they receive, and they should be flexible.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd prefer to say "Some wallets might..." to be clear that this isn't something that always happens, and just a feature some wallets add

* **Providing transaction status**
* Provide the `/transaction` endpoint. The wallet may rely on it to complete interactive withdrawals.
* Provide the `/transactions` endpoint. Users like to see transaction histories.
Expand Down Expand Up @@ -420,7 +425,7 @@ The wallet must use the response fields in the following way to complete the wit
- `withdraw_anchor_account`: send the withdrawal payment to this Stellar account.
- `withdraw_memo`: (if specified) use this memo in the payment transaction to the anchor.
- `withdraw_memo_type`: use this as the memo type.
- `amount_in`: the amount expected in the stellar payment.
- `amount_in`: the amount expected in the Stellar payment.

The next step is for the wallet to display a confirmation screen summarizing the withdrawal to the user, and then send a Stellar payment to `withdraw_anchor_account`. The wallet should show the following info to the user:

Expand Down