Consider introducing a `Cancel` message

[mistermoe]

Context

Per EFTA regulation, consumers have the right to cancel a remittance transfer within 30 minutes after the payin has been sent, so long as the transfer has not yet been picked up by the recipient or deposited into the recipient's account.

If a consumer cancels a remittance transfer within the allowed time frame, the provider must refund the total amount of money paid by the consumer, including any fees, within three business days of receiving the cancellation request.

If we intend for tbDEX to be able to support traditional remittances we need to provide a means through which Alice can submit a cancelation

Proposal

introduce a Cancel message with the following constraints:

• This message kind can only be submitted by Alice
• This message can only be submitted after an Order message and before a Close message. in between OrderStatus messages is fine

Message Data

The data property of a Cancel message would contain:

Field	Type	Description	Required (Y/N)
reason	string	reason for cancelation	N

Cancel Submission

Sending a Cancel message could result in the following responses

202 - Accepted

The Cancel message has been accepted for further processing.

[!IMPORTANT] This does not imply a commitment to refund given the possibility that the payout has already been disbursed but the respective OrderStatus has not yet been added to the exchange

OrderStatus messages that follow after the Cancel message would be used to be provide further context on the status of the cancelation request e.g.

• REFUND_INITIATED - The refund process has been initiated
• CANCEL_DECLINED - cancellation request has been declined. Payout amount has already been disbursed to the recipient.

400 - Bad Request

• Invalid Message
• Exchange has already been closed
• Cancelation has already been submitted
• Cancelation cannot be submitted given the current state of the exchange
• Cancelation Declined. (at the discretion of the PFI)

Backwards Compatibility

Introducing this message kind would result in a version bump of tbdex. as such, submission of a Cancel message to any exchange with a protocol version less than the version that introduces Cancel would result in a 400: Bad Request

Other Considerations

We may want to consider adding an cancelation property to Offering that contains the following:

Field	Type	Description	Required (Y/N)
enabled	boolean	whether cancelation is enabled for the respective offering	Y
terms_url	URI	a link to a page that describes the terms of cancelation	N
terms	string	cancelation terms in plaintext	N

Alternative Approaches

• provide a means through which cancellation can happen out-of-band. An example of this would be to allow for a response to an order message to include a cancelUrl.

[mistermoe]

@nburgess48 lmk if i'm just making things up re: Context in description!

[nburgess48]

You nailed it. LGTM!

[nburgess48]

For the orderStatus messages that follow a Cancel message, do we have an appropriate message to use if the order has been cancelled but funds haven't moved yet? (seems REFUND_INITIATED wouldn't really be appropriate there)

[mistermoe]

great q @nburgess48. what i included in the description above was purely illustrative. If we decide to go forward with adding a Cancel message, i think we should come up with a concrete list of order statuses for this specific use-case. We can include these order statuses in a list of recommended statuses in the spec.

[angiejones]

what use cases do you have in mind that would qualify for Offering.cancelation.enabled = false? Maybe for onramps?

[angiejones]

If Alice cancels, does the exchange remain open until the refund is completed? Or does another exchange kick off?

[jiyoonie9]

@angiejones

what use cases do you have in mind that would qualify for Offering.cancelation.enabled = false? Maybe for onramps?

an example would be a btc purchase where you provide an address. once the btc transfer is initiated, it is not reversible from the original sender.

If Alice cancels, does the exchange remain open until the refund is completed? Or does another exchange kick off?

Yes, the exchange should remain open until the refund is completed. per initial issue wording above:

OrderStatus messages that follow after the Cancel message would be used to be provide further context on the status of the cancelation request e.g.

REFUND_INITIATED - The refund process has been initiated
CANCEL_DECLINED - cancellation request has been declined. Payout amount has already been disbursed to the recipient.

Although these statuses are for illustrative purposes only and we should develop a recommended set of statuses for the refund flow, OrderStatus will continue updating Alice on the status of her refund, until the refund is complete, at which point a Close message can be sent and the exchange is closed.

[jiyoonie9]

working through the PR right now, i think this calls into question how to differentiate between Close and Cancel.

currently, Close can be sent by Alice OR the PFI at any point during the exchange.

does introducing Cancel change how Close works? should we limit Close to only be sent by the PFI? what if Alice wants to nope out of an exchange after she sends an RFQ or receives a Quote?