Skip to content

Commit

Permalink
Updates
Browse files Browse the repository at this point in the history
  • Loading branch information
@Ifropc
Ifropc committed Jan 30, 2024
1 parent a31de72 commit 75a9a89
Showing 1 changed file with 39 additions and 81 deletions.
120 changes: 39 additions & 81 deletions ecosystem/sep-0006.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down Expand Up @@ -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.

Expand Down Expand Up @@ -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:

Expand Down Expand Up @@ -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:

Expand Down Expand Up @@ -1054,55 +1050,39 @@ Request parameters:

The response should be a JSON object like:

```js
```json
{
"deposit": {
"USD": {
"enabled": true,
"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"
}
}
}
}
}
Expand All @@ -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": {
Expand All @@ -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": {
Expand Down Expand Up @@ -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.
Expand All @@ -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:

Expand All @@ -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.
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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
Expand Down

0 comments on commit 75a9a89

Please sign in to comment.