ANCHOR-505: Add fee details field to SEP-31 transaction object (#1441)

ecosystem/sep-0031.md

@@ -6,8 +6,8 @@ Title: Cross-Border Payments API
 Author: SDF
 Status: Active
 Created: 2020-04-07
-Updated: 2023-08-31
-Version 2.5.0
+Updated: 2024-02-09
+Version 2.6.0
 ```
 
 ## Simple Summary
@@ -493,8 +493,9 @@ Name | Type | Description
 `amount_in_asset` | string | (optional) The asset received or to be received by the Receiving Anchor. Must be present if `quote_id` or `destination_asset` was included in the `POST /transactions` request. The value must be in [SEP-38 Asset Identification Format](sep-0038.md#asset-identification-format).
 `amount_out` | string | (optional) The amount sent or to be sent by the Receiving Anchor to the Receiving Client. When using a `destination_asset` in the [`POST /transactions`](#post-transactions) request, it's expected that this value is only populated after the Receiving Anchor receives the incoming payment. Should be equals to `quote.buy_amount` if a `quote_id` was used.
 `amount_out_asset` | string | (optional) The asset delivered to the Receiving Client. Must be present if `quote_id` or `destination_asset` was included in the `POST /transactions` request. The value must be in [SEP-38 Asset Identification Format](sep-0038.md#asset-identification-format).
-`amount_fee` | string | (optional) The amount of fee charged by the Receiving Anchor. Should be equals `quote.fee.total` if a `quote_id` was used.
-`amount_fee_asset` | string | (optional) The asset in which fees are calculated in. Must be present if `quote_id` or `destination_asset` was included in the `POST /transactions` request. The value must be in [SEP-38 Asset Identification Format](sep-0038.md#asset-identification-format). Should be equals `quote.fee.asset` if a `quote_id` was used.
+`amount_fee` | string | (**deprecated**, optional) The amount of fee charged by the Receiving Anchor. Should be equals `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 `quote_id` or `destination_asset` was included in the `POST /transactions` request. The value must be in [SEP-38 Asset Identification Format](sep-0038.md#asset-identification-format). Should be equals `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.
 `stellar_account_id` | string | (optional) The Receiving Anchor's Stellar account that the Sending Anchor will be making the payment to.
 `stellar_memo_type` | string | (optional) The type of memo to attach to the Stellar payment: `text`, `hash`, or `id`.
@@ -574,6 +575,24 @@ amount_fee = sum(quote.fee.total)
 amount_fee_asset = quote.fee.asset
 ```
 
+#### Fee Details Object Schema
+
+| Name      | Type   | Description                                                                                                                                                           |
+| --------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `total`   | string | The total amount of fee applied.                                                                                                                                      |
+| `asset`   | string | The asset in which the fee is applied, represented through the [Asset Identification Format](sep-0038.md#asset-identification-format).                                |
+| `details` | array  | (optional) An array of objects detailing the fees that were used to calculate the conversion price. This can be used to datail the price components for the end-user. |
+
+##### Fee Details Details Object Schema
+
+| Name          | Type   | Description                                                                                                                                |
+| ------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| `name`        | string | The name of the fee, for example `ACH fee`, `Brazilian conciliation fee`, `Service fee`, etc.                                              |
+| `description` | string | (optional) A text describing the fee.                                                                                                      |
+| `amount`      | string | The amount of asset applied. If `fee_details.details` is provided, `sum(fee_details.details.amount)` should be equals `fee_details.total`. |
+
+
+
 #### Example response
 
 Pending external (without quotes):
@@ -862,6 +881,7 @@ It is important to note that the Receiving Anchor is not obligated, at least by
 
 ## Changelog
 
+* `v2.6.0`: Add `fee_details` field to the transaction object ([]())
 * `v2.5.0`: Deprecate and make optional the use of per-transaction `fields` objects ([#1387](https://github.com/stellar/stellar-protocol/pull/1387))
 * `v2.4.0`: Add `updated_at` to `GET /transactions/:id` response ([#1336](https://github.com/stellar/stellar-protocol/pull/1336))
 * `v2.3.1`: Allow anchors to omit the deprecated `X-Stellar-Signature` header ([#1335](https://github.com/stellar/stellar-protocol/pull/1335))