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.

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

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

Merged
merged 7 commits into from
Sep 17, 2019
Merged
Changes from all commits
Commits
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
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.
* Some wallets might exchange currencies only once they're ready to send the withdrawal payment, so 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.
* **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, since this greatly improves the user experience.
* 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. Most Stellar SDKs already support listening to all payment forms via streaming.
* Some wallets might exchange currencies only once they're ready to send the withdrawal payment, so there might be slight fluctuations of 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.
* **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