From a31de72afbb055dbe3917a654b1480e97b5cb4f2 Mon Sep 17 00:00:00 2001 From: Gleb Date: Fri, 26 Jan 2024 16:51:12 -0800 Subject: [PATCH] SEP-6-extra --- ecosystem/sep-0006.md | 54 +++++++++++++++++++++++++++---------------- 1 file changed, 34 insertions(+), 20 deletions(-) diff --git a/ecosystem/sep-0006.md b/ecosystem/sep-0006.md index 7212fdb62..c0616d565 100644 --- a/ecosystem/sep-0006.md +++ b/ecosystem/sep-0006.md @@ -420,6 +420,7 @@ 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. @@ -726,6 +727,7 @@ 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. @@ -828,6 +830,7 @@ 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: @@ -862,26 +865,27 @@ GET TRANSFER_SERVER/withdraw-exchange Request parameters: -| Name | Type | Description | -| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `source_asset` | string | Code of the on-chain asset the user wants to withdraw. The value passed must match one of the codes listed in the [/info](#info) response's `withdraw-exchange` object. | -| `destination_asset` | string | The off-chain asset the Anchor will deliver to the user's account. The value must match one of the `asset` values included in a [`SEP-38 GET /prices?sell_asset=stellar::`](sep-0038.md#get-prices) response using [SEP-38 Asset Identification Format](sep-0038.md#asset-identification-format). | -| `quote_id` | string | (optional) The `id` returned from a `SEP-38 POST /quote` response. If this parameter is provided and the Stellar transaction used to send the asset to the Anchor has a [`created_at`](https://developers.stellar.org/api/resources/transactions/object/) timestamp earlier than the quote's `expires_at` attribute, the Anchor should respect the conversion rate agreed in that quote. If the values of `destination_asset`, `source_asset` and `amount` conflict with the ones used to create the [SEP-38] quote, this request should be rejected with a `400`. | -| `amount` | string | The amount of the on-chain asset (`source_asset`) the user would like to send to the anchor's Stellar account. This field may be necessary for the anchor to determine what KYC information is necessary to collect. Should be equals to `quote.sell_amount` if a `quote_id` was used. | -| `type` | string | Type of withdrawal. Can be: `crypto`, `bank_account`, `cash`, `mobile`, `bill_payment` or other custom values. This field may be necessary for the anchor to determine what KYC information is necessary to collect. | -| `dest` | string | (**Deprecated**, [see note](#dest--dest_extra-parameters)) The account that the user wants to withdraw their funds to. This can be a crypto account, a bank account number, IBAN, mobile number, or email address. | -| `dest_extra` | string | (**Deprecated**, [see note](#dest--dest_extra-parameters), optional) Extra information to specify withdrawal location. For crypto it may be a memo in addition to the `dest` address. It can also be a routing number for a bank, a BIC, or the name of a partner handling the withdrawal. | -| `account` | `G...` or `M...` string | (optional) The Stellar or muxed account of the user that wants to do the withdrawal. This is only needed if the anchor requires KYC information for withdrawal and SEP-10 authentication is not used. Instead, the anchor can use `account` to look up the user's KYC information. Note that the account specified in this request could differ from the account authenticated via SEP-10. | -| `memo` | string | (optional) This field should only be used if SEP-10 authentication is not. It was originally intended to distinguish users of the same Stellar account. However if SEP-10 is supported, the anchor should use the `sub` value included in the decoded SEP-10 JWT instead. See the [Shared Account Authentication](#shared-omnibus-or-pooled-accounts) section for more information. | -| `memo_type` | string | (**Deprecated**, optional) Type of `memo`. One of `text`, `id` or `hash`. Deprecated because memos used to identify users of the same Stellar account should always be of type of `id`. | -| `wallet_name` | string | (**deprecated**,optional) In communications / pages about the withdrawal, anchor should display the wallet name to the user to explain where funds are coming from. However, anchors should use client_domain (for non-custodial) and `sub` value of JWT (for custodial) to determine wallet information. | -| `wallet_url` | string | (**deprecated**,optional) Anchor can show this to the user when referencing the wallet involved in the withdrawal (ex. in the anchor's transaction history). However, anchors should use client_domain (for non-custodial) and `sub` value of JWT (for custodial) to determine wallet information. | -| `lang` | string | (optional) Defaults to `en` if not specified or if the specified language is not supported. Language code specified using [RFC 4646]. `error` fields and other human readable messages in the response should be in this language. | -| `on_change_callback` | string | (optional) A URL that the anchor should `POST` a JSON message to when the `status` property of the transaction created as a result of this request changes. The JSON message should be identical to the response format for the [/transaction](#single-historical-transaction) endpoint. The callback needs to be signed by the anchor and the signature needs to be verified by the wallet according to the [callback signature specification](#callback-signature). | -| `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. | -| `refund_memo` | (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` | (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. | +| Name | Type | Description | +| -------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `source_asset` | string | Code of the on-chain asset the user wants to withdraw. The value passed must match one of the codes listed in the [/info](#info) response's `withdraw-exchange` object. | +| `destination_asset` | string | The off-chain asset the Anchor will deliver to the user's account. The value must match one of the `asset` values included in a [`SEP-38 GET /prices?sell_asset=stellar::`](sep-0038.md#get-prices) response using [SEP-38 Asset Identification Format](sep-0038.md#asset-identification-format). | +| `quote_id` | string | (optional) The `id` returned from a `SEP-38 POST /quote` response. If this parameter is provided and the Stellar transaction used to send the asset to the Anchor has a [`created_at`](https://developers.stellar.org/api/resources/transactions/object/) timestamp earlier than the quote's `expires_at` attribute, the Anchor should respect the conversion rate agreed in that quote. If the values of `destination_asset`, `source_asset` and `amount` conflict with the ones used to create the [SEP-38] quote, this request should be rejected with a `400`. | +| `amount` | string | The amount of the on-chain asset (`source_asset`) the user would like to send to the anchor's Stellar account. This field may be necessary for the anchor to determine what KYC information is necessary to collect. Should be equals to `quote.sell_amount` if a `quote_id` was used. | +| `type` | string | Type of withdrawal. Can be: `crypto`, `bank_account`, `cash`, `mobile`, `bill_payment` or other custom values. This field may be necessary for the anchor to determine what KYC information is necessary to collect. | +| `dest` | string | (**Deprecated**, [see note](#dest--dest_extra-parameters)) The account that the user wants to withdraw their funds to. This can be a crypto account, a bank account number, IBAN, mobile number, or email address. | +| `dest_extra` | string | (**Deprecated**, [see note](#dest--dest_extra-parameters), optional) Extra information to specify withdrawal location. For crypto it may be a memo in addition to the `dest` address. It can also be a routing number for a bank, a BIC, or the name of a partner handling the withdrawal. | +| `account` | `G...` or `M...` string | (optional) The Stellar or muxed account of the user that wants to do the withdrawal. This is only needed if the anchor requires KYC information for withdrawal and SEP-10 authentication is not used. Instead, the anchor can use `account` to look up the user's KYC information. Note that the account specified in this request could differ from the account authenticated via SEP-10. | +| `memo` | string | (optional) This field should only be used if SEP-10 authentication is not. It was originally intended to distinguish users of the same Stellar account. However if SEP-10 is supported, the anchor should use the `sub` value included in the decoded SEP-10 JWT instead. See the [Shared Account Authentication](#shared-omnibus-or-pooled-accounts) section for more information. | +| `memo_type` | string | (**Deprecated**, optional) Type of `memo`. One of `text`, `id` or `hash`. Deprecated because memos used to identify users of the same Stellar account should always be of type of `id`. | +| `wallet_name` | string | (**deprecated**,optional) In communications / pages about the withdrawal, anchor should display the wallet name to the user to explain where funds are coming from. However, anchors should use client_domain (for non-custodial) and `sub` value of JWT (for custodial) to determine wallet information. | +| `wallet_url` | string | (**deprecated**,optional) Anchor can show this to the user when referencing the wallet involved in the withdrawal (ex. in the anchor's transaction history). However, anchors should use client_domain (for non-custodial) and `sub` value of JWT (for custodial) to determine wallet information. | +| `lang` | string | (optional) Defaults to `en` if not specified or if the specified language is not supported. Language code specified using [RFC 4646]. `error` fields and other human readable messages in the response should be in this language. | +| `on_change_callback` | string | (optional) A URL that the anchor should `POST` a JSON message to when the `status` property of the transaction created as a result of this request changes. The JSON message should be identical to the response format for the [/transaction](#single-historical-transaction) endpoint. The callback needs to be signed by the anchor and the signature needs to be verified by the wallet according to the [callback signature specification](#callback-signature). | +| `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. | +| `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: @@ -1606,6 +1610,16 @@ 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.