diff --git a/ecosystem/sep-0006.md b/ecosystem/sep-0006.md index 5aa6873f7..66e881c00 100644 --- a/ecosystem/sep-0006.md +++ b/ecosystem/sep-0006.md @@ -6,8 +6,8 @@ Title: Deposit and Withdrawal API Author: SDF Status: Active (Interactive components are deprecated in favor of SEP-24) Created: 2017-10-30 -Updated: 2024-02-09 -Version 3.26.0 +Updated: 2024-02-21 +Version 4.0.0 ``` ## Simple Summary @@ -74,16 +74,6 @@ sequenceDiagram Anchor-->>Anchor: verifies challenge Anchor-->>-Wallet: authentication token - - note right of Wallet: If User has already
been accepted,
KYC is unnecessary. - Wallet->>+Anchor: GET [SEP-12]/customer?type= - Anchor-->>-Wallet: fields required - Wallet->>+User: requests fields - User-->>-Wallet: provides field values - Wallet->>+Anchor: PUT [SEP-12]/customer?type= - Anchor-->>Anchor: validates KYC values - Anchor-->>-Wallet: id, ACCEPTED - Wallet->>+Anchor: GET [SEP-38]/price Anchor-->>-Wallet: exchange rate Wallet->>+User: provides estimated rate @@ -93,10 +83,19 @@ sequenceDiagram Wallet->>+Anchor: GET [SEP-6]/withdraw Anchor-->>Anchor: checks customer statuses,
links quote,
creates transaction record - Anchor-->>-Wallet: transaction id, receiving account & memo + Anchor-->>-Wallet: transaction id + + note right of Wallet: If User has already
been accepted,
KYC is unnecessary. + Wallet->>+Anchor: GET [SEP-12]/customer?transaction_id=&type= + Anchor-->>-Wallet: fields required + Wallet->>+User: requests fields + User-->>-Wallet: provides field values + Wallet->>+Anchor: PUT [SEP-12]/customer?transaction_id=type= + Anchor-->>Anchor: validates KYC values + Anchor-->>-Wallet: id, ACCEPTED Wallet->>+Anchor: GET [SEP-6]/transaction?id= - Anchor-->>-Wallet: transaction object containing amount_in + Anchor-->>-Wallet: transaction object containing amount_in, receving account, memo note right of Wallet: Use the info amount_in returned
from GET [SEP-6]/transaction?id={id}
to make the stellar payment. Wallet->>+Stellar: submit Stellar payment @@ -771,16 +770,19 @@ The response body should be a JSON object with the following fields: | `account_id` | `G...` string | (optional) The account the user should send its token back to. This field can be omitted if the anchor cannot provide this information at the time of the request. | In this case, the wallet should query the [`/transaction`](#single-historical-transaction) endpoint to get this -asynchonously. `memo_type` | string | (optional) Type of memo to attach to transaction, one of `text`, `id` or `hash`. -`memo` | string | (optional) Value of memo to attach to transaction, for `hash` this should be base64-encoded. The -anchor should use this memo to match the Stellar transaction with the database entry associated created to represent it. -`id` | string | (optional) The anchor's ID for this withdrawal. The wallet will use this ID to query the -[`/transaction`](#single-historical-transaction) endpoint to check status of the request. `eta` | int | (optional) -Estimate of how long the withdrawal will take to credit in seconds. `min_amount` | float | (optional) Minimum amount of -an asset that a user can withdraw. `max_amount` | float | (optional) Maximum amount of asset that a user can withdraw. -`fee_fixed` | float | (optional) If there is a fee for withdraw. In units of the withdrawn asset. `fee_percent` | float -| (optional) If there is a percent fee for withdraw. `extra_info` | object | (optional) Any additional data needed as an -input for this withdraw, example: Bank Name. +asynchonously. + +| name | type | description | +| ------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `memo_type` | string | (optional) Type of memo to attach to transaction, one of `text`, `id` or `hash`. | +| `memo` | string | (optional) Value of memo to attach to transaction, for `hash` this should be base64-encoded. The anchor should use this memo to match the Stellar transaction with the database entry associated created to represent it. | +| `id` | string | (optional) The anchor's ID for this withdrawal. The wallet will use this ID to query the [`/transaction`](#single-historical-transaction) endpoint to check status of the request. | +| `eta` | int | ( Estimate of how long the withdrawal will take to credit in seconds. | +| `min_amount` | float | (optional) Minimum amount of an asset that a user can withdraw. | +| `max_amount` | float | (optional) Maximum amount of asset that a user can withdraw. | +| `fee_fixed` | float | (optional) If there is a fee for withdraw. In units of the withdrawn asset. | +| `fee_percent` | float | (optional) If there is a percent fee for withdraw. | +| `extra_info` | object | (optional) Any additional data needed as an input for this withdraw, example: Bank Name. | Example: @@ -865,26 +867,26 @@ 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. | | `location_id` | string | (optional) id of the chosen location to pick up cash | Example: @@ -905,6 +907,11 @@ The expected response as well as the special cases are the same ones covered in ### Customer information needed (non-interactive) +#### Deprecated + +This response branch has been deprecated. Anchors should return 200 with transaction status set to +`pending_customer_info_update` + Response code: `403 Forbidden` If the anchor needs more information about the customer and all the information can be received non-interactively via @@ -931,6 +938,11 @@ Example: ### 3. Customer Information Status +### Deprecated + +This response branch has been deprecated. Anchors should return 200 with transaction status set to +`pending_customer_info_update` + Response code: `403 Forbidden` An anchor should use this response if customer information was submitted for the `account`, but the information is @@ -974,8 +986,12 @@ object passed in the callback request, or the wallet can poll the anchor's `GET transaction object using the `memo` and `memo_type` used in the deposit request or withdraw success response. If transaction response object has a JSON `status` field set to `incomplete`, it means the user still needs to be KYC'ed -using [SEP-12](sep-0012.md). In this case, the wallet should collect the fields requested in the -`non_interactive_customer_info_needed` response and send them back to the anchor. +using [SEP-12](sep-0012.md). In this case, the wallet should collect the fields with either: + +1. Calling `GET /customer` request with an appropriate `transaction_id` set in the request, and providing fields via + `PUT /customer`. For more information, refer to [pending customer info update](pending-customer-info-update) section. +2. **Deprecated** approach of using fields requested in the `non_interactive_customer_info_needed` response and send + them back to the anchor. The wallet must use the response fields in the following way to complete the withdrawal: @@ -1286,6 +1302,8 @@ all features provided the best user experience. ## Fee +#### Deprecated + **This endpoint is deprecated. The [SEP-38] `GET /price` endpoint should be used to fetch fees instead.** The fee endpoint allows an anchor to report the fee that would be charged when using the `/deposit` or `/withdraw` @@ -1381,44 +1399,42 @@ On success the endpoint should return `200 OK` HTTP status code and a JSON objec Each object in the `transactions` array should have the following fields: -| Name | Type | Description | -| -------------------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `id` | string | Unique, anchor-generated id for the deposit/withdrawal. | -| `kind` | string | `deposit`, `deposit-exchange`, `withdrawal` or `withdrawal-exchange`. | -| `status` | string | Processing status of deposit/withdrawal. | -| `status_eta` | number | (optional) Estimated number of seconds until a status change is expected. | -| `more_info_url` | string | (optional) A URL the user can visit if they want more information about their account / status. | -| `amount_in` | string | (optional) Amount received by anchor at start of transaction as a string with up to 7 decimals. Excludes any fees charged before the anchor received the funds. Should be equals to `quote.sell_asset` if a `quote_id` was used. | -| `amount_in_asset` | string | (optional) The asset received or to be received by the Anchor. Must be present if the deposit/withdraw was made using quotes. The value must be in [SEP-38 Asset Identification Format](sep-0038.md#asset-identification-format). | -| `amount_out` | string | (optional) Amount sent by anchor to user at end of transaction as a string with up to 7 decimals. Excludes amount converted to XLM to fund account and any external fees. Should be equals to `quote.buy_asset` if a `quote_id` was used. | -| `amount_out_asset` | string | (optional) The asset delivered or to be delivered to the user. Must be present if the deposit/withdraw was made using quotes. The value must be in [SEP-38 Asset Identification Format](sep-0038.md#asset-identification-format). | -| `amount_fee` | string | (**deprecated**, optional) Amount of fee charged by anchor. Should be equals to `quote.fee.total` if a `quote_id` was used. | -| `amount_fee_asset` | string | (**deprecated**, optional) The asset in which fees are calculated in. Must be present if the deposit/withdraw was made using quotes. The value must be in [SEP-38 Asset Identification Format](sep-0038.md#asset-identification-format). Should be equals to `quote.fee.asset` if a `quote_id` was used. | +| Name | Type | Description | +| ------------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `id` | string | Unique, anchor-generated id for the deposit/withdrawal. | +| `kind` | string | `deposit`, `deposit-exchange`, `withdrawal` or `withdrawal-exchange`. | +| `status` | string | Processing status of deposit/withdrawal. | +| `status_eta` | number | (optional) Estimated number of seconds until a status change is expected. | +| `more_info_url` | string | (optional) A URL the user can visit if they want more information about their account / status. | +| `amount_in` | string | (optional) Amount received by anchor at start of transaction as a string with up to 7 decimals. Excludes any fees charged before the anchor received the funds. Should be equals to `quote.sell_asset` if a `quote_id` was used. | +| `amount_in_asset` | string | (optional) The asset received or to be received by the Anchor. Must be present if the deposit/withdraw was made using quotes. The value must be in [SEP-38 Asset Identification Format](sep-0038.md#asset-identification-format). | +| `amount_out` | string | (optional) Amount sent by anchor to user at end of transaction as a string with up to 7 decimals. Excludes amount converted to XLM to fund account and any external fees. Should be equals to `quote.buy_asset` if a `quote_id` was used. | +| `amount_out_asset` | string | (optional) The asset delivered or to be delivered to the user. Must be present if the deposit/withdraw was made using quotes. The value must be in [SEP-38 Asset Identification Format](sep-0038.md#asset-identification-format). | +| `amount_fee` | string | (**deprecated**, optional) Amount of fee charged by anchor. Should be equals to `quote.fee.total` if a `quote_id` was used. | +| `amount_fee_asset` | string | (**deprecated**, optional) The asset in which fees are calculated in. Must be present if the deposit/withdraw was made using quotes. The value must be in [SEP-38 Asset Identification Format](sep-0038.md#asset-identification-format). Should be equals to `quote.fee.asset` if a `quote_id` was used. | | `fee_details` | object | Description of fee charged by the anchor. The schema for this object is defined in the [Fee Details Object Schema](#fee-details-object-schema) section below. If `quote_id` is present, it should match the referenced quote's `fee` object. | -| `quote_id` | string | (optional) The ID of the quote used to create this transaction. Should be present if a `quote_id` was included in the `POST /transactions` request. Clients should be aware though that the `quote_id` may not be present in older implementations. | -| `from` | string | (optional) Sent from address (perhaps BTC, IBAN, or bank account in the case of a deposit, Stellar address in the case of a withdrawal). | -| `to` | string | (optional) Sent to address (perhaps BTC, IBAN, or bank account in the case of a withdrawal, Stellar address in the case of a deposit). | -| `external_extra` | string | (optional) Extra information for the external account involved. It could be a bank routing number, BIC, or store number for example. | -| `external_extra_text` | string | (optional) Text version of `external_extra`. This is the name of the bank or store. | -| `deposit_memo` | string | (optional) If this is a deposit, this is the memo (if any) used to transfer the asset to the `to` Stellar address | -| `deposit_memo_type` | string | (optional) Type for the `deposit_memo`. | -| `withdraw_anchor_account` | string | (optional) If this is a withdrawal, this is the anchor's Stellar account that the user transferred (or will transfer) their issued asset to. | -| `withdraw_memo` | string | (optional) Memo used when the user transferred to `withdraw_anchor_account`. | -| `withdraw_memo_type` | string | (optional) Memo type for `withdraw_memo`. | -| `started_at` | UTC ISO 8601 string | (optional) Start date and time of transaction. | -| `updated_at` | UTC ISO 8601 string | (optional) The date and time of transaction reaching the current status. | -| `completed_at` | UTC ISO 8601 string | (optional) Completion date and time of transaction. | -| `stellar_transaction_id` | string | (optional) transaction_id on Stellar network of the transfer that either completed the deposit or started the withdrawal. | -| `external_transaction_id` | string | (optional) ID of transaction on external network that either started the deposit or completed the withdrawal. | -| `message` | string | (optional) Human readable explanation of transaction status, if needed. | -| `refunded` | boolean | (**deprecated**, optional) This field is deprecated in favor of the `refunds` object. True if the transaction was refunded in full. False if the transaction was partially refunded or not refunded. For more details about any refunds, see the `refunds` object. | -| `refunds` | object | (optional) An object describing any on or off-chain refund associated with this transaction. The schema for this object is defined in the [Refunds Object Schema](#refunds-object-schema) section below. | -| `required_info_message` | string | (optional) A human-readable message indicating any errors that require updated information from the user. | -| `required_info_updates` | object | (optional) A set of fields that require update from the user described in the same format as [/info](#info). This field is only relevant when `status` is `pending_transaction_info_update`. | -| `required_customer_info_message` | string | (optional) A human-readable message indicating why the SEP-12 information provided by the user is not sufficient to complete the transaction. | -| `required_customer_info_updates` | object | (optional) A set of SEP-9 fields that require update from the user via SEP-12. This field is only relevant when `status` is `pending_customer_info_update`. | -| `instructions` | object | (optional) JSON object containing the [SEP-9 financial account fields](sep-0009.md#financial-account-fields) that describe how to complete the off-chain deposit in the same format as the [/deposit](#deposit) response. This field should be present if the `instructions` were provided in the [/deposit](#deposit) response or if it could not have been previously provided synchronously. This field should only be present once the status becomes `pending_user_transfer_start`, not while the transaction has any statuses that precede it such as `incomplete`, `pending_anchor`, or `pending_customer_info_update`. | -| `claimable_balance_id` | string | (optional) ID of the Claimable Balance used to send the asset initially requested. Only relevant for deposit transactions. | +| `quote_id` | string | (optional) The ID of the quote used to create this transaction. Should be present if a `quote_id` was included in the `POST /transactions` request. Clients should be aware though that the `quote_id` may not be present in older implementations. | +| `from` | string | (optional) Sent from address (perhaps BTC, IBAN, or bank account in the case of a deposit, Stellar address in the case of a withdrawal). | +| `to` | string | (optional) Sent to address (perhaps BTC, IBAN, or bank account in the case of a withdrawal, Stellar address in the case of a deposit). | +| `external_extra` | string | (optional) Extra information for the external account involved. It could be a bank routing number, BIC, or store number for example. | +| `external_extra_text` | string | (optional) Text version of `external_extra`. This is the name of the bank or store. | +| `deposit_memo` | string | (optional) If this is a deposit, this is the memo (if any) used to transfer the asset to the `to` Stellar address | +| `deposit_memo_type` | string | (optional) Type for the `deposit_memo`. | +| `withdraw_anchor_account` | string | (optional) If this is a withdrawal, this is the anchor's Stellar account that the user transferred (or will transfer) their issued asset to. | +| `withdraw_memo` | string | (optional) Memo used when the user transferred to `withdraw_anchor_account`. | +| `withdraw_memo_type` | string | (optional) Memo type for `withdraw_memo`. | +| `started_at` | UTC ISO 8601 string | (optional) Start date and time of transaction. | +| `updated_at` | UTC ISO 8601 string | (optional) The date and time of transaction reaching the current status. | +| `completed_at` | UTC ISO 8601 string | (optional) Completion date and time of transaction. | +| `stellar_transaction_id` | string | (optional) transaction_id on Stellar network of the transfer that either completed the deposit or started the withdrawal. | +| `external_transaction_id` | string | (optional) ID of transaction on external network that either started the deposit or completed the withdrawal. | +| `message` | string | (optional) Human readable explanation of transaction status, if needed. | +| `refunded` | boolean | (**deprecated**, optional) This field is deprecated in favor of the `refunds` object. True if the transaction was refunded in full. False if the transaction was partially refunded or not refunded. For more details about any refunds, see the `refunds` object. | +| `refunds` | object | (optional) An object describing any on or off-chain refund associated with this transaction. The schema for this object is defined in the [Refunds Object Schema](#refunds-object-schema) section below. | +| `required_info_message` | string | (optional) A human-readable message indicating any errors that require updated information from the user. | +| `required_info_updates` | object | (optional) A set of fields that require update from the user described in the same format as [/info](#info). This field is only relevant when `status` is `pending_transaction_info_update`. | +| `instructions` | object | (optional) JSON object containing the [SEP-9 financial account fields](sep-0009.md#financial-account-fields) that describe how to complete the off-chain deposit in the same format as the [/deposit](#deposit) response. This field should be present if the `instructions` were provided in the [/deposit](#deposit) response or if it could not have been previously provided synchronously. This field should only be present once the status becomes `pending_user_transfer_start`, not while the transaction has any statuses that precede it such as `incomplete`, `pending_anchor`, or `pending_customer_info_update`. | +| `claimable_balance_id` | string | (optional) ID of the Claimable Balance used to send the asset initially requested. Only relevant for deposit transactions. | `status` should be one of: @@ -1693,8 +1709,15 @@ details. For example: In certain cases the anchor may need updated customer information from the user. For example, the bank could tell the anchor that the account address does not match the user's name or other identifying information. Since this information was sent via SEP-12, the transaction should go into the `pending_customer_info_update` status until the sender makes -another `PUT /customer` request to update by providing the list of fields from `required_customer_info_updates` in the -transaction object. +another `PUT /customer` request to update by providing the list of fields from `GET /customer` (with setting appropriate +`transaction_id` in the request) The process of providing information to the anchor looks as follows: + +1. `GET /transaction` and verify transaction status is `pending_customer_info_update` +2. Get required fields via [SEP-12] `GET /customer` request. Note, that you must pass `transaction_id` as part of the + request. +3. Collect user input for the required fields and use [SEP-12] `PUT /customer` endpoint to transfer the data +4. Repeat steps 2-3 until customer's response status becomes `ACCEPTED` +5. `GET /transaction` should transition into `pending_user_transfer_start` status. ## Pending Transaction Info Update @@ -1757,10 +1780,13 @@ 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 +- `v4.0.0`: Update flow to delegate getting KYC fields to SEP-12 + ([#1432](https://github.com/stellar/stellar-protocol/pull/1431)) - `v3.26.0`: Add `location_id` to deposit/withdrawal requests ([#1433](https://github.com/stellar/stellar-protocol/pull/1433)) - `v3.25.0` Add `fee_details` field to the transaction object [#1429](https://github.com/stellar/stellar-protocol/pull/1429) diff --git a/ecosystem/sep-0012.md b/ecosystem/sep-0012.md index 54c248d73..93f40db41 100644 --- a/ecosystem/sep-0012.md +++ b/ecosystem/sep-0012.md @@ -6,8 +6,8 @@ Title: KYC API Author: Interstellar Status: Active Created: 2018-09-11 -Updated: 2024-01-25 -Version 1.12.0 +Updated: 2024-02-09 +Version 1.13.0 ``` ## Abstract @@ -102,6 +102,7 @@ Name | Type | Description `memo` | string | (optional) the client-generated [memo](https://developers.stellar.org/docs/glossary/transactions/#memo) that uniquely identifies the customer. If a memo is present in the decoded SEP-10 JWT's `sub` value, it must match this parameter value. If a muxed account is used as the JWT's `sub` value, memos sent in requests must match the 64-bit integer subaccount ID of the muxed account. See the [Shared Accounts](#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 should always be of type `id`, although anchors should continue to support this parameter for outdated clients. If `hash`, `memo` should be base64-encoded. If a memo is present in the decoded SEP-10 JWT's `sub` value, this parameter can be ignored. See the [Shared Accounts](#shared-omnibus-or-pooled-accounts) section for more information. `type` | string | (optional) the type of action the customer is being KYCd for. See the [Type Specification](#type-specification) below. +`transaction_id` | `string` | (optional) The transaction id with which the customer's info is associated. When information from the customer depends on the transaction (e.g., more information is required for larger amounts) | `lang` | string | (optional) Defaults to `en`. Language code specified using [ISO 639-1](https://en.wikipedia.org/wiki/ISO_639-1). Human readable descriptions, choices, and messages should be in this language. #### ID vs. Account & Memo @@ -353,13 +354,14 @@ Content-Type: application/json } ``` -Name | Type | Description ------|------|------------ -`id` | string | (optional) The `id` value returned from a previous call to this endpoint. If specified, no other parameter is required. -`account` | `G...` or `M...` string | (**deprecated**, optional) The server should infer the account from the `sub` value in the SEP-10 JWT to identify the customer. The `account` parameter is only used for backwards compatibility, and if explicitly provided in the request body it should match the `sub` value of the decoded SEP-10 JWT. -`memo` | string | (optional) the client-generated [memo](https://developers.stellar.org/docs/glossary/transactions/#memo) that uniquely identifies the customer. If a memo is present in the decoded SEP-10 JWT's `sub` value, it must match this parameter value. If a muxed account is used as the JWT's `sub` value, memos sent in requests must match the 64-bit integer subaccount ID of the muxed account. See the [Shared Accounts](#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 should always be of type `id`, although anchors should continue to support this parameter for outdated clients. If `hash`, `memo` should be base64-encoded. If a memo is present in the decoded SEP-10 JWT's `sub` value, this parameter can be ignored. See the [Shared Accounts](#shared-omnibus-or-pooled-accounts) section for more information. -`type` | string | (optional) The type of the customer as defined in the [Type Specification](#type-specification). +Name | Type | Description +-----|------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- +`id` | string | (optional) The `id` value returned from a previous call to this endpoint. If specified, no other parameter is required. +`account` | `G...` or `M...` string | (**deprecated**, optional) The server should infer the account from the `sub` value in the SEP-10 JWT to identify the customer. The `account` parameter is only used for backwards compatibility, and if explicitly provided in the request body it should match the `sub` value of the decoded SEP-10 JWT. +`memo` | string | (optional) the client-generated [memo](https://developers.stellar.org/docs/glossary/transactions/#memo) that uniquely identifies the customer. If a memo is present in the decoded SEP-10 JWT's `sub` value, it must match this parameter value. If a muxed account is used as the JWT's `sub` value, memos sent in requests must match the 64-bit integer subaccount ID of the muxed account. See the [Shared Accounts](#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 should always be of type `id`, although anchors should continue to support this parameter for outdated clients. If `hash`, `memo` should be base64-encoded. If a memo is present in the decoded SEP-10 JWT's `sub` value, this parameter can be ignored. See the [Shared Accounts](#shared-omnibus-or-pooled-accounts) section for more information. +`type` | string | (optional) The type of the customer as defined in the [Type Specification](#type-specification). +`transaction_id` | `string` | (optional) The transaction id with which the customer's info is associated. When information from the customer depends on the transaction (e.g., more information is required for larger amounts) | The wallet should also transmit one or more of the fields listed in [SEP-9](./sep-0009.md), depending on what the anchor has indicated it needs. @@ -695,6 +697,7 @@ All responses should return `200 OK`. If no files are found for the identifer us ## Changelog +* `v1.13.0`: Add `transaction_id` field to `/customer` `GET` and `PUT` ([#1431](https://github.com/stellar/stellar-protocol/pull/1431)) * `v1.12.0`: Deprecate `PUT /verifcation` and update verification process ([#1431](https://github.com/stellar/stellar-protocol/pull/1431)) * `v1.11.1`: Allow anchors to omit the deprecated `X-Stellar-Signature` header ([#1335](https://github.com/stellar/stellar-protocol/pull/1335)) * `v1.11.0`: Deprecate `X-Stellar-Signature` in favor of `Signature` ([#1333](https://github.com/stellar/stellar-protocol/pull/1333))