diff --git a/ecosystem/sep-0006.md b/ecosystem/sep-0006.md index c0616d565..e4ffcbaf6 100644 --- a/ecosystem/sep-0006.md +++ b/ecosystem/sep-0006.md @@ -420,7 +420,6 @@ Request Parameters: | `country_code` | string | (optional) The [ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) code of the user's current address. This field may be necessary for the anchor to determine what KYC information is necessary to collect. | | `claimable_balance_supported` | string | (optional) `true` if the client supports receiving deposit transactions as a claimable balance, `false` otherwise. | | `customer_id` | string | (optional) id of an off-chain account (managed by the anchor) associated with this user's Stellar account (identified by the JWT's `sub` field). If the anchor supports [SEP-12], the `customer_id` field should match the [SEP-12] customer's id. `customer_id` should be passed only when the off-chain id is know to the client, but the relationship between this id and the user's Stellar account is not known to the Anchor. | -| `extra` | object | (optional) Extra information passed to the anchor. For object schema refer to the [Extra Object Schema](#extra-object-chema) section | The request parameters also must include the required fields from the `/info` endpoint. @@ -727,7 +726,6 @@ Request parameters: | `refund_memo` | string | (optional) The memo the anchor must use when sending refund payments back to the user. If not specified, the anchor should use the same memo used by the user to send the original payment. If specified, `refund_memo_type` must also be specified. | | `refund_memo_type` | string | (optional) The type of the `refund_memo`. Can be `id`, `text`, or `hash`. See the [memos](https://developers.stellar.org/docs/encyclopedia/memos) documentation for more information. If specified, `refund_memo` must also be specified. | | `customer_id` | string | (optional) id of an off-chain account (managed by the anchor) associated with this user's Stellar account (identified by the JWT's `sub` field). If the anchor supports [SEP-12], the `customer_id` field should match the [SEP-12] customer's id. `customer_id` should be passed only when the off-chain id is know to the client, but the relationship between this id and the user's Stellar account is not known to the Anchor. | -| `extra` | object | (optional) Extra information passed to the anchor. For object schema refer to the [Extra Object Schema](#extra-object-chema) section | The request parameters also must include the required fields from the `/info` endpoint. @@ -830,7 +828,6 @@ Request Parameters: | `country_code` | string | (optional) The [ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) code of the user's current address. This field may be necessary for the anchor to determine what KYC information is necessary to collect. | | `claimable_balance_supported` | string | (optional) `true` if the client supports receiving deposit transactions as a claimable balance, `false` otherwise. | | `customer_id` | string | (optional) id of an off-chain account (managed by the anchor) associated with this user's Stellar account (identified by the JWT's `sub` field). If the anchor supports [SEP-12], the `customer_id` field should match the [SEP-12] customer's id. `customer_id` should be passed only when the off-chain id is know to the client, but the relationship between this id and the user's Stellar account is not known to the Anchor. | -| `extra` | object | (optional) Extra information passed to the anchor. For object schema refer to the [Extra Object Schema](#extra-object-chema) section | Examples: @@ -885,7 +882,6 @@ Request parameters: | `refund_memo` | string | (optional) The memo the anchor must use when sending refund payments back to the user. If not specified, the anchor should use the same memo used by the user to send the original payment. If specified, `refund_memo_type` must also be specified. | | `refund_memo_type` | string | (optional) The type of the `refund_memo`. Can be `id`, `text`, or `hash`. See the [memos](https://developers.stellar.org/docs/encyclopedia/memos) documentation for more information. If specified, `refund_memo` must also be specified. | | `customer_id` | string | (optional) id of an off-chain account (managed by the anchor) associated with this user's Stellar account (identified by the JWT's `sub` field). If the anchor supports [SEP-12], the `customer_id` field should match the [SEP-12] customer's id. `customer_id` should be passed only when the off-chain id is know to the client, but the relationship between this id and the user's Stellar account is not known to the Anchor. | -| `extra` | object | (optional) Extra information passed to the anchor. For object schema refer to the [Extra Object Schema](#extra-object-chema) section | Example: @@ -1054,7 +1050,7 @@ Request parameters: The response should be a JSON object like: -```js +```json { "deposit": { "USD": { @@ -1062,47 +1058,31 @@ The response should be a JSON object like: "authentication_required": true, "min_amount": 0.1, "max_amount": 1000, - "fields": { - "email_address" : { - "description": "your email address for transaction status updates", - "optional": true - }, - "amount" : { - "description": "amount in USD that you plan to deposit" - }, - "country_code": { - "description": "The ISO 3166-1 alpha-3 code of the user's current address", - "choices": ["USA", "PRI"] - }, - "type" : { - "description": "type of deposit to make", - "choices": ["SEPA", "SWIFT", "cash"] + "types": { + "location": { + "fields": { + "id": { + "description": "ID of location user must visit to pick up cash" + } + } } } }, "ETH": { "enabled": true, - "authentication_required": false, + "authentication_required": false } }, "deposit-exchange": { "USD": { "authentication_required": true, - "fields": { - "email_address" : { - "description": "your email address for transaction status updates", - "optional": true - }, - "amount" : { - "description": "amount in USD that you plan to deposit" - }, - "country_code": { - "description": "The ISO 3166-1 alpha-3 code of the user's current address", - "choices": ["USA", "PRI"] - }, - "type" : { - "description": "type of deposit to make", - "choices": ["SEPA", "SWIFT", "cash"] + "types": { + "location": { + "fields": { + "id": { + "description": "ID of location user must visit to pick up cash" + } + } } } } @@ -1114,18 +1094,6 @@ The response should be a JSON object like: "min_amount": 0.1, "max_amount": 1000, "types": { - "bank_account": { - "fields": { - "dest": {"description": "your bank account number" }, - "dest_extra": { "description": "your routing number" }, - "bank_branch": { "description": "address of your bank branch" }, - "phone_number": { "description": "your phone number in case there's an issue" }, - "country_code": { - "description": "The ISO 3166-1 alpha-3 code of the user's current address", - "choices": ["USA", "PRI"] - } - } - }, "cash": { "fields": { "dest": { @@ -1146,18 +1114,6 @@ The response should be a JSON object like: "min_amount": 0.1, "max_amount": 1000, "types": { - "bank_account": { - "fields": { - "dest": {"description": "your bank account number" }, - "dest_extra": { "description": "your routing number" }, - "bank_branch": { "description": "address of your bank branch" }, - "phone_number": { "description": "your phone number in case there's an issue" }, - "country_code": { - "description": "The ISO 3166-1 alpha-3 code of the user's current address", - "choices": ["USA", "PRI"] - } - } - }, "cash": { "fields": { "dest": { @@ -1198,10 +1154,16 @@ All assets listed in a `deposit` and `deposit-exchange` can contain these attrib - `authentication_required`: Optional. `true` if client must be [authenticated](#authentication) before accessing the deposit endpoint for this asset. `false` if not specified. - `fields` (**Deprecated**, Accepting personally identifiable information through request parameters is a security risk - due to web server request logging. KYC information should be supplied to the Anchor via SEP-12) `fields` object is + due to web server request logging. KYC information should be supplied to the Anchor via SEP-12. For extra fields `types` should be used) `fields` object is explained below. +- `types`: a field with each type of deposit supported for that asset as a key. Each type can specify a `fields` + object as below explaining what fields are needed and what they do. Anchors can define custom fields if + necessary. If a `types` object is not specified, the wallet should assume that no extra fields are needed for that + type of deposit. In the case that the Anchor requires additional fields for a deposit, it should set the + transaction status to `pending_customer_info_update`. The wallet can query the `/transaction` endpoint to get the + fields needed to complete the transaction in `required_customer_info_updates` and then use -Deposit assets listed in the `deposit` object can also contain the attributes: +- Deposit assets listed in the `deposit` object can also contain the attributes: - `fee_fixed`: Optional fixed (flat) fee for deposit, in units of the Stellar asset. Leave blank if there is no fee or the fee schedule is complex. @@ -1218,13 +1180,12 @@ All assets listed in a `withdraw` and `withdraw-exchange` can contain these attr - `authentication_required`: Optional. `true` if client must be [authenticated](#authentication) before accessing the withdraw endpoint for this asset. `false` if not specified. - `types`: a field with each type of withdrawal supported for that asset as a key. Each type can specify a `fields` - object as below explaining what fields are needed and what they do. Anchors are encouraged to use - [SEP-9 financial account fields](sep-0009.md#financial-account-fields), but can also define custom fields if - necessary. If a `fields` object is not specified, the wallet should assume that no extra fields are needed for that + object as below explaining what fields are needed and what they do. Anchors can define custom fields if + necessary. If a `types` object is not specified, the wallet should assume that no extra fields are needed for that type of withdrawal. In the case that the Anchor requires additional fields for a withdrawal, it should set the transaction status to `pending_customer_info_update`. The wallet can query the `/transaction` endpoint to get the fields needed to complete the transaction in `required_customer_info_updates` and then use - [SEP-12](sep-0012.md#customer-put) to collect the information from the user. + [SEP-12](sep-0012.md#customer-put) to collect the information from the user, including financial fields and KYC information. Withdrawal assets listed in the `withdraw` object can also contain the attributes: @@ -1237,13 +1198,18 @@ Withdrawal assets listed in the `withdraw` object can also contain the attribute #### Fields -The `fields` object allows an anchor to describe fields that are passed into `/deposit`, `/withdraw`, -`/deposit-exchange` and/or `/withdraw-exchange`. It can explain standard fields like `dest` and `dest_extra` for -withdrawals, as well as extra fields that could be needed for all deposit and withdrawal endpoints such as an email -address or bank name. If a field is part of the KYC/AML flow handled by SEP-12 or the field is handled by the Anchor's -interactive deposit/withdrawal flow, there's no need to list it in `/info`. Only fields that are passed to `/deposit`, +The `fields` object allows an anchor to describe additional fields that are passed into `/deposit`, `/withdraw`, +`/deposit-exchange` and/or `/withdraw-exchange`. Anchors may support arbitrary fields to be passed in this requests, +which are not covered by the current protocol. + +If a field is part of the KYC/AML flow handled by SEP-12 or the field is handled by the Anchor's +interactive deposit/withdrawal flow, there's no need to list it in `/info`. Only additional fields that are passed to `/deposit`, `/withdraw`, `/deposit-exchange` or `/withdraw-exchange` need to appear here. +Note, that `fields` should only be used to collect the ***transactional*** data, and **not** the ***customer*** data. For latter, [SEP-12] +should be used. An example of the transactional data would be a location user must visit to pick up the cash. This can vary from +transaction to transaction, while customer's KYC data should be the same between transactions. + The `fields` object contains a key for each field name and an object with the following fields as the value: - `description`: description of field to show to user. @@ -1610,16 +1576,6 @@ body should contain error details. For example: } ``` -### Extra object schema - -This object is used to pass any additional info to the anchor. Anchors are free to add any field to this object. Anchors -should notify wallets about fields they are expecting to receive. However, it's recommended to submit a change to this -document to highlight to wallets all possible fields of the `extra` object. - -| Name | Type | Description | -| ------------- | ------ | ---------------------------------------------------------- | -| `location_id` | string | ID of the location chosen by the user to pick up the cash. | - ## Single Historical Transaction The transaction endpoint enables clients to query/validate a specific transaction at an anchor. @@ -1750,10 +1706,12 @@ object containing an error message. - Flutter SDK: https://github.com/Soneso/stellar_flutter_sdk/blob/master/documentation/sdk_examples/sep-0006-transfer.md - PHP SDK: https://github.com/Soneso/stellar-php-sdk/blob/main/examples/sep-0006-transfer.md +[SEP-12]: sep-0012.md [SEP-38]: sep-0038.md ## Changelog +- `v3.25.0`: Update `/info/` endpoint's `types` description and add `types` to deposit flows. ([#g]()) - `v3.24.1`: Get required KYC fields from transaction object only ([#1420](https://github.com/stellar/stellar-protocol/pull/1420)) - `v3.24.0`: Make `account_id` optional in withdraw response