diff --git a/ecosystem/sep-0031.md b/ecosystem/sep-0031.md index 55e78fd6c..2293fb205 100644 --- a/ecosystem/sep-0031.md +++ b/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))