Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

SEP-31: make destination address & memo optional in POST /transactions response #1294

Merged
merged 8 commits into from
Aug 16, 2022
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Binary file modified contents/sep-0031/state_diagram.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
30 changes: 20 additions & 10 deletions ecosystem/sep-0031.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,3 @@

## Preamble

```
Expand All @@ -7,8 +6,8 @@ Title: Cross-Border Payments API
Author: SDF
Status: Active
Created: 2020-04-07
Updated: 2022-07-20
Version 1.10.0
Updated: 2022-08-12
Version 2.0.0
```

## Simple Summary
Expand Down Expand Up @@ -442,14 +441,22 @@ Name | Type | Description

##### Success (201 Created)

This is the successful case where a Receiving Anchor confirms that they can fulfill this payment as described. The response body should be a JSON object with the following values
This is the successful case where a Receiving Anchor either confirms that they can fulfill this payment as described or that confirmation is pending.

Anchors must check for whether `stellar_account_id`, `stellar_memo`, & `stellar_memo_type` values are present in the response.

If these values are not present, the Receiving Anchor is processing the information sent and determining if the transaction can proceed. In this case, the transaction's status is `pending_receiver` and the Sending Anchor should use monitor the transaction until it's status moves to `pending_sender` or `error`.

When the transaction status moves to `pending_sender`, the Stellar account & memo fields should be populated.

Sending Anchors can monitor the transaction's status by registering a callback URL via [`PUT /transactions/:id/callback`](#put-transaction-callback) or by polling [`GET /transactions/:id`](#get-transaction).

Name | Type | Description
-----|------|------------
`id` | string | The persistent identifier to check the status of this payment transaction.
`stellar_account_id` | string | The Stellar account to send payment to.
`stellar_memo_type` | string | The type of memo to attach to the Stellar payment (`text`, `hash`, or `id`).
`stellar_memo` | string | The memo to attach to the Stellar payment.
`stellar_account_id` | string | (optional) The Stellar account to send payment to.
`stellar_memo_type` | string | (optional) The type of memo to attach to the Stellar payment (`text`, `hash`, or `id`).
`stellar_memo` | string | (optional) The memo to attach to the Stellar payment.

##### Customer Info Needed (400 Bad Request)

Expand Down Expand Up @@ -516,16 +523,17 @@ Name | Type | Description
`id` | string | The ID returned from the `POST /transactions` request that created this transaction record.
`status` | string | The status of the transaction. Values are outlined below.
`status_eta` | number | (optional) The estimated number of seconds until a status change is expected.
`status_message` | string | (optional) A human-readable message describing the status of the transaction.
`amount_in` | string | (optional) The amount of the Stellar asset received or to be received by the Receiving Anchor. Excludes any fees charged after Receiving Anchor receives the funds. If a `quote_id` was used, the `amount_in` should be equals to both: (i) the `amount` value used in the [`POST /transactions`](#post-transactions) request; and (ii) the quote's `sell_amount`.
`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.
`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 | The Receiving Anchor's Stellar account that the Sending Anchor will be making the payment to.
`stellar_memo_type` | string | The type of memo to attach to the Stellar payment: `text`, `hash`, or `id`.
`stellar_memo` | string | The memo to attach to the Stellar payment.
`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`.
`stellar_memo` | string | (optional) The memo to attach to the Stellar payment.
`started_at` | UTC ISO 8601 string | (optional) Start date and time of transaction.
`completed_at` | UTC ISO 8601 string | (optional) Completion date and time of transaction.
`stellar_transaction_id` | string | (optional) The transaction_id on Stellar network of the transfer that initiated the payment.
Expand Down Expand Up @@ -609,6 +617,7 @@ Pending external (without quotes):
"id": "82fhs729f63dh0v4",
"status": "pending_external",
"status_eta": 3600,
"status_message": "Payment has been initiated via ACH deposit.",
"stellar_transaction_id": "b9d0b2292c4e09e8eb22d036171491e87b8d2086bf8b265874c8d182cb9c9020",
"external_transaction_id": "ABCDEFG1234567890",
"stellar_account_id": "GBRPYHIL2CI3FNQ4BXLFMNDLFJUNPU2HY3ZMFSHONUCEOASW7QC7OX2H",
Expand Down Expand Up @@ -884,6 +893,7 @@ It is important to note that the Receiving Anchor is not obligated, at least by

## Changelog

* `v2.0.0`: Make `stellar_account_id`, `stellar_memo`, & `stellar_memo_type` optional in the `POST /transactions` response. Add the `status_message` attribute to `GET /transactions/:id`. ([#1294](https://github.com/stellar/stellar-protocol/pull/1294))
* `v1.10.0`: Add `quote_id` to the transaction object schema. ([#1268](https://github.com/stellar/stellar-protocol/pull/1268))
* `v1.9.0`: Add callback signature requirement. ([#1264](https://github.com/stellar/stellar-protocol/pull/1264))
* `v1.8.0`: Add `expired` transaction status. ([#1233](https://github.com/stellar/stellar-protocol/pull/1233))
Expand Down